forge-dev-framework 1.1.0 → 1.2.0

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

@@ -1,10 +1,10 @@
 # FORGE Command Reference
 
-FORGE commands are now available as slash commands in Claude Code, similar to how GSD works.
+FORGE commands are available as slash commands in Claude Code.
 
 ## Available Commands
 
-### Core Commands (Milestone 1 ✅)
+### Core Commands
 
 | Command | Description | Usage |
 |---------|-------------|-------|
@@ -15,19 +15,14 @@ FORGE commands are now available as slash commands in Claude Code, similar to ho
 | `/forge:generate` | Generate artifact from template | `/forge:generate <artifact> [-f]` |
 | `/forge:help` | Show command reference | `/forge:help [command]` |
 
-### Planning Commands (Milestone 2 🚧)
+### Planning Commands
 
 | Command | Description | Usage |
 |---------|-------------|-------|
-| `/forge:discuss` | Capture phase context | `/forge:discuss <phase-name>` |
-| `/forge:plan` | Generate task breakdown | `/forge:plan <phase-name>` |
-| `/forge:verify` | Verify plan against requirements | `/forge:verify <phase-name>` |
-
-### Execution Commands (Milestone 3 📋)
-
-| Command | Description | Usage |
-|---------|-------------|-------|
-| `/forge:execute` | Execute phase with agent teams | `/forge:execute <phase-name>` |
+| `/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
 
@@ -49,10 +44,136 @@ FORGE commands are now available as slash commands in Claude Code, similar to ho
 | Command | Description | Usage |
 |---------|-------------|-------|
 | `/forge:pause-work` | Create context handoff | `/forge:pause-work` |
-| `/forge:resume-work` | Resume from previous session | `/forge:resume-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
@@ -61,87 +182,65 @@ FORGE commands are now available as slash commands in Claude Code, similar to ho
 /forge:new-project my-app
 ```
 
-This creates a complete FORGE project structure with:
-- CLAUDE.md (project constitution)
-- state/STATE.json (event-sourced state)
-- .planning/forge.config.json (configuration)
-- Templates and generators
-- Git integration with hooks
-
-### 2. Plan a Phase
-
-First, capture context:
+### 2. Gather Context
 
 ```bash
 /forge:discuss M2-planning-engine
 ```
 
-Then generate tasks:
+Identifies gray areas, asks focused questions, produces structured CONTEXT.md.
+
+### 3. Plan the Phase
 
 ```bash
 /forge:plan M2-planning-engine
 ```
 
-This creates a PLAN.md with:
-- 5-6 atomic tasks (FORGE hard rule)
-- Mermaid dependency graph
-- Requirements coverage matrix
-- Acceptance criteria
+Researches (→ RESEARCH.md), generates multiple numbered plan files with frontmatter and wave assignments.
 
-### 3. Verify the Plan
+Running `/forge:plan` again when plans exist gives options: add more, verify, execute, or replan.
+
+### 4. Verify Plans
 
 ```bash
 /forge:verify M2-planning-engine
 ```
 
-This validates:
-- Requirements coverage
-- Goal-backward verification
-- Integration completeness
-- Task atomicity
+Checks all plans against requirements. If gaps found, generates gap closure plan files (numbered after existing plans).
 
-### 4. Execute the Phase
+### 5. Execute the Phase
 
 ```bash
 /forge:execute M2-planning-engine
 ```
 
-This spawns agent teams to execute tasks with:
-- Wave-based parallelization
-- Wipe Protocol (fresh context per task)
-- Atomic commits (one task = one commit)
-- Contract-first coordination
+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.
 
-## Artifact Generation
+### 6. Execute Gap Remediation (if needed)
 
-Generate specific artifacts using `/forge:generate`:
+```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 plan            # PLAN.md
 /forge:generate config          # forge.config.json
 /forge:generate rules           # .claude/rules/*.md
 ```
 
 ## Configuration
 
-View configuration:
-
-```bash
-/forge:config
-```
-
-Edit a setting:
-
 ```bash
