/sniper-doc -- Generate or Update Project Documentation (Parallel Team)

You are executing the /sniper-doc command. Your job is to spawn a documentation team that analyzes the project, generates documentation, and validates it. You are the team lead -- you coordinate, you do NOT produce artifacts yourself. Follow every step below precisely.

Arguments: $ARGUMENTS

Step 0: Pre-Flight Checks

Perform ALL of the following checks before proceeding. Adjust behavior based on what exists.

0a. Detect Project Mode

Check if .sniper/config.yaml exists and project.name is not empty.
If config exists (SNIPER project):
- Set mode = sniper
- Read state.artifacts to see which artifacts exist (brief, PRD, architecture, etc.)
- These artifacts are primary sources for documentation generation
If config does not exist (standalone project):
- Set mode = standalone
- The team will infer everything from the codebase itself
- Check for common project files: package.json, Cargo.toml, pyproject.toml, go.mod, pom.xml
- If none found, STOP and print: "No project metadata found. Cannot generate documentation for an empty directory."

0b. Check Existing Documentation

Check if README.md exists at the project root.
Check if docs/ directory exists and what files are in it.
If documentation already exists, default to update mode (preserve manual edits via managed sections).
If no documentation exists, default to generate mode (full generation).

0c. Verify Framework Files (SNIPER mode only)

Check that these files exist:

.sniper/teams/doc.yaml
.sniper/spawn-prompts/_template.md
.sniper/checklists/doc-review.md
.sniper/personas/process/doc-analyst.md
.sniper/personas/process/doc-writer.md
.sniper/personas/process/doc-reviewer.md
.sniper/personas/cognitive/user-empathetic.md
.sniper/personas/cognitive/mentor-explainer.md
.sniper/personas/cognitive/devils-advocate.md

If any are missing, print a warning listing the missing files but continue if at least the team YAML exists.

Step 1: Determine Documentation Scope

Ask the user what documentation they want to generate. Present a selection prompt:

Documentation Mode:
Generate new docs (full generation)
Update existing docs (incremental — preserves manual edits)
What to generate: (select all that apply)
README.md
Setup guide (docs/setup.md)
Architecture overview (docs/architecture.md)
API reference (docs/api.md)
Contributing guide (CONTRIBUTING.md)
Security policy (SECURITY.md)
Changelog (CHANGELOG.md)
Deployment guide (docs/deployment.md)
UI/Component guide (docs/ui-guide.md)

If $ARGUMENTS contains "all", skip the prompt and generate everything. If $ARGUMENTS contains specific doc types (e.g., "readme api setup"), generate only those. If $ARGUMENTS contains "update", force update mode.

Store the user's selections for the team.

Step 2: Read Team Definition

Read .sniper/teams/doc.yaml in full.
Parse out:
- team_name (should be sniper-doc)
- The list of teammates with their name, compose layers, and tasks
- The coordination rules (analyst → writer handoff)
- The review_gate section (checklist path and mode)
Store these values for subsequent steps.

Step 3: Read Project Context

Gather the context that teammates will need:

SNIPER mode:
- Read .sniper/config.yaml fully — extract project.name, project.description, project.type, stack, domain_packs, and ownership sections.
- If domain_packs is not empty, read domain pack context files.
- Check which SNIPER artifacts exist in docs/: brief.md, prd.md, architecture.md, ux-spec.md, security.md, epics/, stories/
- Read the relevant templates: doc-readme.md, doc-guide.md, doc-api.md
Standalone mode:
- Read project metadata from package.json / Cargo.toml / pyproject.toml / go.mod
- Scan the project structure (top 3 levels of directories)
- Identify key source directories, test directories, config files
- Read the relevant templates: doc-readme.md, doc-guide.md, doc-api.md

Step 4: Compose Spawn Prompts

For each teammate in the team YAML, compose a spawn prompt by assembling persona layers.

Teammate: doc-analyst

