forge-dev-framework 1.0.1 → 1.1.0

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

@@ -0,0 +1,314 @@
+# FORGE Command Reference
+
+FORGE commands are now available as slash commands in Claude Code, similar to how GSD works.
+
+## Available Commands
+
+### Core Commands (Milestone 1 ✅)
+
+| 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 (Milestone 2 🚧)
+
+| 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>` |
+
+### 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-work` | Resume from previous session | `/forge:resume-work` |
+| `/forge:quick` | Execute quick task with guarantees | `/forge:quick <task-description>` |
+| `/forge:debug` | Systematic debugging | `/forge:debug [issue description]` |
+
+## Quick Start
+
+### 1. Initialize a New FORGE Project
+
+```bash
+/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:
+
+```bash
+/forge:discuss M2-planning-engine
+```
+
+Then generate tasks:
+
+```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
+
+### 3. Verify the Plan
+
+```bash
+/forge:verify M2-planning-engine
+```
+
+This validates:
+- Requirements coverage
+- Goal-backward verification
+- Integration completeness
+- Task atomicity
+
+### 4. 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
+
+## Artifact Generation
+
+Generate specific artifacts using `/forge:generate`:
+
+```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
+```
+
+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 |
+
+## 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)
+                        ↓
+              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
+- **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
+/forge:help              # Show all commands
+/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 ✅)

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

@@ -0,0 +1,89 @@
+---
+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>` or `forge plan <phase>`
+</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>` to capture phase context
+- Run `forge plan <phase>` to generate task breakdown
+</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>