forge-dev-framework 1.0.1 → 1.2.0

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

@@ -0,0 +1,78 @@
+---
+name: forge:discuss
+description: Capture project context and identify gray areas for a phase.
+argument-hint: <phase-name>
+allowed-tools:
+  - Read
+  - Write
+  - Glob
+  - Grep
+  - Bash
+  - AskUserQuestion
+---
+
+Extract implementation decisions for phase $ARGUMENTS that downstream agents (researcher, planner) need. The user is the visionary — you are the builder asking clarifying questions.
+
+**Read first:** ROADMAP.md, REQUIREMENTS.md, state/STATE.json
+
+**Steps:**
+
+1. **Initialize** — Read ROADMAP.md, REQUIREMENTS.md, STATE.json. Validate the phase exists in the roadmap. Extract the phase goal and scope statement.
+
+2. **Check existing** — If `.planning/phases/{phase}/CONTEXT.md` exists, use AskUserQuestion:
+   - "Update existing context" — re-run discussion, merge new answers
+   - "View current context" — display CONTEXT.md and stop
+   - "Skip (use existing)" — proceed to offering next command
+
+3. **Analyze phase for gray areas** — Based on the phase goal from ROADMAP.md, identify 3-4 **concrete** gray areas specific to THIS phase. Do NOT use generic categories (UI, UX, Behavior). Instead, identify real decisions:
+   - For a visual feature → presentation choices, interaction patterns, layout decisions
+   - For a CLI tool → flag design, output format, error messaging style
+   - For an API → contract shape, auth strategy, error handling patterns
+   - For infrastructure → deployment strategy, monitoring approach, scaling model
+   - Each gray area should be a specific decision point, e.g. "Layout style", "Loading behavior", "Error recovery strategy"
+
+4. **Present gray areas** — Use AskUserQuestion (multiSelect: true) with the 3-4 phase-specific gray areas. User picks which ones to discuss.
+
+5. **Discuss selected areas** — For each selected area:
+   - Ask up to 4 questions via AskUserQuestion with concrete options (not abstract)
+   - Always include a "You decide (Claude's discretion)" option where reasonable — this captures areas where the planner has flexibility
+   - After 4 questions, ask: "More questions about [area], or move to next?"
+   - If user introduces scope creep (new capability beyond this phase), redirect: "That sounds like a new capability — I'll note it under Deferred Ideas for a future phase."
+
+6. **Write CONTEXT.md** — Create `.planning/phases/{phase}/CONTEXT.md` with this structure:
+
+   ```markdown
+   # Phase [X]: [Name] - Context
+   **Gathered:** [date]
+   **Status:** Ready for planning
+
+   ## Phase Boundary
+   [Clear scope statement from ROADMAP.md — fixed, not negotiable]
+
+   ## Implementation Decisions
+   ### [Area 1 discussed]
+   - [Specific decision made]
+   - [Another decision]
+   ### [Area 2 discussed]
+   - [Specific decision made]
+
+   ## Claude's Discretion
+   [Areas where user said "you decide" — flexibility for planner/researcher]
+   - [Area]: [What Claude can choose freely]
+
+   ## Specific Ideas
+   [Any references, inspirations, or "I want it like X" moments from discussion]
+
+   ## Deferred Ideas
+   [Scope creep captured here — explicitly out of scope for this phase]
+   - [Idea]: [Why it was deferred]
+   ```
+
+7. **Commit and offer next step** — Offer `/forge:plan {phase}` to proceed.
+
+**Downstream contract — who reads CONTEXT.md and how:**
+- **Researcher** reads CONTEXT.md to know WHAT to research:
+  - Locked decisions → research deeply, don't explore alternatives
+  - Claude's discretion → research options and recommend best approach
+  - Deferred ideas → ignore completely
+- **Planner** reads CONTEXT.md to know WHAT choices are locked (implement exactly), flexible (can choose), and out of scope (must not include)

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

