@thierrynakoa/fire-flow 10.0.0

package/commands/fire-map-codebase.md

@@ -0,0 +1,313 @@
+---
+description: Analyze codebase with parallel mapper agents to produce structured documentation
+---
+
+# /fire-map-codebase
+
+> Analyze existing codebase using parallel agents to produce structured codebase documents
+
+---
+
+## Purpose
+
+Analyze existing codebase using parallel fire-codebase-mapper agents to produce structured codebase documents. Each mapper agent explores a focus area and **writes documents directly** to `.planning/codebase/`. The orchestrator only receives confirmations, keeping context usage minimal.
+
+**Output:** `.planning/codebase/` folder with 7 structured documents about the codebase state.
+
+---
+
+## Arguments
+
+```yaml
+arguments:
+  focus_area:
+    required: false
+    type: string
+    description: "Optional area to focus mapping on (e.g., 'api', 'auth', 'database')"
+    example: "/fire-map-codebase auth"
+```
+
+---
+
+## When to Use
+
+**Use /fire-map-codebase for:**
+- Brownfield projects before initialization (understand existing code first)
+- Refreshing codebase map after significant changes
+- Onboarding to an unfamiliar codebase
+- Before major refactoring (understand current state)
+- When CONSCIENCE.md references outdated codebase info
+- Before `/fire-0-orient` when joining existing project
+
+**Skip /fire-map-codebase for:**
+- Greenfield projects with no code yet (nothing to map)
+- Trivial codebases (<5 files)
+
+---
+
+## Process
+
+### Step 1: Check Existing Map
+
+```bash
+ls .planning/codebase/*.md 2>/dev/null | wc -l
+```
+
+**If codebase documents exist:**
+
+Use AskUserQuestion:
+- header: "Existing Map"
+- question: "Codebase map already exists. What would you like to do?"
+- options:
+  - "Refresh all (Recommended)" - Re-analyze entire codebase
+  - "Refresh specific area" - Only update one focus area
+  - "Skip" - Keep existing map
+
+### Step 2: Create Directory Structure
+
+```bash
+mkdir -p .planning/codebase
+```
+
+### Step 3: Display Spawning Banner
+
+```
++------------------------------------------------------------------------------+
+| FIRE MAP CODEBASE                                                            |
++------------------------------------------------------------------------------+
+|                                                                              |
+|  Spawning 4 parallel mapper agents...                                        |
+|                                                                              |
+|    -> Agent 1: Tech focus (STACK.md, INTEGRATIONS.md)                        |
+|    -> Agent 2: Architecture focus (ARCHITECTURE.md, STRUCTURE.md)            |
+|    -> Agent 3: Quality focus (CONVENTIONS.md, TESTING.md)                    |
+|    -> Agent 4: Concerns focus (CONCERNS.md)                                  |
+|                                                                              |
+|  Focus area: {focus_area or "entire codebase"}                               |
+|                                                                              |
++------------------------------------------------------------------------------+
+```
+
+### Step 4: Spawn Parallel Mapper Agents
+
+**Agent 1: Tech Focus**
+```
+Task(prompt="
+<focus>tech</focus>
+<area>{focus_area or 'all'}</area>
+
+<instructions>
+Analyze the codebase for technology stack and integrations.
+
+Write these files:
+1. .planning/codebase/STACK.md
+   - Languages and versions
+   - Frameworks and libraries
+   - Build tools and bundlers
+   - Runtime environments
+
+2. .planning/codebase/INTEGRATIONS.md
+   - External APIs consumed
+   - Third-party services
+   - Database connections
+   - Message queues / event systems
+
+Use template structure. Write files directly.
+Return: 'TECH MAPPING COMPLETE' with line counts.
+</instructions>
+", subagent_type="fire-codebase-mapper", description="Map tech stack")
+```
+
+**Agent 2: Architecture Focus**
+```
+Task(prompt="
+<focus>arch</focus>
+<area>{focus_area or 'all'}</area>
+
+<instructions>
+Analyze the codebase for architecture and structure.
+
+Write these files:
+1. .planning/codebase/ARCHITECTURE.md
+   - System architecture overview
+   - Component boundaries
+   - Data flow patterns
+   - Key abstractions
+
+2. .planning/codebase/STRUCTURE.md
+   - Directory organization
+   - Module boundaries
+   - Entry points
+   - Configuration locations
+
+Use template structure. Write files directly.
+Return: 'ARCH MAPPING COMPLETE' with line counts.
+</instructions>
+", subagent_type="fire-codebase-mapper", description="Map architecture")
+```
+
+**Agent 3: Quality Focus**
+```
+Task(prompt="
+<focus>quality</focus>
+<area>{focus_area or 'all'}</area>
+
+<instructions>
+Analyze the codebase for conventions and testing.
+
+Write these files:
+1. .planning/codebase/CONVENTIONS.md
+   - Naming conventions
+   - Code style patterns
+   - Error handling patterns
+   - Logging patterns
+
+2. .planning/codebase/TESTING.md
+   - Test framework(s)
+   - Test organization
+   - Coverage areas
+   - Testing patterns
+
+Use template structure. Write files directly.
+Return: 'QUALITY MAPPING COMPLETE' with line counts.
+</instructions>
+", subagent_type="fire-codebase-mapper", description="Map quality patterns")
+```
+
+**Agent 4: Concerns Focus**
+```
+Task(prompt="
+<focus>concerns</focus>
+<area>{focus_area or 'all'}</area>
+
+<instructions>
+Analyze the codebase for technical debt and concerns.
+
+Write this file:
+1. .planning/codebase/CONCERNS.md
+   - Technical debt identified
+   - Security considerations
+   - Performance bottlenecks
+   - Maintainability issues
+   - Missing documentation
+   - Deprecated patterns
+
+Use template structure. Write file directly.
+Return: 'CONCERNS MAPPING COMPLETE' with line counts.
+</instructions>
+", subagent_type="fire-codebase-mapper", description="Map concerns")
+```
+
+### Step 5: Verify Completion
+
+Wait for all 4 agents. Verify all 7 documents exist:
+
+```bash
+for doc in STACK INTEGRATIONS ARCHITECTURE STRUCTURE CONVENTIONS TESTING CONCERNS; do
+  [ -f ".planning/codebase/${doc}.md" ] && echo "OK: ${doc}.md" || echo "MISSING: ${doc}.md"
+done
+```
+
+Count lines in each document.
+
+### Step 6: Commit Codebase Map
+
+```bash
+git add .planning/codebase/
+git commit -m "$(cat <<'EOF'
+docs: map codebase structure
+
+Generated 7 codebase documents:
+- STACK.md: Technology stack
+- INTEGRATIONS.md: External integrations
+- ARCHITECTURE.md: System architecture
+- STRUCTURE.md: Directory organization
+- CONVENTIONS.md: Code conventions
+- TESTING.md: Test patterns
+- CONCERNS.md: Technical debt
+
+Focus: {focus_area or 'entire codebase'}
+EOF
+)"
+```
+
+### Step 7: Sabbath Rest - Context Persistence
+
+Update persistent state:
+
+```markdown
+## .claude/dominion-flow.local.md
+
+### Codebase Map
+- Generated: {timestamp}
+- Focus: {focus_area or 'entire codebase'}
+- Documents: 7
+- Location: .planning/codebase/
+```
+
+---
+
+## Output Documents
+
+| Document | Contents |
+|----------|----------|
+| `STACK.md` | Languages, frameworks, dependencies, build tools |
+| `INTEGRATIONS.md` | External APIs, services, databases, queues |
+| `ARCHITECTURE.md` | System design, components, data flow |
+| `STRUCTURE.md` | Directory layout, modules, entry points |
+| `CONVENTIONS.md` | Code style, patterns, naming |
+| `TESTING.md` | Test framework, organization, coverage |
+| `CONCERNS.md` | Tech debt, security, performance issues |
+
+---
+
+## Completion Display
+
+```
++------------------------------------------------------------------------------+
+| CODEBASE MAPPING COMPLETE                                                    |
++------------------------------------------------------------------------------+
+|                                                                              |
+|  Documents created in .planning/codebase/:                                   |
+|                                                                              |
+|    STACK.md          {lines} lines - Technology stack                        |
+|    INTEGRATIONS.md   {lines} lines - External integrations                   |
+|    ARCHITECTURE.md   {lines} lines - System architecture                     |
+|    STRUCTURE.md      {lines} lines - Directory organization                  |
+|    CONVENTIONS.md    {lines} lines - Code conventions                        |
+|    TESTING.md        {lines} lines - Test patterns                           |
+|    CONCERNS.md       {lines} lines - Technical debt                          |
+|                                                                              |
+|  Commit: {hash}                                                              |
+|                                                                              |
++------------------------------------------------------------------------------+
+| NEXT UP                                                                      |
++------------------------------------------------------------------------------+
+|                                                                              |
+|  -> Run `/fire-1-new` to initialize project with this context               |
+|  -> Or run `/fire-0-orient` if joining an existing project                  |
+|  -> Or run `/fire-2-plan` to start planning with codebase knowledge         |
+|                                                                              |
++------------------------------------------------------------------------------+
+```
+
+---
+
+## Success Criteria
+
+- [ ] `.planning/codebase/` directory created
+- [ ] All 7 codebase documents written by mapper agents
+- [ ] Documents follow template structure
+- [ ] Parallel agents completed without errors
+- [ ] Changes committed to git
+- [ ] Sabbath Rest state updated
+- [ ] User knows next steps
+
+---
+
+## References
+
+- **Agent:** Uses `fire-codebase-mapper` agent (parallel exploration)
+- **Related:** `/fire-0-orient` - Uses codebase map for orientation
+- **Related:** `/fire-1-new` - Uses codebase map for project initialization
+- **Brand:** `@references/ui-brand.md`

