forge-dev-framework 1.0.1 → 1.2.0

package/.claude/commands/forge/plan.md

@@ -0,0 +1,129 @@
+---
+name: forge:plan
+description: Research-first multi-plan generation with wave-based execution ordering.
+argument-hint: <phase-name> [--research] [--skip-research] [--gaps] [--skip-verify]
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Glob
+  - Grep
+  - Task
+  - TaskCreate
+  - TeamCreate
+  - WebSearch
+  - WebFetch
+  - AskUserQuestion
+---
+
+Generate research-backed multi-plan breakdown for phase $ARGUMENTS. Each research finding that needs addressing becomes a separate plan file with 2-3 tasks. Plans are grouped into waves for parallel execution.
+
+**Read first:** REQUIREMENTS.md, ROADMAP.md, .planning/phases/{phase}/CONTEXT.md (if exists), state/STATE.json
+
+**Steps:**
+
+1. **Parse arguments** — Extract phase name and flags from `$ARGUMENTS`:
+   - `--research` — force re-run research even if RESEARCH.md exists
+   - `--skip-research` — skip research step entirely
+   - `--gaps` — generate gap closure plans only (used after verify)
+   - `--skip-verify` — skip plan verification step
+
+2. **Check for existing plans** — Look for `.planning/phases/{phase}/*-PLAN.md` files.
+   - If plan files exist, use AskUserQuestion with options:
+     a) "Add more plans" — continue numbering from highest existing plan number
+     b) "Verify existing plans" — route to `/forge:verify {phase}`
+     c) "Execute existing plans" — route to `/forge:execute {phase}`
+     d) "Replan from scratch" — delete existing plan files, regenerate from research
+   - If no plans exist, proceed to research.
+
+3. **Research phase** (unless `--skip-research` or `--gaps`):
+   - Check if `.planning/phases/{phase}/{phase}-RESEARCH.md` exists.
+   - If exists and no `--research` flag, ask: use existing research or re-run?
+   - If research needed, spawn a researcher agent via Task tool (subagent_type: "general-purpose"):
+     - **Researcher reads:** CONTEXT.md to constrain research scope:
+       - **Locked decisions** → research these deeply, find best practices, don't explore alternatives
+       - **Claude's discretion** → research multiple options, recommend one with rationale
+       - **Deferred ideas** → ignore completely, do not research
+     - **Researcher uses:** WebSearch (include current year in queries), WebFetch (official docs), Grep/Glob (codebase patterns to follow)
+     - **Researcher produces** `{phase}-RESEARCH.md` with sections:
+       ```
+       # {Phase} Research
+       ## User Constraints (from CONTEXT.md)
+       ## Summary
+       ## Recommended Stack (specific versions)
+       ## Architecture Patterns
+       ## Don't Hand-Roll (use existing libraries)
+       ## Common Pitfalls
+       ## Code Examples
+       ## Sources
+       [Each with confidence: HIGH | MEDIUM | LOW]
+       ```
+     - Each major research finding becomes a candidate for a separate plan
+
+4. **Generate multi-plan breakdown** — Spawn a planner agent via Task tool (subagent_type: "general-purpose"):
+   - **Planner reads:** CONTEXT.md (locked decisions), RESEARCH.md, REQUIREMENTS.md, STATE.json, existing codebase patterns
+   - **Planner decomposes** the phase into multiple plan files, each covering one coherent unit of work with 2-3 tasks
+   - **Each plan file** gets YAML frontmatter:
+     ```yaml
+     ---
+     phase: {phase-name}
+     plan: 01
+     wave: 1
+     depends_on: []
+     files_modified: [src/foo.ts, src/bar.ts]
+     autonomous: true
+     gap_closure: false
+     ---
+     ```
+   - **Plan body** contains:
+     - Objective (what this plan builds and why)
+     - Context references (which CONTEXT.md decisions apply)
+     - Tasks in XML format:
+       ```xml
+       <task name="descriptive-name" type="auto">
+         <files>src/foo.ts, src/bar.ts</files>
+         <action>What to implement, specifically</action>
+         <verify>npm test, specific checks</verify>
+         <done>Concrete completion criteria</done>
+       </task>
+       ```
+     - Success criteria for the plan as a whole
+   - **Write to:** `.planning/phases/{phase}/{phase}-01-PLAN.md`, `{phase}-02-PLAN.md`, etc.
+   - **Build dependency graph and assign waves:**
+     - Independent plans → same wave (can execute in parallel)
+     - Plans that depend on others → higher wave number
+     - `wave = max(waves[dep] for dep in depends_on) + 1`
+     - Wave 1 plans have no dependencies
+
+5. **Verify plans** (unless `--skip-verify`):
+   - Check: requirements coverage across all plans, task completeness, dependency correctness, no circular deps, scope matches CONTEXT.md (no deferred ideas included)
+   - If issues found, revision loop (max 3 iterations): targeted fixes, not full replan
+   - If passes, proceed
+
+6. **Present results:**
+   ```
+   Phase {X}: {Name} — {N} plan(s) in {M} wave(s)
+
+   | Wave | Plans | What it builds |
+   |------|-------|----------------|
+   | 1    | 01, 02 | [objectives]  |
+   | 2    | 03     | [objective]   |
+
+   Research: {Completed | Used existing | Skipped}
+   Verification: {Passed | Skipped}
+
+   Next: /forge:execute {phase}
+   ```
+
+**Plan frontmatter reference:**
+```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
+---
+```