@@ -0,0 +1,85 @@
+---
+name: forge:execute
+description: Execute all plans in a phase with wave-based parallelization.
+argument-hint: <phase-name> [--gaps]
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - TaskList
+  - TaskCreate
+  - TaskUpdate
+  - TaskGet
+  - SendMessage
+  - Task
+---
+
+Execute phase $ARGUMENTS by discovering all plan files, grouping by wave, and executing waves sequentially with plans within each wave in parallel.
+
+**Flag support:** If `$ARGUMENTS` contains `--gaps`, only execute plans with `gap_closure: true` in their frontmatter. Parse the phase name by stripping `--gaps` from arguments.
+
+**Read first:** All `.planning/phases/{phase}/*-PLAN.md` files, `.planning/phases/{phase}/CONTEXT.md`, state/STATE.json
+
+**Steps:**
+
+1. **Parse arguments and discover plans:**
+   - Extract phase name, check for `--gaps` flag
+   - Glob `.planning/phases/{phase}/*-PLAN.md` → parse YAML frontmatter of each
+   - Extract from each: plan number, wave, depends_on, autonomous, files_modified, gap_closure
+   - Skip plans that have a matching `*-SUMMARY.md` (already executed)
+   - If `--gaps`: only include plans where `gap_closure: true`
+   - If no plans found, error: suggest running `/forge:plan {phase}` first
+   - Report: "Found {N} plans in {M} waves ({K} incomplete)"
+
+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. **Create EXECUTION.md** — `.planning/phases/{phase}/EXECUTION.md` with wave/plan status table:
+   ```markdown
+   # {Phase} Execution Log
+   **Started:** [timestamp]
+
+   | Wave | Plan | Objective | Status | Commit |
+   |------|------|-----------|--------|--------|
+   | 1    | 01   | [from plan] | pending | — |
+   | 1    | 02   | [from plan] | pending | — |
+   | 2    | 03   | [from plan] | pending | — |
+   ```
+
+4. **Wave execution loop** (sequential between waves, parallel within):
+   For each wave in order:
+   - Describe what this wave builds (from plan objectives — substantive, not just plan numbers)
+   - Spawn one executor agent per plan via Task tool (subagent_type: "general-purpose"). Each executor:
+     - Reads their specific `{phase}-{NN}-PLAN.md`
+     - Reads CONTEXT.md for locked decisions and RESEARCH.md for technical guidance
+     - Executes tasks following the plan exactly
+     - Atomic commit per task: `type(phase-plan): description`
+     - Creates `{phase}-{NN}-SUMMARY.md` on completion with:
+       ```markdown
+       # Plan {NN} Summary
+       **Completed:** [timestamp]
+       ## What was built
+       ## Files changed
+       ## Commits
+       ## Issues encountered (if any)
+       ```
+   - Wait for all wave agents to complete
+   - Spot-check: verify SUMMARY.md exists for each plan, git commits present
+   - Update EXECUTION.md after each plan completes
+   - Report wave completion with what was built
+   - Proceed to next wave automatically (do NOT ask user between waves)
+
+5. **Cross-domain work:** If a plan touches another teammate's files, use REQUEST_CONTRACT event → provider publishes to contracts/ → both work against contract
+
+6. **State:** Agents write events to state/events/, State Steward merges → STATE.json
+
+7. **On completion:**
+   - Aggregate all SUMMARY.md files into final EXECUTION.md status
+   - Submit phase completion events
+   - Offer `/forge:verify {phase}` to validate results
+
+**Prefer existing teammates** over spawning new ones. Only spawn if the task domain is truly uncovered by current team members.

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

