forge-dev-framework 1.0.1 → 1.1.0

package/.claude/commands/forge/debug.md

@@ -0,0 +1,173 @@
+---
+name: forge:debug
+description: Systematic debugging with persistent state across context resets
+argument-hint: [issue description]
+allowed-tools:
+  - Read
+  - Bash
+  - Task
+  - AskUserQuestion
+---
+
+<objective>
+Debug issues using scientific method with subagent isolation.
+
+**Orchestrator role:** Gather symptoms, spawn debugger agent, handle checkpoints, spawn continuations.
+
+**Why subagent:** Investigation burns context fast (reading files, forming hypotheses, testing). Fresh 200k context per investigation. Main context stays lean for user interaction.
+</objective>
+
+<execution_context>
+@state/STATE.json
+@CLAUDE.md
+</execution_context>
+
+<context>
+**User's Issue:** $ARGUMENTS
+
+**Debug Workflow:**
+1. Check for active debug sessions
+2. Gather symptoms (expected, actual, errors, timeline, reproduction)
+3. Spawn debugger agent
+4. Handle checkpoints and continuations
+5. Confirm root cause before fixing
+</context>
+
+<process>
+**Execute debug workflow:**
+
+1. **Check Active Sessions**
+   ```bash
+   find .planning/debug -name "*.md" -type f 2>/dev/null | grep -v resolved | head -5
+   ```
+
+   If active sessions exist AND no $ARGUMENTS:
+   - List sessions with status, hypothesis, next action
+   - User picks number to resume OR describes new issue
+
+   If $ARGUMENTS provided OR user describes new issue:
+   - Continue to symptom gathering
+
+2. **Gather Symptoms** (if new issue)
+   Use AskUserQuestion for each:
+   - **Expected behavior:** What should happen?
+   - **Actual behavior:** What happens instead?
+   - **Error messages:** Any errors? (paste or describe)
+   - **Timeline:** When did this start? Ever worked?
+   - **Reproduction:** How do you trigger it?
+
+   After gathering, confirm ready to investigate.
+
+3. **Create Debug Session**
+   - Generate slug from issue description
+   - Create debug file: `.planning/debug/{slug}.md`
+   - Initialize with symptom data
+
+4. **Spawn Debugger Agent**
+   Fill prompt and spawn:
+   ```markdown
+   <objective>
+   Investigate issue: {slug}
+
+   **Summary:** {trigger}
+   </objective>
+
+   <symptoms>
+   expected: {expected}
+   actual: {actual}
+   errors: {errors}
+   reproduction: {reproduction}
+   timeline: {timeline}
+   </symptoms>
+
+   <mode>
+   symptoms_prefilled: true
+   goal: find_and_fix
+   </mode>
+
+   <debug_file>
+   Create: .planning/debug/{slug}.md
+   </debug_file>
+   ```
+
+   Spawn with Task tool:
+   ```
+   Task(
+     prompt=filled_prompt,
+     subagent_type="general-purpose",
+     description="Debug {slug}"
+   )
+   ```
+
+5. **Handle Agent Return**
+
+   **If `## ROOT CAUSE FOUND`:**
+   - Display root cause and evidence summary
+   - Offer options:
+     - "Fix now" - spawn fix subagent or fix directly
+     - "Plan fix" - suggest `forge plan <phase>`
+     - "Manual fix" - done
+
+   **If `## CHECKPOINT REACHED`:**
+   - Present checkpoint details to user
+   - Get user response
+   - Spawn continuation agent
+
+   **If `## INVESTIGATION INCONCLUSIVE`:**
+   - Show what was checked and eliminated
+   - Offer options:
+     - "Continue investigating" - spawn new agent
+     - "Manual investigation" - done
+     - "Add more context" - gather more symptoms
+
+6. **Spawn Continuation Agent** (after checkpoint)
+   When user responds to checkpoint, spawn fresh agent:
+   ```markdown
+   <objective>
+   Continue debugging {slug}. Evidence is in the debug file.
+   </objective>
+
+   <prior_state>
+   Debug file: @.planning/debug/{slug}.md
+   </prior_state>
+
+   <checkpoint_response>
+   **Type:** {checkpoint_type}
+   **Response:** {user_response}
+   </checkpoint_response>
+
+   <mode>
+   goal: find_and_fix
+   </mode>
+   ```
+
+7. **Submit Event**
+   - Event type: DEBUG_SESSION_CREATED or DEBUG_RESOLVED
+   - Include: issueSlug, status, rootCause (if found)
+   - Write to state/events/
+
+8. **Update Debug File**
+   - Mark as resolved if root cause found
+   - Rename to `{slug}.resolved.md`
+</process>
+
+<deliverables>
+- .planning/debug/{slug}.md (debug session file)
+- Root cause identified (or investigation results)
+- Event: DEBUG_SESSION_CREATED/RESOLVED in state/events/
+- Optional: Fix applied with atomic commit
+</deliverables>
+
+<success_criteria>
+- [ ] Active sessions checked
+- [ ] Symptoms gathered (if new)
+- [ ] Debugger spawned with context
+- [ ] Checkpoints handled correctly
+- [ ] Root cause confirmed before fixing
+</success_criteria>
+
+<next_steps>
+- If root cause found: Fix now or plan fix
+- If inconclusive: Continue investigating or manual investigation
+- Check progress: `forge status`
+</next_steps>

