forge-dev-framework 1.1.0 → 1.2.0

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

@@ -1,125 +1,78 @@
 ---
 name: forge:discuss
-description: Capture project context and identify gray areas for a specific phase. Use when user says "forge discuss <phase>" or wants to gather context before planning.
+description: Capture project context and identify gray areas for a phase.
 argument-hint: <phase-name>
 allowed-tools:
   - Read
   - Write
+  - Glob
+  - Grep
+  - Bash
   - AskUserQuestion
 ---
 
-<objective>
-Gather project context through adaptive questioning for a specific phase, identifying gray areas and knowledge gaps before planning.
-
-Purpose: Capture domain knowledge, requirements, constraints, and acceptance criteria.
-Output: Context document (.planning/phases/<phase>/CONTEXT.md) with captured information.
-</objective>
-
-<execution_context>
-**Load these files NOW:**
-
-- @CLAUDE.md (FORGE patterns and conventions)
-- @ROADMAP.md (Milestone and phase breakdown)
-- @REQUIREMENTS.md (Project requirements)
-- @state/STATE.json (Current project state)
-</execution_context>
-
-<context>
-**Phase:** $ARGUMENTS (e.g., "M2-planning-engine", "api-integration", "frontend-auth")
-**Target:** Context capture before planning
-
-**Context Areas to Explore:**
-- Domain knowledge and constraints
-- Technical requirements and NFRs
-- Dependencies and integrations
-- Acceptance criteria and success metrics
-- Risks and unknowns
-- File ownership boundaries
-</context>
-
-<process>
-**Execute context capture workflow:**
-
-1. **Initialize Context Session**
-   ```bash
-   mkdir -p .planning/phases/<phase-name>
-   touch .planning/phases/<phase-name>/CONTEXT.md
-   ```
+Extract implementation decisions for phase $ARGUMENTS that downstream agents (researcher, planner) need. The user is the visionary — you are the builder asking clarifying questions.
 
-2. **Adaptive Questioning**
-   - Ask targeted questions based on phase type
-   - Explore dependencies and integration points
-   - Identify gray areas requiring research
-   - Capture constraints and preferences
-
-3. **Question Categories:**
-
-   **For Backend/API Phases:**
-   - API contracts and endpoints
-   - Data models and schemas
-   - Authentication/authorization
-   - Performance requirements
-   - External dependencies
-
-   **For Frontend/UI Phases:**
-   - Component hierarchy
-   - State management approach
-   - Design system and patterns
-   - User interaction flows
-   - Accessibility requirements
-
-   **For Infrastructure Phases:**
-   - Deployment architecture
-   - CI/CD requirements
-   - Monitoring and observability
-   - Security and compliance
-   - Scalability constraints
-
-4. **Document Context**
-   ```markdown
-   # <Phase Name> Context
+**Read first:** ROADMAP.md, REQUIREMENTS.md, state/STATE.json
+
+**Steps:**
 
-   ## Overview
-   [Purpose and goals]
+1. **Initialize** — Read ROADMAP.md, REQUIREMENTS.md, STATE.json. Validate the phase exists in the roadmap. Extract the phase goal and scope statement.
 
-   ## Requirements
-   - Functional requirements
-   - Non-functional requirements
+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
 
-   ## Constraints
-   - Technical constraints
-   - Time/resource constraints
+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"
 
-   ## Dependencies
-   - Internal dependencies
-   - External services
+4. **Present gray areas** — Use AskUserQuestion (multiSelect: true) with the 3-4 phase-specific gray areas. User picks which ones to discuss.
 
-   ## Gray Areas
-   - Items requiring research
-   - Unknowns to investigate
+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."
 
-   ## Acceptance Criteria
-   - Success metrics
-   - Definition of done
+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]
    ```
 
-5. **State Update**
-   - Submit PHASE_CONTEXT_CAPTURED event
-   - Update STATE.json with phase context
-
-6. **Handoff to Planning**
-   - Offer `forge plan <phase>` to generate tasks
-   - Identify research needs (use research agents)
-</process>
-
-<deliverables>
-- .planning/phases/<phase>/CONTEXT.md (captured context)
-- Event: PHASE_CONTEXT_CAPTURED in state/events/
-- STATE.json updated with phase status
-</deliverables>
-
-<next_steps>
-- Run `forge plan <phase>` to generate atomic task breakdown
-- Use research agents for gray areas
-- Proceed to task execution with agent teams
-</next_steps>
+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

@@ -1,160 +1,85 @@
 ---
 name: forge:execute