@@ -0,0 +1,21 @@
+---
+name: forge:generate
+description: Generate a FORGE artifact from templates.
+argument-hint: <artifact-name> [-f]
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+---
+
+Generate artifact $ARGUMENTS (claude, project, requirements, roadmap, plan, config, rules).
+
+**Read:** state/STATE.json, src/templates/
+
+**Artifact mapping:** claude→CLAUDE.md | requirements→REQUIREMENTS.md | roadmap→ROADMAP.md | plan→PLAN.md | config→.planning/forge.config.json | rules→.claude/rules/*.md
+
+**Steps:**
+
+1. Load context from STATE.json (projectName, version, tasks, milestones). Error if required fields missing.
+2. Render template. Check token limits: CLAUDE.md ~2000, REQUIREMENTS.md ~4000, PLAN.md ~6000, rules ~1000 each.
+3. Backup existing file (unless `-f` flag), write artifact, verify format.

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

@@ -0,0 +1,18 @@
+---
+name: forge:help
+description: Show FORGE command reference.
+argument-hint: [command-name]
+allowed-tools:
+  - Read
+---
+
+Show FORGE command reference. Read `.claude/commands/forge/README.md` for full details.
+
+**Core:** `init`, `status`, `config`, `help`, `generate`
+**Planning:** `discuss`, `plan`, `verify`
+**Execution:** `execute`, `quick`, `debug`, `resume`, `pause-work`
+**Team:** `team-create`, `team-start`, `team-view`, `team-add`, `team-remove`
+**Roadmap:** `new-milestone`, `complete-milestone`, `add-phase`, `remove-phase`, `insert-phase`
+**Migration:** `convert`, `new-project`
+
+For specific command help, read the command's md file in `.claude/commands/forge/`.

package/.claude/commands/forge/init.md

@@ -0,0 +1,21 @@
+---
+name: forge:init
+description: Initialize FORGE in the current project directory.
+argument-hint: [--quick]
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - TeamCreate
+---
+
+Initialize FORGE in current directory. Use `--quick` to skip prompts.
+
+**Steps:**
+
+1. Create dirs: state/events, contracts, .planning, .claude/rules, src/{cli,commands,generators,git,utils}, .github/workflows, .worktrees
+2. Generate CLAUDE.md template, state/STATE.json, .planning/forge.config.json
+3. If no AgentTeam.md, analyze codebase via Explore subagent and generate one. Create team with TeamCreate.
+4. Git setup: .gitignore, init repo, pre-commit hooks
+5. Dependencies: package.json, install chalk/commander/execa/zod/handlebars
+6. Verify: `npm run build`, `/forge:status`

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

@@ -0,0 +1,99 @@
+---
+name: forge:insert-phase
+description: Insert urgent work as decimal phase between existing phases
+argument-hint: <after-phase> <description>
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+---
+
+<objective>
+Insert urgent work as a decimal phase between existing phases in the roadmap.
+
+Use when: Urgent bug fix, hotfix, or critical work must be done before continuing current work.
+
+Decimal phase format: `X.Y` where X is parent phase, Y increments (0.1, 0.2, etc.)
+</objective>
+
+<execution_context>
+@state/STATE.json
+@ROADMAP.md
+@CLAUDE.md
+</execution_context>
+
+<context>
+**After Phase:** First argument (e.g., "72")
+**Description:** Second argument
+
+**Decimal Phase Assignment:**
+1. Find existing decimal phases under parent
+2. Calculate next decimal (0.1, 0.2, 0.3, etc.)
+3. Insert into roadmap after parent phase
+4. Update phase dependencies if needed
+</context>
+
+<process>
+**Execute insert-phase workflow:**
+
+1. **Parse Arguments**
+   - Extract parent phase number (e.g., "72")
+   - Extract phase description
+
+2. **Load State**
+   - Read state/STATE.json
+   - Read ROADMAP.md
+   - Find parent phase entry
+
+3. **Calculate Decimal Phase**
+   - Find existing decimals under parent (72.1, 72.2, etc.)
+   - Next decimal = highest + 0.1
+   - Example: If 72.1, 72.2 exist → next is 72.3
+
+4. **Generate Slug**
+   - Create URL-safe slug from description
+   - Format: `<decimal-phase>-<slug>`
+   - Example: "Hotfix auth bug" → "72.3-hotfix-auth-bug"
+
+5. **Create Directory Structure**
+   ```bash
+   mkdir -p .planning/phases/<phase-slug>/
+   touch .planning/phases/<phase-slug>/CONTEXT.md
+   touch .planning/phases/<phase-slug>/PLAN.md
+   ```
+
+6. **Update ROADMAP.md**
+   - Insert new phase entry immediately after parent phase
+   - Use standard phase format with decimal number
+   - Note as "INSERTED" for visibility
+
+7. **Update Dependencies**
+   - If parent phase had dependents, add decimal phase as new dependency
+   - Example: Phase 73 depends on 72, insert 72.3 → 73 now depends on 72.3
+
+8. **Submit Event**
+   - Event type: PHASE_INSERTED
+   - Include: phaseId, parentPhaseId, milestoneId, description
+   - Write to state/events/
+
+9. **Confirm**
+   - Show inserted phase info
+   - List any updated dependencies
+   - 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 inserted phase
+- Updated dependencies for subsequent phases
+- Event: PHASE_INSERTED 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
+- Notify team of dependency changes
+- Tip: Use `/clear` to start from a fresh context
+</next_steps>

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

@@ -0,0 +1,114 @@
+---
+name: forge:new-milestone
+description: Start new milestone cycle — update ROADMAP.md and route to requirements
+argument-hint: ""
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+---
+
+<objective>
+Initialize a new milestone cycle in the ROADMAP.md after completing the previous one.
+
+Updates ROADMAP.md structure and routes to requirements gathering for the new milestone.
+</objective>
+
+<execution_context>
+@state/STATE.json
+@ROADMAP.md
+@CLAUDE.md
+</execution_context>
+
+<context>
+**New Milestone Workflow:**
+1. Validate previous milestone is complete
+2. Get milestone details (name, goals)
+3. Create new milestone section in ROADMAP.md
+4. Update STATE.json
+5. Route to requirements gathering
+</context>
+
+<process>
+**Execute new-milestone workflow:**
+
+1. **Validate Previous Milestone**
+   - Check STATE.json for current milestone status
+   - If "in_progress" → warn: "Previous milestone not complete. Continue?"
+   - If "completed" → proceed
+
+2. **Gather Milestone Details**
+   Use AskUserQuestion:
+   - **Milestone Name**: What is this milestone called?
+   - **Milestone Goals**: What are the primary goals?
+   - **Success Criteria**: How do we know it's complete?
+   - **Estimated Duration**: How long will this take?
+
+3. **Calculate Milestone Number**
+   - Find last milestone in ROADMAP.md
+   - Increment by 1 (e.g., M2 → M3)
+
+4. **Update ROADMAP.md**
+   ```markdown
+   ## Milestone {number}: {name}
+
+   **Status:** 🚧 In Progress
+   **Started:** {date}
+   **Goals:** {goals}
+
+   ### Success Criteria
+   - {criterion-1}
+   - {criterion-2}
+
+   ### Phases
+   _Phases will be added here_
+
+   ---
+   ```
+
+5. **Update STATE.json**
+   ```json
+   {
+     "project": {
+       "currentMilestone": "M{number}",
+       "currentPhase": null,
+       "status": "in_progress"
+     }
+   }
+   ```
+
+6. **Submit Events**
+   - Event type: MILESTONE_STARTED
+   - Include: milestoneId, name, goals
+   - Write to state/events/
+
+7. **Create Milestone Directory**
+   ```bash
+   mkdir -p .planning/phases/
+   ```
+
+8. **Route to Requirements**
+   - Suggest: Run `/forge:generate requirements` or manual requirements gathering
+   - Ask: "Do you want to gather requirements now?"
+     - Yes: Route to requirements workflow
+     - No: Complete, user can gather later
+
+9. **Confirm**
+   - Show new milestone details
+   - Display ROADMAP.md structure
+   - Provide next steps
+</process>
+
+<deliverables>
+- ROADMAP.md updated (new milestone section added)
+- STATE.json updated (currentMilestone set)
+- Event: MILESTONE_STARTED in state/events/
+- .planning/phases/ ready for new phases
+</deliverables>
+
+<next_steps>
+- Gather requirements: `forge generate requirements` or manual
+- Add phases: `forge add-phase "description"`
+- Discuss phase: `forge discuss <phase>`
+- Plan phase: `forge plan <phase>`
+</next_steps>

package/.claude/commands/forge/new-project.md

@@ -0,0 +1,24 @@
+---
+name: forge:new-project
+description: Initialize a new FORGE project with team coordination and state engine.
+argument-hint: [project-name]
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - TeamCreate
+  - AskUserQuestion
+---
+
+Create a new FORGE multi-agent development project.
+
+**Steps:**
+
+1. Create project directory (if name provided), create FORGE structure: state/, contracts/, .planning/, .claude/rules/, src/
+2. Generate CLAUDE.md, REQUIREMENTS.md, ROADMAP.md, PLAN.md
+3. Initialize state/STATE.json, STATE.schema.json, state/events/
+4. Create FORGE team with TeamCreate, set up .claude/rules/ and CODEOWNERS
+5. Set up templates in src/templates/, configure token limits
+6. Git init, .worktrees/, pre-commit hooks, .github/workflows/
+7. Verify: `npm run build`, `npm test`, `/forge:status`
+8. Show next steps: `/forge:discuss` → `/forge:plan` → `/forge:execute`

package/.claude/commands/forge/pause-work.md

@@ -0,0 +1,111 @@
+---
+name: forge:pause-work
+description: Create context handoff when pausing work mid-phase
+argument-hint: ""
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+---
+
+<objective>
+Create `.continue-here.md` handoff file to preserve complete work state across sessions.
+
+Use when: You need to stop work mid-phase and want to resume later with full context preserved.
+</objective>
+
+<execution_context>
+@state/STATE.json
+@CLAUDE.md
+</execution_context>
+
+<context>
+**Pause Work Workflow:**
+1. Detect current phase from recent files
+2. Gather complete state (position, completed work, remaining work, decisions, blockers)
+3. Create handoff file with all context sections
+4. Git commit as WIP
+5. Provide resume instructions
+</context>
+
+<process>
+**Execute pause-work workflow:**
+
+1. **Detect Current Phase**
+   - Check git status for recent changes
+   - Identify phase from recent files
+   - Check STATE.json for current phase
+
+2. **Gather State**
+   Use AskUserQuestion to capture:
+   - **Current Position**: What were you working on?
+   - **Completed Work**: What's done since last commit?
+   - **Remaining Work**: What's left to do?
+   - **Decisions Made**: Any decisions to remember?
+   - **Blockers**: Anything blocking progress?
+   - **Next Steps**: What to do when resuming?
+
+3. **Create Handoff File**
+   ```markdown
+   # Continue Here — {timestamp}
+
+   ## Phase
+   **Phase:** {phase-name}
+   **Status:** {in-progress|blocked|waiting}
+
+   ## Position
+   {current position in the work}
+
+   ## Completed Work
+   - [x] {completed item 1}
+   - [x] {completed item 2}
+
+   ## Remaining Work
+   - [ ] {remaining item 1}
+   - [ ] {remaining item 2}
+
+   ## Decisions Made
+   {important decisions to remember}
+
+   ## Blockers
+   {anything blocking progress}
+
+   ## Next Steps
+   1. {first step}
+   2. {second step}
+
+   ## Context Notes
+   {any other context}
+
+   ---
+   **Paused:** {timestamp}
+   **Resume:** Run `/forge:resume`
+   ```
+
+4. **Git Commit**
+   - Stage all changes: `git add -A`
+   - Commit as WIP: `git commit -m "wip: pause work - {phase-name}"`
+
+5. **Submit Event**
+   - Event type: WORK_PAUSED
+   - Include: phaseId, handoffFile, timestamp
+   - Write to state/events/
+
+6. **Confirm**
+   - Show handoff file location
+   - Provide resume instructions
+   - Confirm git commit created
+</process>
+
+<deliverables>
+- .continue-here.md (complete handoff file)
+- Git commit: "wip: pause work - {phase-name}"
+- Event: WORK_PAUSED in state/events/
+- STATE.json updated
+</deliverables>
+
+<next_steps>
+- When ready to continue: `/forge:resume`
+- Handoff file will be automatically loaded
+- All context preserved
+</next_steps>