forge-dev-framework 1.0.1 → 1.2.0

package/.claude/commands/forge/README.md

@@ -0,0 +1,281 @@
+# FORGE Command Reference
+
+FORGE commands are available as slash commands in Claude Code.
+
+## Available Commands
+
+### Core Commands
+
+| Command | Description | Usage |
+|---------|-------------|-------|
+| `/forge:new-project` | Initialize a new FORGE project | `/forge:new-project [project-name]` |
+| `/forge:init` | Initialize FORGE in current directory | `/forge:init [--quick]` |
+| `/forge:status` | Show project progress | `/forge:status [-v]` |
+| `/forge:config` | View/edit configuration | `/forge:config [key] [value]` |
+| `/forge:generate` | Generate artifact from template | `/forge:generate <artifact> [-f]` |
+| `/forge:help` | Show command reference | `/forge:help [command]` |
+
+### Planning Commands
+
+| Command | Description | Usage |
+|---------|-------------|-------|
+| `/forge:discuss` | Structured context gathering with decisions | `/forge:discuss <phase-name>` |
+| `/forge:plan` | Research-first multi-plan generation | `/forge:plan <phase-name> [flags]` |
+| `/forge:verify` | Verify plans + generate gap closure plans | `/forge:verify <phase-name>` |
+| `/forge:execute` | Wave-based multi-plan execution | `/forge:execute <phase-name> [--gaps]` |
+
+### Phase Management Commands
+
+| Command | Description | Usage |
+|---------|-------------|-------|
+| `/forge:add-phase` | Add phase to end of current milestone | `/forge:add-phase <description>` |
+| `/forge:insert-phase` | Insert urgent work as decimal phase | `/forge:insert-phase <after-phase> <description>` |
+| `/forge:remove-phase` | Remove future phase and renumber | `/forge:remove-phase <phase-number>` |
+
+### Milestone Commands
+
+| Command | Description | Usage |
+|---------|-------------|-------|
+| `/forge:new-milestone` | Start new milestone cycle | `/forge:new-milestone` |
+| `/forge:complete-milestone` | Archive completed milestone | `/forge:complete-milestone` |
+
+### Workflow Commands
+
+| Command | Description | Usage |
+|---------|-------------|-------|
+| `/forge:pause-work` | Create context handoff | `/forge:pause-work` |
+| `/forge:resume` | Resume from previous session | `/forge:resume` |
+| `/forge:quick` | Execute quick task with guarantees | `/forge:quick <task-description>` |
+| `/forge:debug` | Systematic debugging | `/forge:debug [issue description]` |
+
+### Team Commands
+
+| Command | Description | Usage |
+|---------|-------------|-------|
+| `/forge:team-create` | Create agent team from AgentTeam.md | `/forge:team-create` |
+| `/forge:team-view` | View team members and config | `/forge:team-view` |
+| `/forge:team-add` | Add member to agent team | `/forge:team-add` |
+| `/forge:team-remove` | Remove member from agent team | `/forge:team-remove` |
+| `/forge:team-start` | Start all teammates | `/forge:team-start` |
+
+## Command Lifecycle
+
+```
+forge:new-project
+       ↓
+forge:new-milestone
+       ↓
+forge:discuss ←──── Structured gray area identification
+       ↓              Produces CONTEXT.md with:
+       ↓              • Implementation Decisions (locked)
+       ↓              • Claude's Discretion (flexible)
+       ↓              • Deferred Ideas (out of scope)
+       ↓
+forge:plan ←─────── Research-first planning
+       ↓              1. Research (→ RESEARCH.md)
+       ↓              2. Multi-plan generation (→ *-PLAN.md files)
+       ↓              3. Verification
+       ↓
+       ↓ ┌──────── If plans exist: add more / verify / execute / replan
+       ↓ ↓
+forge:verify ←───── Goal-backward verification
+       ↓              Checks all *-PLAN.md files
+       ↓              If gaps → generates gap closure *-PLAN.md files
+       ↓
+       ↓ (pass)                  ↓ (gaps found)
+forge:execute              forge:execute --gaps
+       ↓                         ↓
+       ↓  Wave-based execution:
+       ↓  • Discovers all *-PLAN.md files
+       ↓  • Groups by wave from frontmatter
+       ↓  • Executes waves sequentially
+       ↓  • Plans within wave in parallel
+       ↓  • Each plan → *-SUMMARY.md
+       ↓
+forge:verify ←───── Post-execution verification
+       ↓
+forge:complete-milestone
+```
+
+## Phase Directory Structure
+
+After running the full workflow, a phase directory looks like:
+
+```
+.planning/phases/M2-planning-engine/
+├── M2-CONTEXT.md                      # From /forge:discuss
+├── M2-RESEARCH.md                     # From research step in /forge:plan
+├── M2-01-PLAN.md                      # Wave 1 — Schema design (2-3 tasks)
+├── M2-02-PLAN.md                      # Wave 1 — Event types (2-3 tasks)
+├── M2-03-PLAN.md                      # Wave 2 — Merge logic (depends on 01, 02)
+├── M2-04-PLAN.md                      # Wave 2 — CLI commands
+├── M2-05-PLAN.md                      # Wave 3 — Integration (depends on 03, 04)
+├── M2-01-SUMMARY.md                   # After plan 01 execution
+├── M2-02-SUMMARY.md                   # After plan 02 execution
+├── ...
+├── VERIFICATION.md                    # From /forge:verify
+├── M2-06-PLAN.md                      # Gap closure plan (gap_closure: true)
+└── EXECUTION.md                       # Execution log with wave/plan status
+```
+
+## CONTEXT.md Sections
+
+The discuss command produces CONTEXT.md with structured sections that downstream agents consume differently:
+
+| Section | Researcher reads as | Planner reads as |
+|---------|-------------------|-----------------|
+| **Implementation Decisions** | Research deeply, no alternatives | Must implement exactly as specified |
+| **Claude's Discretion** | Research options, recommend best | Can choose freely, pick best approach |
+| **Deferred Ideas** | Ignore completely | Must NOT include in plans |
+| **Specific Ideas** | Research referenced patterns | Incorporate user inspirations |
+
+## Plan Frontmatter Reference
+
+Every `*-PLAN.md` file starts with YAML frontmatter:
+
+```yaml
+---
+phase: M2-planning-engine       # Phase identifier
+plan: 01                        # Sequential plan number
+wave: 1                         # Execution wave (parallel within wave)
+depends_on: []                  # Plan numbers this depends on
+files_modified: [src/foo.ts]    # Files this plan touches
+autonomous: true                # false if has checkpoints needing user input
+gap_closure: false              # true for gap remediation plans
+---
+```
+
+**Wave assignment rules:**
+- Plans with no dependencies → wave 1
+- Plans with dependencies → `wave = max(waves[dep] for dep in depends_on) + 1`
+- Plans in the same wave execute in parallel
+- Waves execute sequentially
+
+## Research Workflow
+
+The `/forge:plan` command includes a research step that produces `RESEARCH.md`:
+
+1. Researcher reads CONTEXT.md to scope the research
+2. Uses WebSearch, WebFetch, and codebase analysis
+3. Produces structured findings with confidence levels (HIGH/MEDIUM/LOW)
+4. Each major finding may become a separate plan file
+
+Control with flags:
+- `--research` — force re-run even if RESEARCH.md exists
+- `--skip-research` — skip research entirely
+
+## Plan Flags Reference
+
+| Flag | Command | Effect |
+|------|---------|--------|
+| `--research` | `/forge:plan` | Force re-run research |
+| `--skip-research` | `/forge:plan` | Skip research step |
+| `--skip-verify` | `/forge:plan` | Skip plan verification |
+| `--gaps` | `/forge:plan` | Generate gap closure plans only |
+| `--gaps` | `/forge:execute` | Execute only gap_closure plans |
+
+## Quick Start
+
+### 1. Initialize a New FORGE Project
+
+```bash
+/forge:new-project my-app
+```
+
+### 2. Gather Context
+
+```bash
+/forge:discuss M2-planning-engine
+```
+
+Identifies gray areas, asks focused questions, produces structured CONTEXT.md.
+
+### 3. Plan the Phase
+
+```bash
+/forge:plan M2-planning-engine
+```
+
+Researches (→ RESEARCH.md), generates multiple numbered plan files with frontmatter and wave assignments.
+
+Running `/forge:plan` again when plans exist gives options: add more, verify, execute, or replan.
+
+### 4. Verify Plans
+
+```bash
+/forge:verify M2-planning-engine
+```
+
+Checks all plans against requirements. If gaps found, generates gap closure plan files (numbered after existing plans).
+
+### 5. Execute the Phase
+
+```bash
+/forge:execute M2-planning-engine
+```
+
+Discovers all plan files, groups by wave, executes waves sequentially with plans in each wave running in parallel. Each completed plan produces a SUMMARY.md.
+
+### 6. Execute Gap Remediation (if needed)
+
+```bash
+/forge:execute M2-planning-engine --gaps
+```
+
+Executes only plans with `gap_closure: true` in their frontmatter.
+
+## Artifact Generation
+
+```bash
+/forge:generate claude          # CLAUDE.md
+/forge:generate requirements    # REQUIREMENTS.md
+/forge:generate roadmap         # ROADMAP.md
+/forge:generate config          # forge.config.json
+/forge:generate rules           # .claude/rules/*.md
+```
+
+## Configuration
+
+```bash
+/forge:config                   # View all settings
+/forge:config maxTeammates 6    # Set a value
+```
+
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| mode | enum | interactive | yolo, interactive, standard |
+| depth | enum | standard | quick, standard, comprehensive |
+| maxTeammates | int | 5 | Max agents per phase (2-10) |
+| taskLimit | int | 6 | Max tasks per phase (5-6 recommended) |
+| conventionalCommits | bool | true | Enforce commit format |
+| worktreeIsolation | bool | true | Use worktrees for tasks |
+
+## FORGE Architecture
+
+```
+All Agents → state/events/*.json (append-only)
+                        ↓
+              State Steward (single writer)
+                        ↓
+                  state/STATE.json (canonical)
+```
+
+### Key Principles
+
+- **Event-Sourced State**: Append-only event log
+- **Single-Writer**: Only State Steward writes STATE.json
+- **Contract-First**: API contracts negotiated before cross-domain work
+- **File Ownership**: Each agent writes only within owned paths
+- **Wipe Protocol**: Fresh agent context per task
+- **Atomic Commits**: One task = one commit
+
+## Getting Help
+
+```bash
+/forge:help              # Show all commands
+/forge:help plan         # Detailed help for specific command
+```
+
+## Version
+
+FORGE v1.0-M1 — Milestone 1: Foundation (COMPLETE)