package/.claude/commands/forge/quick.md

@@ -0,0 +1,41 @@
+---
+name: forge:quick
+description: Execute a quick task with FORGE guarantees (atomic commits, state tracking)
+argument-hint: <task-description>
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Glob
+  - Grep
+  - Bash
+  - Task
+  - TaskCreate
+  - TeamCreate
+  - AskUserQuestion
+---
+
+Execute quick ad-hoc task "$ARGUMENTS" with atomic commits and state tracking. Skips research/verification.
+
+**Read:** state/STATE.json
+
+**Steps:**
+
+1. Generate task ID `quick-{timestamp}`, create `.planning/quick/{taskId}/PLAN.md` with description, steps (1-3), and acceptance criteria
+
+2. **Ensure FORGE team AND teammates are running:**
+   - Check `~/.claude/teams/forge/config.json` exists. If not, create team with TeamCreate.
+   - Read `.planning/AgentTeam.md` to get the list of teammates that should be active.
+   - Read `~/.claude/teams/forge/config.json` members list to see who is registered.
+   - For each teammate defined in AgentTeam.md that is NOT in the team config (or if team was just created), spawn them using the Task tool with `team_name: "forge"` and `name: "{teammate-name}"` and their full prompt from AgentTeam.md.
+   - This ensures teammates are always running when any FORGE command executes, even after session restarts.
+
+3. Validate quick mode fit (well-understood, small, 1-3 steps). If too big, suggest `/forge:plan`.
+
+4. Execute steps: make changes → atomic commit `feat({taskId}): {desc}` → update PLAN.md checklist after each
+
+5. Optionally delegate to teammates via TaskCreate + Task if complex enough
+
+6. Finalize PLAN.md (mark completed, list commits), update STATE.json `quickTasksCompleted` table, submit QUICK_TASK_COMPLETED event to state/events/
+
+7. Show completion summary with commits and PLAN.md location

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