Read these persona layer files:
- Process: .sniper/personas/process/doc-analyst.md
- Technical: SKIP (null in team YAML)
- Cognitive: .sniper/personas/cognitive/user-empathetic.md
- Domain: If domain_packs is set, read domain context. Otherwise skip.
Read the spawn prompt template: .sniper/spawn-prompts/_template.md
Assemble the spawn prompt by filling the template:
- {name} = "doc-analyst"
- {process_layer} = contents of doc-analyst.md
- {technical_layer} = "No specific technical lens for this role."
- {cognitive_layer} = contents of user-empathetic.md
- {domain_layer} = domain context if available, otherwise "No domain pack configured."
- {ownership} = the docs ownership paths from config.yaml (or ["docs/", "README.md"] in standalone mode)

Append to the spawn prompt:

## Your Task
**Task ID:** analyze-project
**Task Name:** Analyze Project Structure & Artifacts
**Output File:** docs/.sniper-doc-index.json
**Mode:** {sniper | standalone}

Scan the entire project and produce a documentation index. The user has requested
these doc types: {list of selected doc types from Step 1}.

Documentation mode: {generate | update}

{If update mode:}
Check existing documentation files for `<!-- sniper:managed:start -->` tags.
Note which docs have managed sections and which are fully manual.

## Project Context
- **Project:** {project.name or inferred name}
- **Type:** {project.type or inferred type}
- **Description:** {project.description or inferred description}
- **Stack:** {summary of stack section or inferred stack}

## Instructions
1. Scan the project root and src/ directories to map the codebase structure.
2. If SNIPER artifacts exist (docs/brief.md, docs/prd.md, docs/architecture.md, etc.), inventory them as source material.
3. Identify API routes/endpoints, models/schemas, config files, Docker files, and test files.
4. For each requested doc type, determine if it: exists and is current, exists but is stale, or is missing.
5. Write the doc index to `docs/.sniper-doc-index.json`.
6. When complete, message the team lead that your task is done.

Teammate: doc-writer

Read these persona layer files:
- Process: .sniper/personas/process/doc-writer.md
- Technical: Read the technical persona matching the project's primary stack. If stack.backend is node-express, use backend.md. If stack.frontend is react, use frontend.md. In standalone mode, infer from the project. If unclear, skip.
- Cognitive: .sniper/personas/cognitive/mentor-explainer.md
- Domain: Same as doc-analyst.
Assemble using the same template pattern:
- {name} = "doc-writer"
- {ownership} = the docs ownership paths plus README.md, CONTRIBUTING.md, SECURITY.md, CHANGELOG.md

Append task context for write-readme:

## Your Tasks

### Task 1: Generate README.md
**Task ID:** write-readme
**Output File:** README.md
**Template:** .sniper/templates/doc-readme.md

Write the project README. Read the doc index at docs/.sniper-doc-index.json first
to understand available sources. Follow the template structure.

{If update mode:}
The README already exists. Only modify content within `<!-- sniper:managed:start -->`
and `<!-- sniper:managed:end -->` tags. Preserve everything outside those tags.
If no managed tags exist, treat the entire file as manual and append new content
inside managed tags at the end.

### Task 2: Generate Documentation Guides
**Task ID:** write-guides
**Output Files:** docs/{selected guides}
**Template:** .sniper/templates/doc-guide.md (for general guides), .sniper/templates/doc-api.md (for API reference)

Generate the following documentation files: {list of selected doc types minus README}.
Read the doc index for source material. Follow templates.

{If update mode:}
For existing docs, respect managed section boundaries. For new docs, wrap all
content in managed tags.

## Instructions
1. Wait for the doc-analyst to complete the doc index.
2. Read `docs/.sniper-doc-index.json` to understand what sources are available.
3. For README: read the doc-readme template, read source materials, write README.md.
4. For each guide: read the appropriate template, read source materials, write the file.
5. Every code example must come from or be verified against the actual codebase.
6. When both tasks are complete, message the team lead.

Teammate: doc-reviewer