package/.claude/commands/forge/add-phase.md

@@ -0,0 +1,90 @@
+---
+name: forge:add-phase
+description: Add phase to end of current milestone in roadmap
+argument-hint: <description>
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+---
+
+<objective>
+Add a new integer phase to the end of the current milestone in the roadmap.
+
+Routes to the add-phase workflow which handles:
+- Phase number calculation (next sequential integer)
+- Directory creation with slug generation
+- Roadmap structure updates
+- State evolution tracking
+</objective>
+
+<execution_context>
+@state/STATE.json
+@ROADMAP.md
+@CLAUDE.md
+</execution_context>
+
+<context>
+**Phase Description:** $ARGUMENTS
+
+**Phase Assignment:**
+1. Read ROADMAP.md to find current milestone
+2. Calculate next integer phase (ignoring decimals)
+3. Generate slug from description
+4. Create phase directory structure
+5. Add to ROADMAP.md
+</context>
+
+<process>
+**Execute add-phase workflow:**
+
+1. **Load State**
+   - Read state/STATE.json
+   - Read ROADMAP.md
+   - Identify current milestone
+
+2. **Calculate Phase Number**
+   - Find highest integer phase in current milestone
+   - Next phase = highest + 1
+   - Example: If phases are 70, 71, 71.1, 72 → next is 73
+
+3. **Generate Slug**
+   - Create URL-safe slug from description
+   - Format: `<phase-number>-<slug>`
+   - Example: "Implement auth" → "73-implement-auth"
+
+4. **Create Directory Structure**
+   ```bash
+   mkdir -p .planning/phases/<phase-slug>/
+   touch .planning/phases/<phase-slug>/CONTEXT.md
+   touch .planning/phases/<phase-slug>/PLAN.md
+   ```
+
+5. **Update ROADMAP.md**
+   - Add new phase entry to current milestone
+   - Use standard phase format
+   - Maintain proper heading hierarchy
+
+6. **Submit Event**
+   - Event type: PHASE_ADDED
+   - Include: phaseId, milestoneId, description
+   - Write to state/events/
+
+7. **Confirm**
+   - Show new phase info
+   - Suggest next: `/forge:discuss <phase-number>` or `/forge:plan <phase-number>`
+</process>
+
+<deliverables>
+- .planning/phases/<phase-slug>/CONTEXT.md (empty template)
+- .planning/phases/<phase-slug>/PLAN.md (empty template)
+- ROADMAP.md updated with new phase
+- Event: PHASE_ADDED in state/events/
+- STATE.json updated
+</deliverables>
+
+<next_steps>
+- Run `/forge:discuss <phase-number>` to capture phase context
+- Run `/forge:plan <phase-number>` to generate task breakdown
+- Tip: Use `/clear` to start from a fresh context
+</next_steps>