-description: Execute all tasks in a phase with agent team coordination and parallel execution. Use when user says "forge execute <phase>" or wants to run a planned phase.
-argument-hint: <phase-name>
+description: Execute all plans in a phase with wave-based parallelization.
+argument-hint: <phase-name> [--gaps]
 allowed-tools:
   - Read
   - Write
   - Bash
-  - Task
+  - TaskList
+  - TaskCreate
+  - TaskUpdate
+  - TaskGet
   - SendMessage
+  - Task
 ---
 
-<objective>
-Execute all tasks in a phase using agent teams with wave-based parallelization, contract-first protocol, and atomic commits.
-
-Purpose: Execute planned tasks with multi-agent coordination.
-Output: All tasks complete, verified, integrated, and committed.
-</objective>
-
-<execution_context>
-**Load these files NOW:**
+Execute phase $ARGUMENTS by discovering all plan files, grouping by wave, and executing waves sequentially with plans within each wave in parallel.
 
-- @CLAUDE.md (Wipe protocol, atomic commits, file ownership)
-- @.planning/phases/<phase>/PLAN.md (Task list and dependencies)
-- @.planning/phases/<phase>/CONTEXT.md (Phase context)
-- @state/STATE.json (Current state)
-- @contracts/ (API contracts)
-</execution_context>
+**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.
 
-<context>
-**Phase:** $ARGUMENTS
-**Execution Mode:** Wave-based parallelization
-**Protocol:** Wipe Protocol (fresh agent context per task)
+**Read first:** All `.planning/phases/{phase}/*-PLAN.md` files, `.planning/phases/{phase}/CONTEXT.md`, state/STATE.json
 
-**Execution Constraints:**
-- One task = one git commit (atomic)
-- Agents write only within owned paths
-- Contracts required before cross-domain work
-- Worktree isolation for parallel tasks
-</context>
+**Steps:**
 
-<process>
-**Execute phase with agent teams:**
-
-1. **Load Plan**
-   - Read PLAN.md for task list
-   - Build dependency graph
-   - Identify parallel execution waves
-
-2. **Create Agent Team**
-   ```bash
-   forge deploy <phase>
-   # Spawns team with specialists based on plan
-   ```
-
-3. **Wave-Based Execution**
-
-   **Wave 1:** Tasks with no dependencies (parallel)
-   ```
-   Spawn agents for:
-   - api-001 → backend-agent
-   - core-001 → core-engine
-   - ui-001 → frontend-agent
-   ```
-
-   **Wave 2:** Tasks after Wave 1 complete
-   ```
-   - api-002 → backend-agent (depends on api-001)
-   - ui-002 → frontend-agent (depends on ui-001)
-   ```
+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)"
 
-   **Wave 3+:** Continue until all tasks complete
+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.
 