Read these persona layer files:
- Process: .sniper/personas/process/doc-reviewer.md
- Technical: SKIP (null)
- Cognitive: .sniper/personas/cognitive/devils-advocate.md
- Domain: SKIP (null)
Assemble using the same template pattern:
- {name} = "doc-reviewer"
- {ownership} = ["docs/"]

Append task context:

## Your Task
**Task ID:** review-docs
**Task Name:** Review & Validate Documentation
**Output File:** docs/.sniper-doc-review.md

Review all generated documentation for accuracy and completeness.

## Instructions
1. Wait for the doc-writer to complete all documentation.
2. Read every generated documentation file.
3. Cross-reference code examples against the actual codebase.
4. Verify shell commands reference real scripts and binaries.
5. Check internal links between docs.
6. Check that setup instructions produce a working environment.
7. Write the review report to docs/.sniper-doc-review.md.
8. When complete, message the team lead with a summary (pass/fail count).

Step 5: Create the Agent Team

Use the TeamCreate tool to create the team:

TeamCreate:
  team_name: "sniper-doc"
  description: "SNIPER Documentation: Generate/update docs for {project name}"

Step 6: Create Tasks in the Shared Task List

Create tasks with dependencies matching the team YAML.

Task 1: Analyze Project

TaskCreate:
  subject: "Analyze Project Structure & Artifacts"
  description: "Scan the codebase and SNIPER artifacts. Produce documentation index at docs/.sniper-doc-index.json. Determine what docs exist, what's missing, what's stale."
  activeForm: "Analyzing project structure"

Task 2: Generate README

TaskCreate:
  subject: "Generate README.md"
  description: "Write the project README from artifacts and codebase analysis. Follow doc-readme template. Output: README.md"
  activeForm: "Writing README.md"

Set dependency: blocked_by Task 1.

Task 3: Generate Documentation Guides

TaskCreate:
  subject: "Generate Documentation Guides"
  description: "Generate selected documentation files (setup, architecture, API, deployment, etc.) based on doc index. Output: docs/ directory"
  activeForm: "Writing documentation guides"

Set dependency: blocked_by Task 1.

Task 4: Review Documentation

TaskCreate:
  subject: "Review & Validate Documentation"
  description: "Review all generated docs for accuracy, completeness, consistency. Verify code examples, links, and setup instructions. Output: docs/.sniper-doc-review.md"
  activeForm: "Reviewing documentation"

Set dependency: blocked_by Task 2 AND Task 3.

Step 7: Spawn Teammates

Spawn each teammate using the Task tool. Use the composed spawn prompts from Step 4.

For each teammate, spawn using:

team_name: "sniper-doc"
name: the teammate name from the YAML (doc-analyst, doc-writer, doc-reviewer)
The full composed spawn prompt as the instruction

Spawn all three teammates. The doc-analyst works first (unblocked), the doc-writer waits for the index, and the doc-reviewer waits for the writer.

After spawning, assign each task to its corresponding teammate using TaskUpdate with the owner field:

Task 1 (Analyze Project) -> owner: "doc-analyst"
Task 2 (Generate README) -> owner: "doc-writer"
Task 3 (Generate Guides) -> owner: "doc-writer"
Task 4 (Review Docs) -> owner: "doc-reviewer"

Mark Task 1 as in_progress. Tasks 2, 3, 4 remain pending (blocked).

Step 8: Enter Delegate Mode

You are now the team lead. You do NOT produce artifacts.

Your responsibilities during execution:

Monitor task progress via TaskList
When doc-analyst completes, unblock Tasks 2 and 3 — message doc-writer that the index is ready
When doc-writer completes both tasks, unblock Task 4 — message doc-reviewer to begin review
Respond to teammate messages (questions, blockers, completion notifications)
Track which teammates have completed their work

Do NOT:

Write any documentation files yourself
Modify teammate artifacts
Analyze the codebase yourself

Wait for all teammates to report completion.

Step 9: Verify Artifacts Exist

Once all teammates report completion:

Verify docs/.sniper-doc-index.json exists and is valid JSON.
Verify each requested documentation file exists and is non-empty.
Verify docs/.sniper-doc-review.md exists.
If any file is missing or empty, message the responsible teammate and ask them to complete it.
Do NOT proceed to Step 10 until all files exist.

Step 10: Run Review Gate

Read the review gate configuration from the team YAML: review_gate.mode and review_gate.checklist.

Read the review report at docs/.sniper-doc-review.md (produced by the doc-reviewer).
Read the review checklist at .sniper/checklists/doc-review.md.
Cross-reference the review report with the checklist.
Compile a gate summary.

Gate Decision

The doc gate mode is flexible:

If there are no FAIL items in the review report: Auto-advance. Print the summary.
If there are FAIL items: Present the failures to the user and ask:
"The documentation review found {N} critical issues. Would you like to:
1. Have the writer fix the issues
2. Accept the docs as-is
3. Stop and fix manually"
If option 1: Message doc-writer with the specific failures, wait for fixes, then re-run review. If option 2: Proceed. If option 3: STOP.

Step 11: Clean Up and Shut Down Team

Remove Temporary Files

The docs/.sniper-doc-index.json file is an intermediate artifact. Ask the user if they want to keep it (useful for future incremental updates) or delete it.

Shut Down Teammates

Send a shutdown request to each teammate:

Send shutdown_request to "doc-analyst"
Send shutdown_request to "doc-writer"
Send shutdown_request to "doc-reviewer"

Wait for all teammates to acknowledge shutdown.

Step 12: Present Results

Print a formatted summary:

============================================
  SNIPER Doc: Documentation Complete
============================================

  Mode: {sniper | standalone}
  Action: {generate | update}

  Files Generated/Updated:
    - README.md                 [generated | updated]
    - docs/setup.md             [generated | updated | skipped]
    - docs/architecture.md      [generated | updated | skipped]
    - docs/api.md               [generated | updated | skipped]
    - ...

  Review:
    Passed: {count}/{total} checks
    Warnings: {count}
    Critical: {count}

============================================
  Documentation is ready for review.
  Run `/sniper-doc update` anytime to refresh.
============================================

IMPORTANT RULES

You are the LEAD. You coordinate. You do NOT write documentation yourself.
The doc-analyst MUST complete before the doc-writer starts.
The doc-writer MUST complete before the doc-reviewer starts.
If $ARGUMENTS contains "dry-run", perform Steps 0-4 only (compose prompts) and print them without spawning.
If $ARGUMENTS contains "skip-review", skip the doc-reviewer teammate entirely (only spawn analyst and writer).
/sniper-doc does NOT modify lifecycle state in config.yaml — it is a utility, not a phase.
In update mode, NEVER overwrite content outside  tags.
All file paths are relative to the project root.
This command works regardless of current lifecycle phase — it can run during discover, plan, or sprint.

/sniper-doc -- Generate or Update Project Documentation (Parallel Team) ​

Step 0: Pre-Flight Checks ​

0a. Detect Project Mode ​

0b. Check Existing Documentation ​

0c. Verify Framework Files (SNIPER mode only) ​

Step 1: Determine Documentation Scope ​

Step 2: Read Team Definition ​

Step 3: Read Project Context ​

Step 4: Compose Spawn Prompts ​

Teammate: doc-analyst ​

Teammate: doc-writer ​

Teammate: doc-reviewer ​

Step 5: Create the Agent Team ​

Step 6: Create Tasks in the Shared Task List ​

Task 1: Analyze Project ​

Task 2: Generate README ​

Task 3: Generate Documentation Guides ​

Task 4: Review Documentation ​

Step 7: Spawn Teammates ​

Step 8: Enter Delegate Mode ​

Step 9: Verify Artifacts Exist ​

Step 10: Run Review Gate ​

Gate Decision ​

Step 11: Clean Up and Shut Down Team ​

Remove Temporary Files ​

Shut Down Teammates ​

Step 12: Present Results ​

IMPORTANT RULES ​