package/.claude/commands/forge/complete-milestone.md

@@ -0,0 +1,130 @@
+---
+name: forge:complete-milestone
+description: Archive completed milestone and prepare for next version
+argument-hint: ""
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+---
+
+<objective>
+Archive the completed milestone and prepare the project for the next version.
+
+Routes to audit-milestone workflow which validates completion before archiving.
+</objective>
+
+<execution_context>
+@state/STATE.json
+@ROADMAP.md
+@CLAUDE.md
+</execution_context>
+
+<context>
+**Milestone Completion Workflow:**
+1. Validate all phases in milestone are complete
+2. Generate milestone summary
+3. Archive milestone artifacts
+4. Update ROADMAP.md
+5. Prepare next milestone
+6. Tag and release (optional)
+</context>
+
+<process>
+**Execute complete-milestone workflow:**
+
+1. **Load State**
+   - Read state/STATE.json
+   - Read ROADMAP.md
+   - Identify current milestone
+
+2. **Validate Completion**
+   Check all phases in current milestone:
+   - Status is "completed"
+   - All tasks complete
+   - All tests passing
+   - No pending blockers
+
+   If validation fails:
+   - Show incomplete phases
+   - Ask: "Continue anyway?" or "Fix issues first?"
+
+3. **Generate Milestone Summary**
+   ```markdown
+   # Milestone {name} Summary
+
+   **Completed:** {date}
+   **Duration:** {start-date} to {end-date}
+
+   ## Phases Delivered
+   - {phase-1}: {description}
+   - {phase-2}: {description}
+
+   ## Key Metrics
+   - Total Phases: {count}
+   - Total Tasks: {count}
+   - Completion Rate: {percentage}
+   - Test Coverage: {percentage}
+
+   ## Technical Highlights
+   - {highlight-1}
+   - {highlight-2}
+
+   ## Challenges Overcome
+   - {challenge-1}
+   - {challenge-2}
+
+   ## Next Steps
+   - {next-milestone-goals}
+   ```
+
+4. **Archive Artifacts**
+   ```bash
+   mkdir -p .planning/archive/milestone-{name}/
+   cp ROADMAP.md .planning/archive/milestone-{name}/
+   cp PLAN.md .planning/archive/milestone-{name}/ || true
+   cp -r .planning/phases/* .planning/archive/milestone-{name}/phases/ || true
+   ```
+
+5. **Update ROADMAP.md**
+   - Move completed milestone to "Completed" section
+   - Mark as ✅ COMPLETE
+   - Add milestone summary
+
+6. **Update STATE.json**
+   - Set `project.status` = "completed"
+   - Archive milestone data
+   - Prepare for next milestone
+
+7. **Submit Events**
+   - Event type: MILESTONE_COMPLETED
+   - Include: milestoneId, summary, metrics
+   - Write to state/events/
+
+8. **Git Tag** (optional)
+   - Ask: "Create git tag for this milestone?"
+   - If yes: `git tag -a milestone-{name} -m "Milestone {name} complete"`
+
+9. **Confirm**
+   - Show milestone summary
+   - List archived artifacts
+   - Suggest next: `/forge:new-milestone` or manual planning
+
+10. **Cleanup**
+    - Offer to remove completed phase directories
+    - Ask: "Clean up .planning/phases/?"
+</process>
+
+<deliverables>
+- .planning/archive/milestone-{name}/ (archived artifacts)
+- ROADMAP.md updated (milestone moved to completed)
+- STATE.json updated (milestone archived)
+- Event: MILESTONE_COMPLETED in state/events/
+- Optional: Git tag milestone-{name}
+</deliverables>
+
+<next_steps>
+- Run `forge new-milestone` to start next milestone
+- Or manually plan next work
+- Celebrate! 🎉
+</next_steps>

