@sniper.ai/core 2.0.0 → 3.1.0

package/framework/commands/sniper-ingest.md

@@ -1,506 +0,0 @@
-# /sniper-ingest -- Codebase Ingestion (Parallel Team)
-
-You are executing the `/sniper-ingest` command. Your job is to spawn a parallel team that reverse-engineers planning artifacts from an existing codebase. 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. If any check fails, STOP and report the issue.
-
-### 0a. Verify SNIPER Is Initialized
-
-1. Read `.sniper/config.yaml`.
-2. If the file does not exist or `project.name` is empty:
-   - **STOP.** Print: "SNIPER is not initialized. Run `/sniper-init` first."
-   - Do not proceed further.
-
-### 0b. Config Migration Check
-
-1. Read `schema_version` from `.sniper/config.yaml`.
-2. If `schema_version` is absent or less than 2, run the v1→v2 migration as defined in the Config Reader Protocol (see `plans/features/phase-a-config-schema.md`). Write the updated config before proceeding.
-
-### 0c. Parse Arguments
-
-1. **`--scope`:** If provided (e.g., `--scope "src/api/ src/models/"`), validate that each listed directory exists. If any directory does not exist, print a warning but continue with the directories that do exist. Store the scope list for Step 4.
-2. **`--update`:** If provided, force amendment mode regardless of whether artifacts already exist.
-
-### 0d. Verify Phase State
-
-1. Determine the current active phase: find the last entry in `state.phase_log` where `completed_at` is null.
-2. **If no active phase (all completed or empty log):** Good -- proceed.
-3. **If active phase is `ingest`:** The ingest phase is already in progress.
-   - Ask the user: "An ingest phase is already in progress ({context}). Options: (a) Resume it (b) Start a new ingestion"
-   - If resume, STOP (they should continue in the existing session).
-4. **If active phase is something else** (discover, plan, solve, sprint):
-   - Ask the user: "You have an active {phase} phase ({context}) that hasn't completed. Options: (a) Pause it and start ingest (b) Complete {phase} first"
-   - If (b), STOP.
-
-### 0e. Amendment Detection
-
-1. Check if the target artifact files already exist and are non-empty:
-   - `docs/brief.md`
-   - `docs/architecture.md`
-   - `docs/conventions.md`
-2. **If ANY exist AND `--update` was NOT passed:**
-   - Ask the user: "The following artifacts already exist: {list}. Options: (a) Amend existing artifacts (b) Overwrite from scratch (c) Cancel"
-   - If (a): Enter amendment mode. Note which files exist and their current version numbers.
-   - If (b): Normal create mode. Agents will overwrite.
-   - If (c): STOP.
-3. **If `--update` was passed:** Enter amendment mode for any artifacts that exist.
-4. **If NONE exist:** Normal create mode.
-
-### 0f. Verify Framework Files
-
-Check that these files exist (they are needed by the team):
-- `.sniper/teams/ingest.yaml`
-- `.sniper/spawn-prompts/_template.md`
-- `.sniper/checklists/ingest-review.md`
-- `.sniper/personas/process/code-archaeologist.md`
-- `.sniper/personas/process/architecture-cartographer.md`
-- `.sniper/personas/process/convention-miner.md`
-- `.sniper/personas/cognitive/systems-thinker.md`
-- `.sniper/templates/brief.md`
-- `.sniper/templates/architecture.md`
-- `.sniper/templates/conventions.md`
-
-If any are missing, print a warning listing the missing files but continue if at least the team YAML exists.
-
----
-
-## Step 1: Update Lifecycle State
-
-Edit `.sniper/config.yaml` to update the state section:
-
-1. Append to `state.phase_log`:
-   ```yaml
-   - phase: ingest
-     context: "{scope if --scope provided, otherwise 'full-codebase'}{' (update)' if amendment mode}"
-     started_at: "{current ISO timestamp}"
-     completed_at: null
-     approved_by: null
-   ```
-
----
-
-## Step 2: Read Team Definition
-
-1. Read `.sniper/teams/ingest.yaml` in full.
-2. Parse out:
-   - `team_name` (should be `sniper-ingest`)
-   - The list of `teammates` with their `name`, `compose` layers, and `tasks`
-   - The `coordination` rules (should be empty -- all tasks are independent)
-   - The `review_gate` section (checklist path and mode)
-3. Store these values for subsequent steps.
-
----
-
-## Step 3: Read Project Context
-
-Gather the context that teammates will need:
-
-1. Read `.sniper/config.yaml` fully -- extract `project.name`, `project.description`, `project.type`, `stack`, and `ownership` sections.
-2. Get the project's directory tree by listing top-level directories and key files. If `--scope` was provided, focus the tree listing on those directories.
-3. Read `package.json` / `pyproject.toml` / `Cargo.toml` (whichever exists) -- this gives agents dependency context.
-4. If `README.md` exists, note its location for agents to read.
-
----
-
-## Step 4: Compose Spawn Prompts
-
-For each teammate in the team YAML, compose a spawn prompt by assembling persona layers. Do this by reading the actual persona files and assembling them into the template.
-
-### Teammate: code-archaeologist
-
-1. Read these persona layer files:
-   - Process: `.sniper/personas/process/code-archaeologist.md`
-   - Technical: SKIP (null in team YAML)
-   - Cognitive: `.sniper/personas/cognitive/systems-thinker.md`
-
-2. Read the spawn prompt template: `.sniper/spawn-prompts/_template.md`
-
-3. Assemble the spawn prompt by filling the template:
-   - `{name}` = "code-archaeologist"
-   - `{process_layer}` = contents of the process persona file
-   - `{technical_layer}` = "No specific technical lens for this role."
-   - `{cognitive_layer}` = contents of the cognitive persona file
-   - `{domain_layer}` = "No domain pack configured."
-   - `{ownership}` = the `docs` ownership paths from `config.yaml`
-
-4. Append to the spawn prompt:
-   ```
-   ## Your Task
-   **Task ID:** project-brief
-   **Task Name:** Reverse-engineer Project Brief
-   **Output File:** docs/brief.md
-   **Template:** .sniper/templates/brief.md
-
-   {task description from the team YAML}
-
-   ## Project Context
-   - **Project:** {project.name}
-   - **Type:** {project.type}
-   - **Description:** {project.description}
-   - **Stack:** {summary of stack section}
-   {if --scope: "- **Scope:** Only analyze these directories: {scope list}"}
-
-   ## Key Files to Read
-   - `package.json` / `pyproject.toml` / `Cargo.toml` (project metadata, dependencies)
-   - `README.md` (if exists)
-   - Top-level directory structure
-   - Key entry points (`src/index.ts`, `src/main.py`, `app/`, etc.)
-   - CI/CD configs (`.github/workflows/`, `Dockerfile`, etc.)
-   - Environment files (`.env.example`, NOT `.env`)
-
-   ## Instructions (Create Mode -- when docs/brief.md does NOT exist)
-   1. Read the template at `.sniper/templates/brief.md` to understand the expected output format.
-   2. Read the codebase to understand what this project does, what problem it solves, and who uses it.
-   3. Produce the artifact at `docs/brief.md` following the template exactly.
-   4. This is a REVERSE-ENGINEERING exercise: describe what IS, not what SHOULD BE.
-   5. For sections you cannot infer from code, write "Unable to determine from codebase analysis."
-   6. Every section in the template MUST be filled -- no empty sections.
-   7. When complete, message the team lead that your task is done.
-
-   ## Instructions (Amendment Mode -- when docs/brief.md already exists)
-   1. Read the EXISTING artifact at `docs/brief.md` first. Note its current version number.
-   2. Read the template at `.sniper/templates/brief.md` to understand the expected format.
-   3. AMEND the existing brief: update sections that need changes, add new information, preserve content outside managed sections (<!-- sniper:managed --> markers).
-   4. Increment the version number in the header (e.g., v1 -> v2).
-   5. Add a changelog entry describing what changed.
-   6. Set Status back to "Draft" (even if it was previously "Approved").
-   7. When complete, message the team lead that your task is done.
-   ```
-
-5. Save this composed prompt as a variable for spawning.
-
-### Teammate: architecture-cartographer
-
-1. Read these persona layer files:
-   - Process: `.sniper/personas/process/architecture-cartographer.md`
-   - Technical: `.sniper/personas/technical/backend.md`
-   - Cognitive: `.sniper/personas/cognitive/systems-thinker.md`
-
-2. Assemble using the same template pattern:
-   - `{name}` = "architecture-cartographer"
-   - `{technical_layer}` = contents of the backend technical persona
-   - `{ownership}` = the `docs` ownership paths
-
-3. Append task context:
-   ```
-   ## Your Task
-   **Task ID:** system-architecture
-   **Task Name:** Reverse-engineer System Architecture
-   **Output File:** docs/architecture.md
-   **Template:** .sniper/templates/architecture.md
-
-   {task description from the team YAML}
-
-   ## Project Context
-   - **Project:** {project.name}
-   - **Type:** {project.type}
-   - **Description:** {project.description}
-   - **Stack:** {summary of stack section}
-   {if --scope: "- **Scope:** Only analyze these directories: {scope list}"}
-
-   ## Key Files to Read
-   - Full directory tree (to map component boundaries)
-   - Database schemas / migrations / ORM models
-   - API route definitions (Express routes, FastAPI endpoints, etc.)
-   - Configuration files (database connections, cache, queue configs)
-   - Infrastructure files (Docker, Terraform, K8s manifests)
-   - Key service files (to understand component responsibilities)
-   - Dependency graph (imports between modules)
-
-   ## Instructions (Create Mode)
-   1. Read the template at `.sniper/templates/architecture.md` to understand the expected output format.
-   2. Map the complete technical architecture from the source code.
-   3. Produce a component diagram (ASCII or Mermaid) of the system AS BUILT.
-   4. Document data models with actual field names, types, and relationships.
-   5. Document API contracts with actual endpoint paths, methods, and request/response shapes.
-   6. Note technical debt and inconsistencies: "Pattern inconsistency found: {detail}".
-   7. Do NOT hallucinate components -- only document what you can trace to actual code.
-   8. Write the output to `docs/architecture.md` following the template exactly.
-   9. When complete, message the team lead that your task is done.
-
-   ## Instructions (Amendment Mode)
-   1. Read the EXISTING artifact at `docs/architecture.md` first. Note its current version number.
-   2. Read the template at `.sniper/templates/architecture.md` to understand the expected format.
-   3. AMEND the existing architecture: update components, data models, APIs that have changed. Preserve content outside managed sections.
-   4. Increment the version number in the header.
-   5. Add a changelog entry describing what changed.
-   6. Set Status back to "Draft".
-   7. When complete, message the team lead that your task is done.
-   ```
-
-### Teammate: convention-miner
-
-1. Read these persona layer files:
-   - Process: `.sniper/personas/process/convention-miner.md`
-   - Technical: SKIP (null)
-   - Cognitive: `.sniper/personas/cognitive/systems-thinker.md`
-
-2. Assemble using the same template pattern:
-   - `{name}` = "convention-miner"
-   - `{technical_layer}` = "No specific technical lens for this role."
-   - `{ownership}` = ALL ownership paths (this agent updates them)
-
-3. Append task context:
-   ```
-   ## Your Task
-   **Task ID:** conventions
-   **Task Name:** Extract Coding Conventions
-   **Output File:** docs/conventions.md AND updates to .sniper/config.yaml (ownership section)
-   **Template:** .sniper/templates/conventions.md
-
-   {task description from the team YAML}
-
-   ## Project Context
-   - **Project:** {project.name}
-   - **Type:** {project.type}
-   - **Description:** {project.description}
-   - **Stack:** {summary of stack section}
-   {if --scope: "- **Scope:** Only analyze these directories: {scope list}"}
-
-   ## Key Files to Read
-   - Linter/formatter configs: `.eslintrc*`, `.prettierrc*`, `tsconfig*`, `ruff.toml`, `pyproject.toml`
-   - At least 5-10 representative source files from different parts of the codebase
-   - Test files (to understand test patterns)
-   - The full directory tree (to update ownership paths)
-
-   ## Instructions (Create Mode)
-   1. Read the template at `.sniper/templates/conventions.md` to understand the expected output format.
-   2. Sample multiple files (at least 5-10) from different directories.
-   3. For each convention category, identify the dominant pattern (appears in 80%+ of relevant files).
-   4. Every convention MUST cite a real code example with file path and code snippet.
-   5. If patterns are inconsistent, document BOTH patterns and note the inconsistency.
-   6. Write the output to `docs/conventions.md` following the template exactly.
-   7. ALSO update `.sniper/config.yaml` ownership section:
-      - Read the actual project directory structure.
-      - Replace the template default ownership paths with paths that match the real project layout.
-      - Categorize directories into: backend, frontend, shared, infrastructure, tests, docs.
-      - Only include directories that actually exist.
-   8. When complete, message the team lead that your task is done.
-
-   ## Instructions (Amendment Mode)
-   1. Read the EXISTING artifact at `docs/conventions.md` first. Note its current version number.
-   2. Read the template at `.sniper/templates/conventions.md` to understand the expected format.
-   3. AMEND the existing conventions: update patterns that have changed, add newly discovered conventions, preserve content outside managed sections.
-   4. Re-check the `.sniper/config.yaml` ownership paths and update if the directory structure has changed.
-   5. Increment the version number in the header.
-   6. Add a changelog entry describing what changed.
-   7. Set Status back to "Draft".
-   8. When complete, message the team lead that your task is done.
-   ```
-
----
-
-## Step 5: Create the Agent Team
-
-Use the TeamCreate tool to create the team:
-
-```
-TeamCreate:
-  team_name: "sniper-ingest"
-  description: "SNIPER Codebase Ingestion for {project.name}"
-```
-
----
-
-## Step 6: Create Tasks in the Shared Task List
-
-Create one task per teammate using TaskCreate. All tasks are independent -- no dependencies.
-
-### Task 1: Project Brief
-
-```
-TaskCreate:
-  subject: "Reverse-engineer Project Brief"
-  description: "Read the codebase and produce docs/brief.md capturing what this project does, what problem it solves, who uses it, and its current scope. Focus on what IS, not what SHOULD BE. Follow template at .sniper/templates/brief.md."
-  activeForm: "Reverse-engineering project brief from codebase"
-```
-
-### Task 2: System Architecture
-
-```
-TaskCreate:
-  subject: "Reverse-engineer System Architecture"
-  description: "Map the complete technical architecture from source code. Produce docs/architecture.md with component diagrams, data models, API contracts, infrastructure topology, and cross-cutting concerns. Document the system AS BUILT. Follow template at .sniper/templates/architecture.md."
-  activeForm: "Mapping system architecture from source code"
-```
-
-### Task 3: Coding Conventions
-
-```
-TaskCreate:
-  subject: "Extract Coding Conventions"
-  description: "Analyze the codebase to extract coding conventions with real code examples. Produce docs/conventions.md AND update .sniper/config.yaml ownership paths to match actual project structure. Follow template at .sniper/templates/conventions.md."
-  activeForm: "Extracting coding conventions and patterns"
-```
-
-No dependencies between tasks -- all three run in parallel.
-
----
-
-## 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-ingest"
-- `name`: the teammate name from the YAML (code-archaeologist, architecture-cartographer, convention-miner)
-- The full composed spawn prompt as the instruction
-
-Spawn all three teammates. They will work in parallel on their independent tasks.
-
-After spawning, assign each task to its corresponding teammate using TaskUpdate with the `owner` field:
-- Task 1 (Project Brief) -> owner: "code-archaeologist"
-- Task 2 (System Architecture) -> owner: "architecture-cartographer"
-- Task 3 (Coding Conventions) -> owner: "convention-miner"
-
-Mark each task as `in_progress` via TaskUpdate.
-
----
-
-## Step 8: Enter Delegate Mode
-
-**You are now the team lead. You do NOT produce artifacts.**
-
-Your responsibilities during execution:
-1. Monitor task progress via TaskList
-2. Respond to teammate messages (questions, blockers, completion notifications)
-3. If a teammate asks about project structure or where to find files, provide guidance from the project context
-4. If a teammate finishes early, acknowledge their completion and update their task status to `completed`
-5. Track which teammates have completed their work
-
-**Do NOT:**
-- Write to `docs/brief.md`, `docs/architecture.md`, or `docs/conventions.md` yourself
-- Modify teammate artifacts
-- Analyze the codebase yourself
-
-Wait for all three teammates to report completion.
-
----
-
-## Step 9: Verify Artifacts Exist
-
-Once all three teammates report completion:
-
-1. Verify these files exist and are non-empty:
-   - `docs/brief.md`
-   - `docs/architecture.md`
-   - `docs/conventions.md`
-
-2. Verify the ownership section in `.sniper/config.yaml` has been updated (paths should not match the template defaults unless the project happens to use the default structure).
-
-3. If any file is missing or empty, message the responsible teammate and ask them to complete it.
-
-4. Do NOT proceed to Step 10 until all three files exist and contain content.
-
----
-
-## Step 10: Run Review Gate
-
-Read the review gate configuration from the team YAML: `review_gate.mode` and `review_gate.checklist`.
-
-1. Read the review checklist at `.sniper/checklists/ingest-review.md`.
-2. For each checklist item, perform a quick evaluation by reading the relevant artifact and checking if the item is addressed.
-3. Compile a review summary with:
-   - Total checklist items
-   - Items that PASS
-   - Items that NEED ATTENTION (not fully met but not blocking)
-   - Items that FAIL (critical gaps)
-
-### Gate Decision
-
-The ingest gate mode is **flexible**:
-
-- **If there are no FAIL items:** Auto-advance. Print the review summary and note any NEED ATTENTION items for async review.
-- **If there are FAIL items:** Present the failures to the user and ask:
-  > "The ingestion review found {N} critical issues. Would you like to:
-  > 1. Have the team fix the issues (I will message the relevant teammates)
-  > 2. Override and advance anyway
-  > 3. Stop and review manually"
-
-  If option 1: Message the relevant teammates with specific feedback, wait for fixes, then re-run the checklist.
-  If option 2: Proceed with a note that issues were overridden.
-  If option 3: STOP and let the user handle it.
-
----
-
-## Step 11: Update State and Shut Down Team
-
-### Update Lifecycle State
-
-Edit `.sniper/config.yaml`:
-
-1. Update artifact tracking (increment version if amendment mode):
-   - Set `state.artifacts.brief.status: draft` and increment `state.artifacts.brief.version`
-   - Set `state.artifacts.architecture.status: draft` and increment `state.artifacts.architecture.version`
-   - Set `state.artifacts.conventions.status: draft` and increment `state.artifacts.conventions.version`
-2. Update the ingest entry in `state.phase_log` to add `completed_at: "{current ISO timestamp}"`
-3. If auto-advanced (flexible gate passed), set `approved_by: "auto-flexible"`
-
-### Shut Down Teammates
-
-Send a shutdown request to each teammate:
-- Send shutdown_request to "code-archaeologist"
-- Send shutdown_request to "architecture-cartographer"
-- Send shutdown_request to "convention-miner"
-
-Wait for all teammates to acknowledge shutdown.
-
----
-
-## Step 12: Present Results and Next Steps
-
-Print a formatted summary:
-
-```
-============================================
-  SNIPER Codebase Ingestion Complete
-============================================
-
-  Artifacts Produced:
-    - docs/brief.md          [draft] {v1 or vN}
-    - docs/architecture.md   [draft] {v1 or vN}
-    - docs/conventions.md    [draft] {v1 or vN}
-
-  Config Updated:
-    - ownership paths updated to match project structure
-
-  Review Gate: FLEXIBLE
-    Passed: {count}/{total} checklist items
-    Attention: {count} items flagged for async review
-    Failed: {count} critical issues
-
-  Phase Duration: {time elapsed}
-
-============================================
-  Next Steps
-============================================
-
-  1. Review the ingested artifacts in `docs/`
-  2. These artifacts provide the foundation for:
-     - /sniper-feature  -- add incremental features using the architecture as reference
-     - /sniper-discover -- run discovery if you want market/risk/persona analysis
-     - /sniper-plan     -- run planning if you want a PRD and UX spec
-     - /sniper-audit    -- audit the codebase using the architecture as baseline
-  3. Run /sniper-status to see the full lifecycle state
-
-============================================
-```
-
----
-
-## IMPORTANT RULES
-
-- You are the LEAD. You coordinate. You do NOT write artifact files.
-- All three teammates work in PARALLEL -- do not serialize their work.
-- If `$ARGUMENTS` contains "dry-run", perform Steps 0-4 only (compose prompts) and print them without spawning. This lets the user review prompts before execution.
-- If `$ARGUMENTS` contains "skip-review", skip Step 10 and go straight to Step 11.
-- If a teammate crashes or becomes unresponsive after 10 minutes of no messages, report the issue to the user and offer to respawn that specific teammate.
-- All file paths are relative to the project root.
-- Do NOT proceed to other phases automatically -- always let the user initiate the next command.
-- The convention-miner modifies `.sniper/config.yaml` (ownership section only). This is the ONLY case where a teammate modifies config. Warn the team lead to verify the ownership update after completion.