@@ -0,0 +1,92 @@
+---
+name: forge:remove-phase
+description: Remove a future phase from roadmap and renumber subsequent phases
+argument-hint: <phase-number>
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+---
+
+<objective>
+Remove a future phase from the roadmap and renumber all subsequent phases.
+
+Use when: Phase is no longer needed, duplicate, or superseded by another phase.
+
+**Safety:** Cannot remove in-progress or completed phases.
+</objective>
+
+<execution_context>
+@state/STATE.json
+@ROADMAP.md
+@CLAUDE.md
+</execution_context>
+
+<context>
+**Phase to Remove:** $ARGUMENTS
+
+**Phase Removal Validation:**
+1. Check phase status (must be "pending")
+2. Verify phase is in the future
+3. Check for dependents
+4. Warn if other phases depend on this one
+</context>
+
+<process>
+**Execute remove-phase workflow:**
+
+1. **Parse Arguments**
+   - Extract phase number to remove
+
+2. **Load State**
+   - Read state/STATE.json
+   - Read ROADMAP.md
+   - Check phase status
+
+3. **Validate Removal**
+   - If phase is "in_progress" or "completed" → ERROR
+   - If phase is "pending" → continue
+   - Check for phases that depend on this one
+   - If dependents exist → warn and require confirmation
+
+4. **Renumber Subsequent Phases**
+   - Find all phases with higher numbers in the same milestone
+   - Decrement each phase number by 1
+   - Update phase directory names if needed
+   - Update phase IDs in ROADMAP.md
+   - Update dependencies in other phases
+
+5. **Remove from ROADMAP.md**
+   - Delete phase entry from ROADMAP.md
+   - Renumber subsequent phases
+   - Update all cross-references
+
+6. **Remove Directory** (optional)
+   - Ask user if they want to remove the phase directory
+   - If yes: `rm -rf .planning/phases/<phase-slug>/`
+   - If no: Keep for reference
+
+7. **Submit Event**
+   - Event type: PHASE_REMOVED
+   - Include: removedPhaseId, renumberedPhases
+   - Write to state/events/
+
+8. **Confirm**
+   - Show removed phase info
+   - List renumbered phases
+   - Notify of any dependency updates
+</process>
+
+<deliverables>
+- ROADMAP.md updated (phase removed, subsequent phases renumbered)
+- Phase directory removed (if user confirmed)
+- Event: PHASE_REMOVED in state/events/
+- STATE.json updated
+</deliverables>
+
+<next_steps>
+- Review updated roadmap with `/forge:status`
+- Update any dependent phases manually if needed
+- Continue work with `/forge:execute <phase-number>`
+- Tip: Use `/clear` to start from a fresh context
+</next_steps>

package/.claude/commands/forge/resume.md

@@ -0,0 +1,22 @@
+---
+name: forge:resume
+description: Resume work from previous session with full context restoration
+argument-hint: ""
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+---
+
+Resume work by loading `.continue-here.md` handoff file.
+
+**Read:** .continue-here.md, state/STATE.json
+
+**Steps:**
+
+1. Check for `.continue-here.md`. If missing, check STATE.json for last phase.
+2. Parse and display: phase, status, position, completed work, remaining work, decisions, blockers
+3. Ask "Ready to continue?"
+4. Submit WORK_RESUMED event to state/events/
+5. Route to next action: `/forge:execute`, manual work, or `/forge:discuss`
+6. After completing work, remove .continue-here.md and submit WORK_COMPLETED event

package/.claude/commands/forge/status.md