package/.claude/commands/forge/config.md

@@ -0,0 +1,115 @@
+---
+name: forge:config
+description: View or edit FORGE configuration settings. Use when user says "forge config" or wants to change settings.
+argument-hint: [key] [value]
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+---
+
+<objective>
+View current FORGE configuration or modify specific settings.
+
+Purpose: Configure FORGE behavior for the project.
+Output: Current settings or updated configuration.
+</objective>
+
+<execution_context>
+**Load these files NOW:**
+
+- @.planning/forge.config.json (Current configuration)
+- @state/STATE.json (Project state)
+</execution_context>
+
+<context>
+**Configuration File:** .planning/forge.config.json
+**Operation:** View (no args) or Edit (key + value)
+</context>
+
+<process>
+**Execute config command:**
+
+1. **View Configuration** (no arguments)
+   ```bash
+   forge config
+   ```
+
+   Output:
+   ```
+   FORGE Configuration:
+   ───────────────────────────────────────
+   mode: interactive           # Interaction mode
+   depth: standard            # Planning depth
+   maxTeammates: 5            # Max agents per phase
+   taskLimit: 6               # Max tasks per phase
+   conventionalCommits: true   # Enforce commit format
+   worktreeIsolation: true    # Use worktrees for tasks
+   ```
+
+2. **View Specific Key**
+   ```bash
+   forge config taskLimit
+   # Output: taskLimit = 6
+   ```
+
+3. **Edit Setting**
+   ```bash
+   forge config maxTeammates 6
+   # Updates: .planning/forge.config.json
+   ```
+
+4. **Validate Changes**
+   - Check value type
+   - Validate ranges (e.g., maxTeammates: 2-10)
+   - Verify schema compliance
+   - Update STATE.json if needed
+
+5. **Available Settings**
+
+   | Key | Type | Default | Description |
+   |-----|------|---------|-------------|
+   | mode | enum | interactive | yolo, interactive, standard |
+   | depth | enum | standard | quick, standard, comprehensive |
+   | maxTeammates | int | 5 | Max agents per phase (2-10) |
+   | taskLimit | int | 6 | Max tasks per phase (5-6 recommended) |
+   | conventionalCommits | bool | true | Enforce commit format |
+   | worktreeIsolation | bool | true | Use worktrees for tasks |
+   | autoMerge | bool | false | Auto-merge completed tasks |
+
+6. **Config Schema**
+   ```json
+   {
+     "$schema": "./config.schema.json",
+     "mode": "interactive",
+     "depth": "standard",
+     "maxTeammates": 5,
+     "taskLimit": 6,
+     "conventionalCommits": true,
+     "worktreeIsolation": true,
+     "autoMerge": false
+   }
+   ```
+</process>
+
+<validation>
+- Type checking (int, bool, enum)
+- Range validation (e.g., maxTeammates: 2-10)
+- Schema compliance
+</validation>
+
+<examples>
+```bash
+# View all config
+forge config
+
+# View specific setting
+forge config taskLimit
+
+# Change setting
+forge config maxTeammates 6
+
+# Reset to defaults
+forge config --reset
+```
+</examples>

