Overview

Guide users through a structured workflow for collaboratively writing documents, proposals, specs, and decision docs. Uses a three-stage process: context gathering, iterative refinement, and reader testing.

Getting Started

Add your source materials to the project workspace, then activate the Doc Co-Authoring skill. The agent will guide you through the process step by step.

Example Conversation

You: I want to write a one-pager decision doc for migrating our auth to OAuth2. Can we do the structured workflow?

Agent: Sure. We’ll do three stages: (1) Context gathering — I’ll ask about audience, impact, and any template; (2) Refinement — we’ll build each section with brainstorming and edits; (3) Reader testing — we’ll check if a fresh reader can answer key questions from the doc. To start: Who’s the primary audience? What should they do after reading it? Any existing template or format?

You: Audience is eng leads and security. Goal: get a go/no-go. No template — just clear sections.

Agent: I’ll suggest: Context & problem, Options considered, Recommendation, Risks & mitigation, Next steps. We’ll start with “Options considered” and “Recommendation” since those have the most unknowns. Dump any context you have (constraints, past discussions, why not other options); I’ll ask follow-ups, then we’ll brainstorm and draft section by section. Ready for your context dump.

You: [Provides context.]

Agent: I’ve created decision-doc-auth-oauth2.md with placeholders. Starting with the Recommendation section: here are 8 possible bullets based on what you shared. Which do you want to keep, remove, or combine? [Lists options.] Once you choose, I’ll draft that section and we’ll iterate.

Sample Output Excerpt

Below is a representative excerpt from a decision document produced with the co-authoring workflow.

Decision: Migrate Authentication to OAuth2

Context and problem

Current cookie-based auth does not support mobile and third-party integrations. We need a standard, maintainable auth layer that works across web, mobile, and API clients.

Options considered

Recommendation

Adopt OAuth2 with OpenID Connect for identity. Use [Provider X] for issuance and our existing user store. Phase 1: web and API; Phase 2: mobile. Timeline: 8 weeks to pilot, 12 weeks to full rollout.

Risks and mitigation

• Risk: Token revocation and session invalidation. Mitigation: Short-lived access tokens, refresh rotation, and revocation endpoint by Phase 2.
• Risk: Key rotation. Mitigation: Automated rotation and dual-key support during handover.

Next steps

1. Security sign-off on provider and flow (Week 1).
2. Implement issuer and integrate with web app (Weeks 2–6).
3. Pilot with internal API consumers (Weeks 7–8).