@@ -0,0 +1,87 @@
+---
+name: forge:status
+description: Show FORGE project status including current milestone, tasks, events, and progress. Use when user asks "forge status" or wants to see project progress.
+argument-hint: [-v|--verbose]
+allowed-tools:
+  - Read
+  - Bash
+---
+
+<objective>
+Display current FORGE project status including milestone progress, task states, event count, and team activity.
+
+Purpose: Provide visibility into project state and progress.
+Output: Formatted status table with milestone, tasks, events, and counts.
+</objective>
+
+<execution_context>
+**Load these files NOW:**
+
+- @state/STATE.json (current project state)
+- @src/commands/status.ts (status command implementation)
+</execution_context>
+
+<context>
+**Verbosity:** Standard (summary) or -v (verbose with full details)
+**State File:** state/STATE.json
+**Events Directory:** state/events/
+
+**Status Information:**
+- Project name and version
+- Current milestone and phase
+- Task counts by status (pending, in_progress, completed)
+- Total events processed
+- Team member activity
+- Recent commits
+</context>
+
+<process>
+**Execute the status command:**
+
+1. **Load State**
+   ```bash
+   forge status
+   # or
+   forge status -v  # verbose mode
+   ```
+
+2. **Parse STATE.json**
+   - Extract project metadata
+   - Count tasks by status
+   - Count events from state/events/
+   - Get current milestone/phase
+
+3. **Format Output**
+   ```
+   PROJECT: FORGE v1.0-M1
+   STATUS: in_progress
+
+   MILESTONE: v1.0-M1 (Foundation)
+   PHASE: Complete
+
+   TASKS:
+     ✅ Completed: 27/27
+     🔄 In Progress: 0
+     ⏳ Pending: 0
+
+   EVENTS: 47 events processed
+
+   TEAM ACTIVITY:
+     ARCHITECT: 6/6 tasks complete
+     STATE-ENGINE: 4/4 tasks complete
+     CLI-ENGINE: 5/5 tasks complete
+     TEMPLATES: 6/6 tasks complete
+     GIT-OPS: 6/6 tasks complete
+   ```
+
+4. **Verbose Mode** (-v flag)
+   - Show all tasks with IDs and owners
+   - List recent events
+   - Show contract status
+   - Display worktree activity
+</process>
+
+<output_formats>
+**Standard:** Summary with counts and milestone
+**Verbose (-v):** Full task list, recent events, team details
+</output_formats>

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

@@ -0,0 +1,24 @@
+---
+name: forge:team-add
+description: Add a new member to the FORGE agent team.
+argument-hint: <name> <role> <agent-type>
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - TeamCreate
+  - Task
+---
+
+Add a new specialist to FORGE team by updating AgentTeam.md and recreating team.
+
+**Read:** .planning/AgentTeam.md, ~/.claude/teams/forge/config.json
+
+**Steps:**
+
+1. Validate AgentTeam.md exists
+2. Prompt for details if not in args: name (kebab-case), role, agent type, model, owned paths
+3. Add member section to AgentTeam.md, increment version
+4. Confirm with user, shutdown old team via SendMessage, recreate with TeamCreate, spawn all teammates
+5. Verify with `/forge:team-view`

package/.claude/commands/forge/team-create.md

@@ -0,0 +1,22 @@
+---
+name: forge:team-create
+description: Create a FORGE agent team from AgentTeam.md specification.
+argument-hint: [--team-name <name>]
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - TeamCreate
+  - Task
+---
+
+Create FORGE agent team from `.planning/AgentTeam.md`.
+
+**Read:** .planning/AgentTeam.md (or .planning/AgentTeam.template.md as reference)
+
+**Steps:**
+
+1. If AgentTeam.md missing, spawn Explore subagent to analyze codebase and generate it
+2. Show team config to user, confirm creation
+3. Create team with TeamCreate, spawn all specialist teammates via Task tool
+4. Verify at `~/.claude/teams/forge/config.json`

package/.claude/commands/forge/team-remove.md

@@ -0,0 +1,24 @@
+---
+name: forge:team-remove
+description: Remove a member from the FORGE agent team.
+argument-hint: <member-name>
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - TeamCreate
+  - Task
+  - SendMessage
+---
+
+Remove specialist $ARGUMENTS from FORGE team by updating AgentTeam.md and recreating team.
+
+**Read:** .planning/AgentTeam.md, ~/.claude/teams/forge/config.json
+
+**Steps:**
+
+1. Show current members, confirm which to remove
+2. Remove member section from AgentTeam.md, renumber remaining, increment version
+3. Shutdown old team, recreate with TeamCreate, spawn remaining teammates
+4. Verify with `/forge:team-view`

package/.claude/commands/forge/team-start.md

@@ -0,0 +1,22 @@
+---
+name: forge:team-start
+description: Start the FORGE agent team by spawning all teammates.
+argument-hint: [--team-name <name>]
+allowed-tools:
+  - Read
+  - Bash
+  - TeamCreate
+  - Task
+---
+
+Spawn all specialist teammates defined in AgentTeam.md.
+
+**Read:** .planning/AgentTeam.md, ~/.claude/teams/forge/config.json
+
+**Steps:**
+
+1. Validate AgentTeam.md exists
+2. Parse all specialist roles (name, agent type, model, prompt)
+3. Check existing team for inactive members
+4. Spawn team-lead first, then all specialists via Task tool
+5. Verify team is active, show member summary