package/.claude/commands/forge/discuss.md

@@ -0,0 +1,125 @@
+---
+name: forge:discuss
+description: Capture project context and identify gray areas for a specific phase. Use when user says "forge discuss <phase>" or wants to gather context before planning.
+argument-hint: <phase-name>
+allowed-tools:
+  - Read
+  - Write
+  - AskUserQuestion
+---
+
+<objective>
+Gather project context through adaptive questioning for a specific phase, identifying gray areas and knowledge gaps before planning.
+
+Purpose: Capture domain knowledge, requirements, constraints, and acceptance criteria.
+Output: Context document (.planning/phases/<phase>/CONTEXT.md) with captured information.
+</objective>
+
+<execution_context>
+**Load these files NOW:**
+
+- @CLAUDE.md (FORGE patterns and conventions)
+- @ROADMAP.md (Milestone and phase breakdown)
+- @REQUIREMENTS.md (Project requirements)
+- @state/STATE.json (Current project state)
+</execution_context>
+
+<context>
+**Phase:** $ARGUMENTS (e.g., "M2-planning-engine", "api-integration", "frontend-auth")
+**Target:** Context capture before planning
+
+**Context Areas to Explore:**
+- Domain knowledge and constraints
+- Technical requirements and NFRs
+- Dependencies and integrations
+- Acceptance criteria and success metrics
+- Risks and unknowns
+- File ownership boundaries
+</context>
+
+<process>
+**Execute context capture workflow:**
+
+1. **Initialize Context Session**
+   ```bash
+   mkdir -p .planning/phases/<phase-name>
+   touch .planning/phases/<phase-name>/CONTEXT.md
+   ```
+
+2. **Adaptive Questioning**
+   - Ask targeted questions based on phase type
+   - Explore dependencies and integration points
+   - Identify gray areas requiring research
+   - Capture constraints and preferences
+
+3. **Question Categories:**
+
+   **For Backend/API Phases:**
+   - API contracts and endpoints
+   - Data models and schemas
+   - Authentication/authorization
+   - Performance requirements
+   - External dependencies
+
+   **For Frontend/UI Phases:**
+   - Component hierarchy
+   - State management approach
+   - Design system and patterns
+   - User interaction flows
+   - Accessibility requirements
+
+   **For Infrastructure Phases:**
+   - Deployment architecture
+   - CI/CD requirements
+   - Monitoring and observability
+   - Security and compliance
+   - Scalability constraints
+
+4. **Document Context**
+   ```markdown
+   # <Phase Name> Context
+
+   ## Overview
+   [Purpose and goals]
+
+   ## Requirements
+   - Functional requirements
+   - Non-functional requirements
+
+   ## Constraints
+   - Technical constraints
+   - Time/resource constraints
+
+   ## Dependencies
+   - Internal dependencies
+   - External services
+
+   ## Gray Areas
+   - Items requiring research
+   - Unknowns to investigate
+
+   ## Acceptance Criteria
+   - Success metrics
+   - Definition of done
+   ```
+
+5. **State Update**
+   - Submit PHASE_CONTEXT_CAPTURED event
+   - Update STATE.json with phase context
+
+6. **Handoff to Planning**
+   - Offer `forge plan <phase>` to generate tasks
+   - Identify research needs (use research agents)
+</process>
+
+<deliverables>
+- .planning/phases/<phase>/CONTEXT.md (captured context)
+- Event: PHASE_CONTEXT_CAPTURED in state/events/
+- STATE.json updated with phase status
+</deliverables>
+
+<next_steps>
+- Run `forge plan <phase>` to generate atomic task breakdown
+- Use research agents for gray areas
+- Proceed to task execution with agent teams
+</next_steps>