package/commands/fire-new-milestone.md

@@ -0,0 +1,356 @@
+---
+description: Start a new milestone cycle with questioning, research, requirements, and roadmap
+---
+
+# /fire-new-milestone
+
+> Start a new milestone through unified flow: questioning -> research -> requirements -> roadmap
+
+---
+
+## Purpose
+
+Start a new milestone for an existing project. This is the brownfield equivalent of `/fire-1-new`. The project exists, PROJECT.md has history. This command gathers "what's next" and takes you through the full cycle.
+
+**Creates/Updates:**
+- `.planning/PROJECT.md` - Updated with new milestone goals
+- `.planning/research/` - Domain research (optional)
+- `.planning/REQUIREMENTS.md` - Scoped requirements
+- `.planning/VISION.md` - Phase structure
+- `.planning/CONSCIENCE.md` - Updated project memory
+
+**After this command:** Run `/fire-2-plan [N]` to start execution.
+
+---
+
+## Arguments
+
+```yaml
+arguments:
+  milestone_name:
+    required: false
+    type: string
+    description: "Optional milestone name (e.g., 'v1.1 Notifications')"
+    example: "/fire-new-milestone v1.1 Notifications"
+```
+
+---
+
+## Process
+
+### Phase 1: Validate Project
+
+**MANDATORY FGTAT STEP - Execute these checks before ANY user interaction:**
+
+```bash
+[ -f .planning/PROJECT.md ] || { echo "ERROR: No PROJECT.md. Run /fire-1-new first."; exit 1; }
+```
+
+Check for active milestone (VISION.md exists):
+
+```bash
+[ -f .planning/VISION.md ] && echo "ACTIVE_MILESTONE" || echo "READY_FOR_NEW"
+```
+
+**If ACTIVE_MILESTONE:**
+
+Use AskUserQuestion:
+- header: "Active Milestone"
+- question: "A milestone is in progress. What would you like to do?"
+- options:
+  - "Complete current first (Recommended)" - Run /fire-complete-milestone
+  - "Continue anyway" - Start new milestone (will archive current)
+
+### Phase 2: Present Context
+
+Display banner:
+
+```
++------------------------------------------------------------------------------+
+| DOMINION FLOW > NEW MILESTONE                                                   |
++------------------------------------------------------------------------------+
+```
+
+Present what shipped:
+
+```
+Last milestone: v[X.Y] [Name] (shipped [DATE])
+
+Key accomplishments:
+- [From MILESTONES.md]
+- [From MILESTONES.md]
+
+Validated requirements:
+- [From PROJECT.md Validated section]
+
+Pending todos:
+- [From CONSCIENCE.md if any]
+```
+
+### Phase 3: Deep Questioning
+
+Display banner:
+
+```
++------------------------------------------------------------------------------+
+| DOMINION FLOW > QUESTIONING                                                     |
++------------------------------------------------------------------------------+
+```
+
+**Open the conversation:**
+
+Ask inline (freeform, NOT AskUserQuestion):
+
+"What do you want to build next?"
+
+Wait for response. This gives context for intelligent follow-up questions.
+
+**Follow the thread:**
+
+Based on their response, ask follow-up questions that dig deeper. Use AskUserQuestion with options that probe what they mentioned.
+
+Keep following threads. Each answer opens new threads to explore:
+- What excited them
+- What problem sparked this
+- What they mean by vague terms
+- What it would actually look like
+- What's already decided
+
+**WARRIOR Enhancement - Honesty Protocol:**
+
+Before finalizing understanding, acknowledge:
+- What I understand clearly
+- What I'm uncertain about
+- What I'm assuming
+
+**Decision gate:**
+
+When ready, use AskUserQuestion:
+- header: "Ready?"
+- question: "I think I understand what you're after. Ready to update PROJECT.md?"
+- options:
+  - "Update PROJECT.md" - Move forward
+  - "Keep exploring" - Share more / ask more
+
+### Phase 4: Determine Milestone Version
+
+Parse last version from MILESTONES.md and suggest next:
+
+Use AskUserQuestion:
+- header: "Version"
+- question: "What version is this milestone?"
+- options:
+  - "v[X.Y+0.1] (patch)" - Minor update
+  - "v[X+1].0 (major)" - Major release
+  - "Custom" - I'll specify
+
+### Phase 5: Update PROJECT.md
+
+Update `.planning/PROJECT.md` with new milestone section:
+
+```markdown
+## Current Milestone: v[X.Y] [Name]
+
+**Goal:** [One sentence describing milestone focus]
+
+**Target features:**
+- [Feature 1]
+- [Feature 2]
+- [Feature 3]
+```
+
+Commit:
+
+```bash
+git add .planning/PROJECT.md
+git commit -m "$(cat <<'EOF'
+docs: start milestone v[X.Y] [Name]
+
+[One-liner describing milestone focus]
+EOF
+)"
+```
+
+### Phase 6: Research Decision
+
+Use AskUserQuestion:
+- header: "Research"
+- question: "Research the domain ecosystem before defining requirements?"
+- options:
+  - "Research first (Recommended)" - Discover patterns, expected features
+  - "Skip research" - I know this domain well
+
+**If "Research first":**
+
+Display banner:
+```
++------------------------------------------------------------------------------+
+| DOMINION FLOW > RESEARCHING                                                     |
++------------------------------------------------------------------------------+
+
+Researching [domain] ecosystem...
+```
+
+Spawn 4 parallel fire-project-researcher agents:
+- Stack research
+- Features research
+- Architecture research
+- Pitfalls research
+
+After completion, spawn synthesizer to create RECORD.md.
+
+**Adversarial Fact-Check (v11.0):**
+After the synthesizer writes SYNTHESIS.md, spawn `fire-fact-checker`:
+- Reads SYNTHESIS.md
+- Independently attempts to disprove top findings
+- Produces `.planning/research/CONTESTED-CLAIMS.md`
+- Adjusts confidence levels based on adversarial verification
+- Any CONTESTED findings are flagged for the roadmapper's risk assessment
+
+```
+Spawning fire-fact-checker for adversarial verification...
+```
+
+### Phase 7: Define Requirements
+
+Display banner:
+```
++------------------------------------------------------------------------------+
+| DOMINION FLOW > DEFINING REQUIREMENTS                                           |
++------------------------------------------------------------------------------+
+```
+
+**If research exists:** Read FEATURES.md and present by category.
+
+**If no research:** Gather requirements through conversation.
+
+**Scope each category:**
+
+For each category, use AskUserQuestion with multiSelect:
+- header: "[Category name]"
+- question: "Which [category] features are in this milestone?"
+- options: [Feature list]
+
+**Generate REQUIREMENTS.md:**
+
+Create `.planning/REQUIREMENTS.md` with:
+- v1 Requirements grouped by category (checkboxes, REQ-IDs)
+- v2 Requirements (deferred)
+- Out of Scope (explicit exclusions)
+- Traceability section
+
+Commit:
+
+```bash
+git add .planning/REQUIREMENTS.md
+git commit -m "$(cat <<'EOF'
+docs: define v[X.Y] requirements
+
+[X] requirements across [N] categories
+[Y] requirements deferred to v2
+EOF
+)"
+```
+
+### Phase 8: Create Roadmap
+
+Display banner:
+```
++------------------------------------------------------------------------------+
+| DOMINION FLOW > CREATING ROADMAP                                                |
++------------------------------------------------------------------------------+
+
+Spawning roadmapper...
+```
+
+Spawn fire-roadmapper agent with context:
+- PROJECT.md
+- REQUIREMENTS.md
+- Research RECORD.md (if exists)
+- Starting phase number
+
+**Handle roadmapper return:**
+
+**If `## ROADMAP CREATED`:**
+- Present roadmap inline
+- Ask for approval
+
+**If approved:** Commit roadmap.
+
+### Phase 9: Sabbath Rest - Context Persistence
+
+Update persistent state:
+
+```markdown
+## .claude/dominion-flow.local.md
+
+### Current Milestone
+- Version: v[X.Y]
+- Name: [Name]
+- Phases: [count]
+- Requirements: [count]
+- Started: {timestamp}
+- Status: Ready to plan
+- Next: /fire-2-plan [first_phase]
+```
+
+---
+
+## Completion Display
+
+```
++------------------------------------------------------------------------------+
+| DOMINION FLOW > MILESTONE INITIALIZED                                           |
++------------------------------------------------------------------------------+
+|                                                                              |
+|  v[X.Y] [Name]                                                               |
+|                                                                              |
+|  | Artifact       | Location                    |                            |
+|  |----------------|-----------------------------                             |
+|  | Project        | .planning/PROJECT.md        |                            |
+|  | Research       | .planning/research/         |                            |
+|  | Requirements   | .planning/REQUIREMENTS.md   |                            |
+|  | Roadmap        | .planning/VISION.md        |                            |
+|                                                                              |
+|  [N] phases | [X] requirements | Ready to build                             |
+|                                                                              |
++------------------------------------------------------------------------------+
+| NEXT UP                                                                      |
++------------------------------------------------------------------------------+
+|                                                                              |
+|  Phase [N]: [Phase Name] - [Goal]                                            |
+|                                                                              |
+|  -> Run `/fire-1a-discuss [N]` to gather context and clarify approach       |
+|  -> Or run `/fire-2-plan [N]` to plan directly                              |
+|                                                                              |
+|  Tip: Run `/clear` first for fresh context window                            |
+|                                                                              |
++------------------------------------------------------------------------------+
+```
+
+---
+
+## Success Criteria
+
+- [ ] Project validated (PROJECT.md exists)
+- [ ] Previous milestone context presented
+- [ ] Deep questioning completed (threads followed)
+- [ ] Honesty protocol applied (acknowledged uncertainties)
+- [ ] Milestone version determined
+- [ ] PROJECT.md updated -> committed
+- [ ] Research completed (if selected) -> committed
+- [ ] REQUIREMENTS.md created with REQ-IDs -> committed
+- [ ] VISION.md created -> committed
+- [ ] Sabbath Rest state updated
+- [ ] User knows next step is `/fire-2-plan [N]`
+
+---
+
+## References
+
+- **Related:** `/fire-1-new` - Initialize new project (greenfield)
+- **Related:** `/fire-complete-milestone` - Archive completed milestone
+- **Related:** `/fire-1a-discuss` - Discuss phase before planning
+- **Agent:** Uses `fire-roadmapper` for roadmap creation
+- **Agent:** Uses `fire-project-researcher` for domain research
+- **Brand:** `@references/ui-brand.md`