-/forge:config maxTeammates 6
-/forge:config taskLimit 5
+/forge:config                   # View all settings
+/forge:config maxTeammates 6    # Set a value
 ```
 
-Available settings:
-
 | Key | Type | Default | Description |
 |-----|------|---------|-------------|
 | mode | enum | interactive | yolo, interactive, standard |
@@ -151,77 +250,8 @@ Available settings:
 | conventionalCommits | bool | true | Enforce commit format |
 | worktreeIsolation | bool | true | Use worktrees for tasks |
 
-## Status Tracking
-
-Check project progress:
-
-```bash
-/forge:status
-```
-
-Verbose mode (shows all tasks):
-
-```bash
-/forge:status -v
-```
-
-## Command Lifecycle
-
-```
-┌─────────────────┐
-│ forge:new-project │  ← Create new FORGE project
-└────────┬────────┘
-         ↓
-┌─────────────────┐
-│ forge:new-milestone │ ← Start new milestone
-└────────┬────────┘
-         ↓
-┌─────────────────┐
-│  forge:discuss  │  ← Capture phase context
-└────────┬────────┘
-         ↓
-┌─────────────────┐
-│   forge:plan    │  ← Generate 5-6 atomic tasks
-└────────┬────────┘
-         ↓
-┌─────────────────┐
-│  forge:verify   │  ← Validate against requirements
-└────────┬────────┘
-         ↓
-┌─────────────────┐
-│  forge:execute  │  ← Execute with agent teams
-└────────┬────────┘
-         ↓
-┌─────────────────────┐
-│ forge:pause-work   │ ← Pause mid-phase (optional)
-└────────┬────────────┘
-         ↓
-┌─────────────────────┐
-│ forge:resume-work  │ ← Resume with full context
-└────────┬────────────┘
-         ↓
-┌─────────────────────┐
-│forge:complete-milestone│ ← Archive milestone
-└─────────────────────┘
-```
-
-## Quick Tasks & Debugging
-
-For ad-hoc work outside the planned phases:
-
-```bash
-/forge:quick "Fix login bug"     # Execute small task with atomic commits
-/forge:debug "API not responding" # Systematic debugging workflow
-```
-
-**Quick tasks** live in `.planning/quick/` separate from planned phases and update the quick tasks table in STATE.json.
-
-**Debug sessions** create `.planning/debug/*.md` files with investigation state that persists across context resets.
-
 ## FORGE Architecture
 
-FORGE uses an event-sourced state engine with single-writer merge:
-
 ```
 All Agents → state/events/*.json (append-only)
                         ↓
@@ -237,19 +267,8 @@ All Agents → state/events/*.json (append-only)
 - **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
-- **5-6 Task Limit**: Maximum tasks per phase
 - **Atomic Commits**: One task = one commit
 
-## Milestone Status
-
-| Milestone | Name | Status |
-|-----------|------|--------|
-| M1 | Foundation | ✅ Complete |
-| M2 | Planning Engine | 🚧 In Progress |
-| M3 | Parallel Execution | 📋 Planned |
-| M4 | Adversarial Review | 📋 Planned |
-| M5 | CLI & TUI | 📋 Planned |
-
 ## Getting Help
 
 ```bash
@@ -257,58 +276,6 @@ All Agents → state/events/*.json (append-only)
 /forge:help plan         # Detailed help for specific command
 ```
 
-## File Structure
-
-```
-.forge-project/
-├── CLAUDE.md              # Project constitution
-├── REQUIREMENTS.md        # Functional requirements
-├── ROADMAP.md            # Milestone breakdown
-├── PLAN.md               # Task breakdown
-├── state/
-│   ├── STATE.json        # Canonical state (single-writer)
-│   ├── STATE.schema.json # State validation schema
-│   └── events/          # Append-only event log
-├── contracts/            # API contracts
-├── .planning/
-│   ├── forge.config.json # Configuration
-│   └── phases/          # Phase artifacts
-├── .claude/
-│   └── rules/          # Scoped rules
-├── src/
-│   ├── cli/            # CLI commands
-│   ├── commands/       # Command implementations
-│   ├── generators/     # Template engine
-│   ├── git/           # Git operations
-│   └── utils/         # Utilities
-└── .worktrees/        # Git worktrees for isolation
-```
-
-## Integration with Claude Code
-
-FORGE commands integrate seamlessly with Claude Code's agent teams:
-
-1. **State Engine**: Manages project state deterministically
-2. **Contract-First**: Agents negotiate interfaces before implementation
-3. **File Ownership**: Clear boundaries prevent merge conflicts
-4. **Wipe Protocol**: Fresh context prevents hallucination carry-over
-5. **Atomic Commits**: One task = one git commit (enforced)
-
-## Next Steps
-
-1. Run `/forge:new-project` to create a new FORGE project
-2. Run `/forge:discuss` to capture phase context
-3. Run `/forge:plan` to generate task breakdown
-4. Run `/forge:execute` to execute with agent teams
-5. Run `/forge:status` to track progress
-
-## Documentation
-
-- **CLAUDE.md**: Architecture, patterns, rules
-- **REQUIREMENTS.md**: Functional requirements
-- **ROADMAP.md**: 5-milestone implementation plan
-- **PLAN.md**: Detailed task breakdowns
-
 ## Version
 
-FORGE v1.0-M1 — Milestone 1: Foundation (COMPLETE ✅)
+FORGE v1.0-M1 — Milestone 1: Foundation (COMPLETE)

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

@@ -72,7 +72,7 @@ Routes to the add-phase workflow which handles:
 
 7. **Confirm**
    - Show new phase info
-   - Suggest next: `forge discuss <phase>` or `forge plan <phase>`
+   - Suggest next: `/forge:discuss <phase-number>` or `/forge:plan <phase-number>`
 </process>
 
 <deliverables>
@@ -84,6 +84,7 @@ Routes to the add-phase workflow which handles:
 </deliverables>
 
 <next_steps>
-- Run `forge discuss <phase>` to capture phase context
-- Run `forge plan <phase>` to generate task breakdown
+- 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

@@ -108,7 +108,7 @@ Routes to audit-milestone workflow which validates completion before archiving.
 9. **Confirm**
    - Show milestone summary
    - List archived artifacts
-   - Suggest next: `forge new-milestone` or manual planning
+   - Suggest next: `/forge:new-milestone` or manual planning
 
 10. **Cleanup**
     - Offer to remove completed phase directories

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

@@ -9,165 +9,23 @@ allowed-tools:
   - AskUserQuestion
 ---
 
-<objective>
-Debug issues using scientific method with subagent isolation.
+Debug issue "$ARGUMENTS" using scientific method with subagent isolation.
 
-**Orchestrator role:** Gather symptoms, spawn debugger agent, handle checkpoints, spawn continuations.
+**Read:** state/STATE.json
 
-**Why subagent:** Investigation burns context fast (reading files, forming hypotheses, testing). Fresh 200k context per investigation. Main context stays lean for user interaction.
-</objective>
+**Steps:**
 
-<execution_context>
-@state/STATE.json
-@CLAUDE.md
-</execution_context>
+1. Check for active debug sessions in `.planning/debug/`. If found and no args, list sessions for user to resume.
 
-<context>
-**User's Issue:** $ARGUMENTS
+2. Gather symptoms via AskUserQuestion: expected behavior, actual behavior, errors, timeline, reproduction steps.
 
-**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>
+3. Create `.planning/debug/{slug}.md` with symptom data.
 
-<process>
-**Execute debug workflow:**
+4. Spawn debugger subagent via Task tool with symptoms context. Uses fresh 200k context for investigation.
 
-1. **Check Active Sessions**
-   ```bash
-   find .planning/debug -name "*.md" -type f 2>/dev/null | grep -v resolved | head -5
-   ```
+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
 
-   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>
+6. Submit DEBUG_SESSION_CREATED/RESOLVED event. Rename resolved files to `{slug}.resolved.md`.