-4. **Per-Task Execution** (Wipe Protocol)
-   ```
-   For each task:
-   a. Hydrate: Agent reads CLAUDE.md + STATE.json + task + contracts
-   b. Execute: Agent writes code, runs tests
-   c. Commit: Atomic git commit (one task = one commit)
-   d. Verify: Run acceptance tests
-   e. Terminate: Agent context wiped
-   ```
+3. **Create EXECUTION.md** — `.planning/phases/{phase}/EXECUTION.md` with wave/plan status table:
+   ```markdown
+   # {Phase} Execution Log
+   **Started:** [timestamp]
 
-5. **Contract-First Coordination**
-   ```
-   If agent needs interface from another domain:
-   - Write REQUEST_CONTRACT event
-   - Provider publishes contract to contracts/
-   - Both work against agreed contract
-   - Integration at merge time
+   | Wave | Plan | Objective | Status | Commit |
+   |------|------|-----------|--------|--------|
+   | 1    | 01   | [from plan] | pending | — |
+   | 1    | 02   | [from plan] | pending | — |
+   | 2    | 03   | [from plan] | pending | — |
    ```
 
-6. **State Updates**
-   - Each agent submits events to state/events/
-   - State Steward merges events → STATE.json
-   - Progress tracked in real-time
-
-7. **Integration & Verification**
-   - Run integration tests
-   - Verify end-to-end flows
-   - Check requirements coverage
-   - Create VERIFICATION.md
-
-8. **Completion**
-   - All tasks marked complete in STATE.json
-   - Phase marked done
-   - Git tag created: forge/<phase>-complete
-   - Summary generated
-</process>
-
-<deliverables>
-- All tasks complete and verified
-- Git commits (one per task) with conventional format
-- .planning/phases/<phase>/VERIFICATION.md
-- Updated state/STATE.json
-- state/events/ with all task events
-- Integration tests passing
-</deliverables>
-
-<atomic_commit_format>
-Each commit follows conventional format:
-```
-type(scope): description
-
-Examples:
-feat(api-003): implement session authentication
-fix(ui-002): resolve login form validation bug
-test(core-001): add database integration tests
-```
-</atomic_commit_format>
-
-<wipe_protocol>
-**Per-Task Context Lifecycle:**
-1. Hydrate → Load CLAUDE.md + STATE.json + task + contracts
-2. Execute → Write code, run tests
-3. Commit → Atomic git commit
-4. Terminate → Session ends, context wiped
-5. Reincarnate → Next task starts fresh
-
-This prevents hallucination carry-over and context rot.
-</wipe_protocol>
-
-<verification>
-After execution completes:
-- ✅ All tasks marked complete
-- ✅ All tests passing
-- ✅ Integration tests pass
-- ✅ Requirements verified
-- ✅ One commit per task
-- ✅ Conventional commit format
-- ✅ No merge conflicts
-- ✅ Files within ownership boundaries
-</verification>
-
-<next_steps>
-- Run `forge status` to confirm completion
-- Review VERIFICATION.md for details
-- Proceed to next phase or milestone
-- Archive phase with `forge archive <phase>`
-</next_steps>
+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

@@ -1,6 +1,6 @@
 ---
 name: forge:generate
-description: Generate a specific FORGE artifact from templates. Use when user says "forge generate <artifact>" to create CLAUDE.md, REQUIREMENTS.md, etc.
+description: Generate a FORGE artifact from templates.
 argument-hint: <artifact-name> [-f]
 allowed-tools:
   - Read
@@ -8,113 +8,14 @@ allowed-tools:
   - Bash
 ---
 
-<objective>
-Generate specific FORGE artifacts from templates, including CLAUDE.md, REQUIREMENTS.md, ROADMAP.md, PLAN.md, config files, and rule files.
+Generate artifact $ARGUMENTS (claude, project, requirements, roadmap, plan, config, rules).
 
-Purpose: Create or update FORGE artifacts with project-specific content.
-Output: Generated artifact file with validated content.
-</objective>
+**Read:** state/STATE.json, src/templates/
 
-<execution_context>
-**Load these files NOW:**
+**Artifact mapping:** claude→CLAUDE.md | requirements→REQUIREMENTS.md | roadmap→ROADMAP.md | plan→PLAN.md | config→.planning/forge.config.json | rules→.claude/rules/*.md
 
-- @src/commands/generate.ts (Generate command implementation)
-- @src/generators/index.ts (Template engine)
-- @src/templates/ (Template files)
-- @state/STATE.json (Project context)
-</execution_context>
+**Steps:**
 
-<context>
-**Artifact:** $ARGUMENTS (claude, project, requirements, roadmap, plan, config, rules)
-**Force Mode:** -f flag overwrites without backup
-**Context:** Loaded from STATE.json or user input
-</context>
-
-<process>
-**Execute generate command:**
-
-1. **Map Artifact to Template**
-
-   | Artifact | Template | Output | Required Fields |
-   |----------|----------|--------|-----------------|
-   | claude | CLAUDE.md.template | CLAUDE.md | projectName, vision, techStack |
-   | project | PROJECT.md.template | PROJECT.md | projectName, vision, techStack |
-   | requirements | REQUIREMENTS.md.template | REQUIREMENTS.md | projectName, vision, features, nfrs |
-   | roadmap | ROADMAP.md.template | ROADMAP.md | projectName, milestones, phases |
-   | plan | PLAN.md.template | PLAN.md | tasks, dependencyGraph |
-   | config | forge.config.json.template | .planning/forge.config.json | mode, depth, maxTeammates, taskLimit |
-   | rules | .claude/rules/*.md.template | .claude/rules/ | patterns, rules |
-
-2. **Load Context**
-   - Read state/STATE.json for project data
-   - Extract: projectName, version, status, tasks, milestones
-   - If missing fields, prompt user or error
-
-3. **Validate Required Fields**
-   - Check all required fields present
-   - Error if missing (suggest `forge init`)
-   - Show missing fields list
-
-4. **Render Template**
-   ```typescript
-   const result = await templateEngine.render(templateName, context);
-   // Returns: { content, tokenCount, withinLimit, warnings }
-   ```
-
-5. **Token Limit Check**
-   - CLAUDE.md: ~2000 tokens max
-   - REQUIREMENTS.md: ~4000 tokens max
-   - PLAN.md: ~6000 tokens max
-   - Rules: ~1000 tokens each
-
-   If over limit:
-   - Show warning with suggestions
-   - Offer to proceed or reduce
-
-6. **Backup Existing** (unless -f flag)
-   - Copy existing file to .backup
-   - Inform user of backup location
-
-7. **Write Artifact**
-   - Write rendered content to output path
-   - Log success with token count
-   - Show output location
-
-8. **Verify**
-   - Check file exists
-   - Validate format (JSON for config, MD for others)
-   - Run `forge status` to confirm
-</process>
-
-<examples>
-```bash
-# Generate CLAUDE.md
-forge generate claude
-
-# Generate REQUIREMENTS.md
-forge generate requirements
-
-# Generate ROADMAP.md
-forge generate roadmap
-
-# Generate with force (no backup)
-forge generate plan -f
-
-# Generate config file
-forge generate config
-```
-</examples>
-
-<deliverables>
-- Generated artifact file
-- Backup of existing file (if not -f)
-- Token count and limit status
-</deliverables>
-
-<validation>
-- ✅ Required fields present
-- ✅ Template exists
-- ✅ Token limit within bounds
-- ✅ Output path writable
-- ✅ Format valid (JSON/MD)
-</validation>
+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

@@ -1,123 +1,18 @@
 ---
 name: forge:help
-description: Show comprehensive FORGE command reference and usage guide. Use when user asks "forge help" or wants to see available commands.
+description: Show FORGE command reference.
 argument-hint: [command-name]
 allowed-tools:
   - Read
 ---
 
-<objective>
-Display comprehensive FORGE command reference with descriptions, usage examples, and links to detailed documentation.
+Show FORGE command reference. Read `.claude/commands/forge/README.md` for full details.
 
-Purpose: Help users discover and understand FORGE capabilities.
-Output: Formatted command reference with examples.
-</objective>
+**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`
 