package/.claude/commands/forge/execute.md

@@ -0,0 +1,160 @@
+---
+name: forge:execute
+description: Execute all tasks in a phase with agent team coordination and parallel execution. Use when user says "forge execute <phase>" or wants to run a planned phase.
+argument-hint: <phase-name>
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Task
+  - SendMessage
+---
+
+<objective>
+Execute all tasks in a phase using agent teams with wave-based parallelization, contract-first protocol, and atomic commits.
+
+Purpose: Execute planned tasks with multi-agent coordination.
+Output: All tasks complete, verified, integrated, and committed.
+</objective>
+
+<execution_context>
+**Load these files NOW:**
+
+- @CLAUDE.md (Wipe protocol, atomic commits, file ownership)
+- @.planning/phases/<phase>/PLAN.md (Task list and dependencies)
+- @.planning/phases/<phase>/CONTEXT.md (Phase context)
+- @state/STATE.json (Current state)
+- @contracts/ (API contracts)
+</execution_context>
+
+<context>
+**Phase:** $ARGUMENTS
+**Execution Mode:** Wave-based parallelization
+**Protocol:** Wipe Protocol (fresh agent context per task)
+
+**Execution Constraints:**
+- One task = one git commit (atomic)
+- Agents write only within owned paths
+- Contracts required before cross-domain work
+- Worktree isolation for parallel tasks
+</context>
+
+<process>
+**Execute phase with agent teams:**
+
+1. **Load Plan**
+   - Read PLAN.md for task list
+   - Build dependency graph
+   - Identify parallel execution waves
+
+2. **Create Agent Team**
+   ```bash
+   forge deploy <phase>
+   # Spawns team with specialists based on plan
+   ```
+
+3. **Wave-Based Execution**
+
+   **Wave 1:** Tasks with no dependencies (parallel)
+   ```
+   Spawn agents for:
+   - api-001 → backend-agent
+   - core-001 → core-engine
+   - ui-001 → frontend-agent
+   ```
+
+   **Wave 2:** Tasks after Wave 1 complete
+   ```
+   - api-002 → backend-agent (depends on api-001)
+   - ui-002 → frontend-agent (depends on ui-001)
+   ```
+
+   **Wave 3+:** Continue until all tasks complete
+
+4. **Per-Task Execution** (Wipe Protocol)
+   ```
+   For each task:
+   a. Hydrate: Agent reads CLAUDE.md + STATE.json + task + contracts
+   b. Execute: Agent writes code, runs tests
+   c. Commit: Atomic git commit (one task = one commit)
+   d. Verify: Run acceptance tests
+   e. Terminate: Agent context wiped
+   ```
+
+5. **Contract-First Coordination**
+   ```
+   If agent needs interface from another domain:
+   - Write REQUEST_CONTRACT event
+   - Provider publishes contract to contracts/
+   - Both work against agreed contract
+   - Integration at merge time
+   ```
+
+6. **State Updates**
+   - Each agent submits events to state/events/
+   - State Steward merges events → STATE.json
+   - Progress tracked in real-time
+
+7. **Integration & Verification**
+   - Run integration tests
+   - Verify end-to-end flows
+   - Check requirements coverage
+   - Create VERIFICATION.md
+
+8. **Completion**
+   - All tasks marked complete in STATE.json
+   - Phase marked done
+   - Git tag created: forge/<phase>-complete
+   - Summary generated
+</process>
+
+<deliverables>
+- All tasks complete and verified
+- Git commits (one per task) with conventional format
+- .planning/phases/<phase>/VERIFICATION.md
+- Updated state/STATE.json
+- state/events/ with all task events
+- Integration tests passing
+</deliverables>
+
+<atomic_commit_format>
+Each commit follows conventional format:
+```
+type(scope): description
+
+Examples:
+feat(api-003): implement session authentication
+fix(ui-002): resolve login form validation bug
+test(core-001): add database integration tests
+```
+</atomic_commit_format>
+
+<wipe_protocol>
+**Per-Task Context Lifecycle:**
+1. Hydrate → Load CLAUDE.md + STATE.json + task + contracts
+2. Execute → Write code, run tests
+3. Commit → Atomic git commit
+4. Terminate → Session ends, context wiped
+5. Reincarnate → Next task starts fresh
+
+This prevents hallucination carry-over and context rot.
+</wipe_protocol>
+
+<verification>
+After execution completes:
+- ✅ All tasks marked complete
+- ✅ All tests passing
+- ✅ Integration tests pass
+- ✅ Requirements verified
+- ✅ One commit per task
+- ✅ Conventional commit format
+- ✅ No merge conflicts
+- ✅ Files within ownership boundaries
+</verification>
+
+<next_steps>
+- Run `forge status` to confirm completion
+- Review VERIFICATION.md for details
+- Proceed to next phase or milestone
+- Archive phase with `forge archive <phase>`
+</next_steps>