package/.claude/commands/forge/team-view.md

@@ -0,0 +1,18 @@
+---
+name: forge:team-view
+description: View FORGE agent team members and configuration.
+argument-hint: [--team-name <name>]
+allowed-tools:
+  - Read
+  - Bash
+---
+
+Display current FORGE team configuration.
+
+**Read:** ~/.claude/teams/forge/config.json, .planning/AgentTeam.md
+
+**Steps:**
+
+1. Read team config, extract: name, description, members
+2. Display formatted table: name, type, model, role, owned paths, active/idle status
+3. Compare with AgentTeam.md, flag differences

package/.claude/commands/forge/verify.md

@@ -0,0 +1,95 @@
+---
+name: forge:verify
+description: Verify all phase plans against requirements and generate gap closure plans.
+argument-hint: <phase-name>
+allowed-tools:
+  - Read
+  - Write
+  - Glob
+  - Grep
+  - Bash
+  - Task
+---
+
+Verify phase $ARGUMENTS plans cover all requirements via goal-backward analysis. If gaps are found, generate numbered gap closure plan files (same format as regular plans) that can be executed with `/forge:execute {phase} --gaps`.
+
+**Read:** All `.planning/phases/{phase}/*-PLAN.md` files, all `*-SUMMARY.md` files (if execution happened), REQUIREMENTS.md, ROADMAP.md, state/STATE.json
+
+**Steps:**
+
+1. **Discover all plan and summary files:**
+   - Glob `.planning/phases/{phase}/*-PLAN.md` → parse each plan's frontmatter and tasks
+   - Glob `.planning/phases/{phase}/*-SUMMARY.md` → check execution results
+   - Build complete picture: what was planned, what was executed, what succeeded
+
+2. **Requirements coverage** — Map each requirement from REQUIREMENTS.md → plans/tasks that cover it. Mark each as:
+   - **Covered** — task exists and (if executed) summary confirms completion
+   - **Planned** — task exists but not yet executed
+   - **Gap** — no task addresses this requirement
+
+3. **Goal-backward analysis** — For each milestone goal from ROADMAP.md:
+   - Trace: goal → plans → tasks → acceptance criteria
+   - Flag missing links in the chain
+
+4. **Integration completeness** — Check cross-plan contracts defined, integration points covered, no conflicting file modifications across plans in the same wave.
+
+5. **Dependency validation** — Verify plan dependency graph is acyclic, all depends_on references are valid plan numbers, wave assignments are correct.
+
+6. **Scope validation** — Cross-reference with CONTEXT.md:
+   - Deferred ideas should NOT appear in any plan
+   - Locked decisions should be implemented as specified
+   - Claude's discretion areas should have reasonable choices
+
+7. **Write VERIFICATION.md** — `.planning/phases/{phase}/VERIFICATION.md` with:
+   ```markdown
+   # {Phase} Verification
+   **Verified:** [timestamp]
+   **Result:** {PASS | GAPS FOUND}
+
+   ## Requirements Coverage
+   | Requirement | Status | Covered By |
+   |-------------|--------|------------|
+   | REQ-001     | Covered | Plan 01, Task 1 |
+   | REQ-003     | GAP    | — |
+
+   ## Goal-Backward Analysis
+   [Results per goal]
+
+   ## Integration Check
+   [Results]
+
+   ## Dependency Validation
+   [Results]
+
+   ## Scope Validation
+   [Results]
+
+   ## Gaps Summary
+   {count} gaps identified requiring remediation.
+   ```
+
+8. **If gaps found — generate gap closure plan files:**
+   - Determine next plan number (highest existing + 1)
+   - Create `.planning/phases/{phase}/{phase}-{next}-PLAN.md` for each gap cluster
+   - Each gap closure plan uses the same format as regular plans with frontmatter:
+     ```yaml
+     ---
+     phase: {phase-name}
+     plan: {next-number}
+     wave: 1
+     depends_on: []
+     files_modified: [...]
+     autonomous: true
+     gap_closure: true
+     ---
+     ```
+   - Gap closure plans contain 2-3 remediation tasks each (same XML task format)
+   - Number sequentially after existing plans
+   - Gap plan limit: max 3 gap closure plans. If more gaps exist, recommend breaking into sub-phases.
+
+9. **Routing:**
+   - If **no gaps:** "All requirements covered. Ready to execute." → Offer `/forge:execute {phase}`
+   - If **gaps found:** Show gap summary, list generated gap closure plans → Offer `/forge:execute {phase} --gaps` to run only gap closure plans
+   - If **already executed and gaps in results:** Generate plans targeting execution failures
+
+**Pass criteria:** All requirements covered, goals achievable, deps valid, scope aligned with CONTEXT.md.