-<execution_context>
-**Load these files NOW:**
-
-- @ROADMAP.md (Implementation status)
-- @CLAUDE.md (Architecture overview)
-</execution_context>
-
-<context>
-**Command Scope:** All FORGE commands (implemented and stubs)
-**Detail Level:** Summary (all commands) or detailed (specific command)
-</context>
-
-<process>
-**Display command reference:**
-
-## FORGE Commands
-
-### Core Commands (Implemented)
-
-```bash
-forge init [--quick]              # Initialize FORGE project
-forge status [-v]                 # Show project status
-forge config [key] [value]        # View/edit configuration
-forge help [command]              # Show this help
-forge generate <artifact>          # Generate specific artifact
-```
-
-### Planning Commands (Milestone 2 - In Progress)
-
-```bash
-forge discuss <phase>              # Capture phase context
-forge plan <phase>                # Generate task breakdown
-forge verify <phase>              # Verify plan against requirements
-```
-
-### Execution Commands (Milestone 3 - Planned)
-
-```bash
-forge deploy <phase>               # Deploy agent team for phase
-forge assign <task-id> <agent>    # Assign task to specialist
-forge commit <task-id>            # Create atomic commit for task
-```
-
-### Review Commands (Milestone 4 - Planned)
-
-```bash
-forge tribunal <phase>             # Adversarial review
-forge critique <file>             # Security/quality review
-```
-
-### Utility Commands
-
-```bash
-forge generate <artifact>          # Generate artifact
-  Artifacts: claude, project, requirements, roadmap, plan, config, rules
-
-forge worktree <task-id>          # Create git worktree for task
-forge merge <task-id>             # Merge worktree back to main
-```
-
-## Examples
-
-### Start a New Project
-```bash
-forge new-project my-app
-forge discuss M2-planning-engine
-forge plan M2-planning-engine
-```
-
-### Check Progress
-```bash
-forge status
-forge status -v  # verbose with all tasks
-```
-
-### Generate Artifacts
-```bash
-forge generate requirements
-forge generate roadmap
-```
-
-## Quick Reference
-
-| Command | Purpose | Milestone |
-|---------|---------|-----------|
-| init | Initialize project | M1 ✅ |
-| status | Show progress | M1 ✅ |
-| config | Configure settings | M1 ✅ |
-| discuss | Capture context | M2 🚧 |
-| plan | Generate tasks | M2 🚧 |
-| deploy | Execute phase | M3 📋 |
-| tribunal | Review phase | M4 📋 |
-
-Legend: ✅ Complete | 🚧 In Progress | 📋 Planned
-
-## Documentation
-
-- CLAUDE.md - Architecture and patterns
-- REQUIREMENTS.md - Functional requirements
-- ROADMAP.md - Implementation roadmap
-- PLAN.md - Detailed task plans
-</process>
-
-<output_format>
-**Summary:** All commands in table format
-**Detailed:** Full documentation for specific command
-**With Examples:** Usage examples for common workflows
-</output_format>
+For specific command help, read the command's md file in `.claude/commands/forge/`.