package/.claude/commands/forge/generate.md

@@ -0,0 +1,120 @@
+---
+name: forge:generate
+description: Generate a specific FORGE artifact from templates. Use when user says "forge generate <artifact>" to create CLAUDE.md, REQUIREMENTS.md, etc.
+argument-hint: <artifact-name> [-f]
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+---
+
+<objective>
+Generate specific FORGE artifacts from templates, including CLAUDE.md, REQUIREMENTS.md, ROADMAP.md, PLAN.md, config files, and rule files.
+
+Purpose: Create or update FORGE artifacts with project-specific content.
+Output: Generated artifact file with validated content.
+</objective>
+
+<execution_context>
+**Load these files NOW:**
+
+- @src/commands/generate.ts (Generate command implementation)
+- @src/generators/index.ts (Template engine)
+- @src/templates/ (Template files)
+- @state/STATE.json (Project context)
+</execution_context>
+
+<context>
+**Artifact:** $ARGUMENTS (claude, project, requirements, roadmap, plan, config, rules)
+**Force Mode:** -f flag overwrites without backup
+**Context:** Loaded from STATE.json or user input
+</context>
+
+<process>
+**Execute generate command:**
+
+1. **Map Artifact to Template**
+
+   | Artifact | Template | Output | Required Fields |
+   |----------|----------|--------|-----------------|
+   | claude | CLAUDE.md.template | CLAUDE.md | projectName, vision, techStack |
+   | project | PROJECT.md.template | PROJECT.md | projectName, vision, techStack |
+   | requirements | REQUIREMENTS.md.template | REQUIREMENTS.md | projectName, vision, features, nfrs |
+   | roadmap | ROADMAP.md.template | ROADMAP.md | projectName, milestones, phases |
+   | plan | PLAN.md.template | PLAN.md | tasks, dependencyGraph |
+   | config | forge.config.json.template | .planning/forge.config.json | mode, depth, maxTeammates, taskLimit |
+   | rules | .claude/rules/*.md.template | .claude/rules/ | patterns, rules |
+
+2. **Load Context**
+   - Read state/STATE.json for project data
+   - Extract: projectName, version, status, tasks, milestones
+   - If missing fields, prompt user or error
+
+3. **Validate Required Fields**
+   - Check all required fields present
+   - Error if missing (suggest `forge init`)
+   - Show missing fields list
+
+4. **Render Template**
+   ```typescript
+   const result = await templateEngine.render(templateName, context);
+   // Returns: { content, tokenCount, withinLimit, warnings }
+   ```
+
+5. **Token Limit Check**
+   - CLAUDE.md: ~2000 tokens max
+   - REQUIREMENTS.md: ~4000 tokens max
+   - PLAN.md: ~6000 tokens max
+   - Rules: ~1000 tokens each
+
+   If over limit:
+   - Show warning with suggestions
+   - Offer to proceed or reduce
+
+6. **Backup Existing** (unless -f flag)
+   - Copy existing file to .backup
+   - Inform user of backup location
+
+7. **Write Artifact**
+   - Write rendered content to output path
+   - Log success with token count
+   - Show output location
+
+8. **Verify**
+   - Check file exists
+   - Validate format (JSON for config, MD for others)
+   - Run `forge status` to confirm
+</process>
+
+<examples>
+```bash
+# Generate CLAUDE.md
+forge generate claude
+
+# Generate REQUIREMENTS.md
+forge generate requirements
+
+# Generate ROADMAP.md
+forge generate roadmap
+
+# Generate with force (no backup)
+forge generate plan -f
+
+# Generate config file
+forge generate config
+```
+</examples>
+
+<deliverables>
+- Generated artifact file
+- Backup of existing file (if not -f)
+- Token count and limit status
+</deliverables>
+
+<validation>
+- ✅ Required fields present
+- ✅ Template exists
+- ✅ Token limit within bounds
+- ✅ Output path writable
+- ✅ Format valid (JSON/MD)
+</validation>

package/.claude/commands/forge/help.md

@@ -0,0 +1,123 @@
+---
+name: forge:help
+description: Show comprehensive FORGE command reference and usage guide. Use when user asks "forge help" or wants to see available commands.
+argument-hint: [command-name]
+allowed-tools:
+  - Read
+---
+
+<objective>
+Display comprehensive FORGE command reference with descriptions, usage examples, and links to detailed documentation.
+
+Purpose: Help users discover and understand FORGE capabilities.
+Output: Formatted command reference with examples.
+</objective>
+
+<execution_context>
+**Load these files NOW:**
+
+- @ROADMAP.md (Implementation status)
+- @CLAUDE.md (Architecture overview)
+</execution_context>
+
+<context>
+**Command Scope:** All FORGE commands (implemented and stubs)
+**Detail Level:** Summary (all commands) or detailed (specific command)
+</context>
+
+<process>
+**Display command reference:**
+
+## FORGE Commands
+
+### Core Commands (Implemented)
+
+```bash
+forge init [--quick]              # Initialize FORGE project
+forge status [-v]                 # Show project status
+forge config [key] [value]        # View/edit configuration
+forge help [command]              # Show this help
+forge generate <artifact>          # Generate specific artifact
+```
+
+### Planning Commands (Milestone 2 - In Progress)
+
+```bash
+forge discuss <phase>              # Capture phase context
+forge plan <phase>                # Generate task breakdown
+forge verify <phase>              # Verify plan against requirements
+```
+
+### Execution Commands (Milestone 3 - Planned)
+
+```bash
+forge deploy <phase>               # Deploy agent team for phase
+forge assign <task-id> <agent>    # Assign task to specialist
+forge commit <task-id>            # Create atomic commit for task
+```
+
+### Review Commands (Milestone 4 - Planned)
+
+```bash
+forge tribunal <phase>             # Adversarial review
+forge critique <file>             # Security/quality review
+```
+
+### Utility Commands
+
+```bash
+forge generate <artifact>          # Generate artifact
+  Artifacts: claude, project, requirements, roadmap, plan, config, rules
+
+forge worktree <task-id>          # Create git worktree for task
+forge merge <task-id>             # Merge worktree back to main
+```
+
+## Examples
+
+### Start a New Project
+```bash
+forge new-project my-app
+forge discuss M2-planning-engine
+forge plan M2-planning-engine
+```
+
+### Check Progress
+```bash
+forge status
+forge status -v  # verbose with all tasks
+```
+
+### Generate Artifacts
+```bash
+forge generate requirements
+forge generate roadmap
+```
+
+## Quick Reference
+
+| Command | Purpose | Milestone |
+|---------|---------|-----------|
+| init | Initialize project | M1 ✅ |
+| status | Show progress | M1 ✅ |
+| config | Configure settings | M1 ✅ |
+| discuss | Capture context | M2 🚧 |
+| plan | Generate tasks | M2 🚧 |
+| deploy | Execute phase | M3 📋 |
+| tribunal | Review phase | M4 📋 |
+
+Legend: ✅ Complete | 🚧 In Progress | 📋 Planned
+
+## Documentation
+
+- CLAUDE.md - Architecture and patterns
+- REQUIREMENTS.md - Functional requirements
+- ROADMAP.md - Implementation roadmap
+- PLAN.md - Detailed task plans
+</process>
+
+<output_format>
+**Summary:** All commands in table format
+**Detailed:** Full documentation for specific command
+**With Examples:** Usage examples for common workflows
+</output_format>