package/.claude/commands/forge/convert.md

@@ -0,0 +1,31 @@
+---
+name: forge:convert
+description: Convert GSD project to FORGE format.
+argument-hint: [--dry-run] [--force]
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Glob
+  - Grep
+  - Bash
+  - Task
+  - TeamCreate
+  - AskUserQuestion
+---
+
+Convert existing GSD project to FORGE format, preserving roadmap and phase context.
+
+**GSD → FORGE mapping:** PROJECT.md → CLAUDE.md | ROADMAP.md → preserved | .planning/phases → STATE.json tasks
+
+**Steps:**
+
+1. Detect GSD project (PROJECT.md, ROADMAP.md, .planning/)
+2. If `--dry-run`, preview changes and exit
+3. Create FORGE structure: state/STATE.json, state/events/, contracts/, .planning/forge.config.json
+4. Generate CLAUDE.md from PROJECT.md with FORGE architecture patterns
+5. Extract tasks from phase plans into STATE.json
+6. If no AgentTeam.md, analyze codebase and generate one. Create team with TeamCreate.
+7. Verify with `/forge:status`
+
+Use `--force` to overwrite existing FORGE files.

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

@@ -0,0 +1,31 @@
+---
+name: forge:debug
+description: Systematic debugging with persistent state across context resets
+argument-hint: [issue description]
+allowed-tools:
+  - Read
+  - Bash
+  - Task
+  - AskUserQuestion
+---
+
+Debug issue "$ARGUMENTS" using scientific method with subagent isolation.
+
+**Read:** state/STATE.json
+
+**Steps:**
+
+1. Check for active debug sessions in `.planning/debug/`. If found and no args, list sessions for user to resume.
+
+2. Gather symptoms via AskUserQuestion: expected behavior, actual behavior, errors, timeline, reproduction steps.
+
+3. Create `.planning/debug/{slug}.md` with symptom data.
+
+4. Spawn debugger subagent via Task tool with symptoms context. Uses fresh 200k context for investigation.
+
+5. Handle agent return:
+   - **ROOT CAUSE FOUND:** Display cause + evidence, offer "Fix now" / "Plan fix" / "Manual fix"
+   - **CHECKPOINT REACHED:** Present to user, get response, spawn continuation agent
+   - **INCONCLUSIVE:** Show eliminated hypotheses, offer to continue or add context
+
+6. Submit DEBUG_SESSION_CREATED/RESOLVED event. Rename resolved files to `{slug}.resolved.md`.