package/.claude/hooks/forge-context-cleanup.cjs

@@ -0,0 +1,79 @@
+#!/usr/bin/env node
+// FORGE Hook: Context Cleanup (SessionStart)
+// Archives old events, cleans temp files, reports context health
+
+const fs = require('fs');
+const path = require('path');
+
+const cwd = process.cwd();
+const eventsDir = path.join(cwd, 'state', 'events');
+const archiveDir = path.join(cwd, 'state', 'events', 'archive');
+const planningDir = path.join(cwd, '.planning');
+
+// Only run if this looks like a FORGE project
+if (!fs.existsSync(path.join(cwd, 'state', 'STATE.json'))) {
+  process.exit(0);
+}
+
+let archived = 0;
+let cleaned = 0;
+
+// 1. Archive events older than 7 days
+if (fs.existsSync(eventsDir)) {
+  const cutoff = Date.now() - (7 * 24 * 60 * 60 * 1000);
+  const files = fs.readdirSync(eventsDir)
+    .filter(f => f.endsWith('.json') && f !== 'archive');
+
+  for (const file of files) {
+    const fp = path.join(eventsDir, file);
+    try {
+      const stat = fs.statSync(fp);
+      if (stat.mtime.getTime() < cutoff) {
+        if (!fs.existsSync(archiveDir)) {
+          fs.mkdirSync(archiveDir, { recursive: true });
+        }
+        fs.renameSync(fp, path.join(archiveDir, file));
+        archived++;
+      }
+    } catch (e) {}
+  }
+}
+
+// 2. Clean up orphaned .continue-here.md if older than 3 days
+const continueFile = path.join(cwd, '.continue-here.md');
+if (fs.existsSync(continueFile)) {
+  try {
+    const stat = fs.statSync(continueFile);
+    const age = Date.now() - stat.mtime.getTime();
+    if (age > 3 * 24 * 60 * 60 * 1000) {
+      fs.unlinkSync(continueFile);
+      cleaned++;
+    }
+  } catch (e) {}
+}
+
+// 3. Clean up empty quick task dirs
+const quickDir = path.join(planningDir, 'quick');
+if (fs.existsSync(quickDir)) {
+  const dirs = fs.readdirSync(quickDir);
+  for (const dir of dirs) {
+    const dp = path.join(quickDir, dir);
+    try {
+      if (fs.statSync(dp).isDirectory()) {
+        const contents = fs.readdirSync(dp);
+        if (contents.length === 0) {
+          fs.rmdirSync(dp);
+          cleaned++;
+        }
+      }
+    } catch (e) {}
+  }
+}
+
+// Report if anything happened
+if (archived > 0 || cleaned > 0) {
+  const parts = [];
+  if (archived > 0) parts.push(`archived ${archived} old event(s)`);
+  if (cleaned > 0) parts.push(`cleaned ${cleaned} temp file(s)`);
+  process.stderr.write(`\x1b[34m→ FORGE cleanup: ${parts.join(', ')}\x1b[0m\n`);
+}