forge-dev-framework 1.0.1 → 1.1.0

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

@@ -0,0 +1,130 @@
+---
+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
+  - AskUserQuestion
+---
+
+<objective>
+Execute small, ad-hoc tasks with FORGE guarantees (atomic commits, STATE.json tracking) while skipping optional workflows.
+
+Quick mode is the same system with a shorter path:
+- Spawns planner + executor(s)
+- Skips research, plan-checker, verifier
+- Quick tasks live in `.planning/quick/` separate from planned phases
+- Updates STATE.json "Quick Tasks Completed" table (NOT ROADMAP.md)
+
+Use when: You know exactly what to do and the task is small enough to not need research or verification.
+</objective>
+
+<execution_context>
+@state/STATE.json
+@CLAUDE.md
+</execution_context>
+
+<context>
+**Task Description:** $ARGUMENTS
+
+**Quick Task Workflow:**
+1. Validate task is appropriate for quick mode
+2. Create minimal task plan (1-3 atomic steps)
+3. Execute task with atomic commits
+4. Update STATE.json quick tasks table
+5. Verify with basic validation
+</context>
+
+<process>
+**Execute quick task workflow:**
+
+1. **Validate Quick Mode Appropriateness**
+   Ask: "Is this task appropriate for quick mode?"
+   - Quick mode tasks should:
+     - Be well-understood (no research needed)
+     - Be small (1-3 atomic steps)
+     - Not require verification workflows
+
+   If task doesn't fit:
+   - Suggest: Use `forge plan <phase>` for proper planning
+   - Or: Continue with quick mode anyway
+
+2. **Create Quick Task Entry**
+   - Generate task ID: `quick-{timestamp}`
+   - Create quick task directory:
+     ```bash
+     mkdir -p .planning/quick/{taskId}/
+     ```
+
+3. **Generate Minimal Task Plan**
+   - Break task into 1-3 atomic steps
+   - Define acceptance criteria
+   - Identify files to change
+   - Create simple plan in `.planning/quick/{taskId}/PLAN.md`
+
+4. **Execute Task**
+   For each step:
+   - Read necessary files
+   - Make changes (Edit or Write)
+   - Run validation if applicable
+   - **Atomic commit after each step:**
+     ```bash
+     git add <changed-files>
+     git commit -m "feat({taskId}): {step-description}"
+     ```
+
+5. **Update STATE.json**
+   Add to "quickTasksCompleted" table:
+   ```json
+   {
+     "quickTasksCompleted": [
+       {
+         "taskId": "quick-{timestamp}",
+         "description": "{task-description}",
+         "completedAt": "{timestamp}",
+         "commitHash": "{hash}"
+       }
+     ]
+   }
+   ```
+
+6. **Submit Event**
+   - Event type: QUICK_TASK_COMPLETED
+   - Include: taskId, description, commitHash
+   - Write to state/events/
+
+7. **Verify**
+   - Basic validation (does it work?)
+   - No formal verification workflow in quick mode
+
+8. **Confirm**
+   - Show task completion summary
+   - List commits made
+   - Show updated STATE.json
+</process>
+
+<deliverables>
+- .planning/quick/{taskId}/PLAN.md (minimal plan)
+- Completed task with atomic commits
+- STATE.json updated (quickTasksCompleted table)
+- Event: QUICK_TASK_COMPLETED in state/events/
+</deliverables>
+
+<success_criteria>
+- [ ] Task completed successfully
+- [ ] Atomic commits for each step
+- [ ] STATE.json updated
+- [ ] Basic validation passed
+</success_criteria>
+
+<next_steps>
+- Continue with more quick tasks: `forge quick <description>`
+- Or plan a full phase: `forge plan <phase>`
+- Check progress: `forge status`
+</next_steps>

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

@@ -0,0 +1,91 @@
+---
+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>`
+</next_steps>

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

@@ -0,0 +1,122 @@
+---
+name: forge:resume-work
+description: Resume work from previous session with full context restoration
+argument-hint: ""
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+---
+
+<objective>
+Resume work from a previous pause by loading the `.continue-here.md` handoff file.
+
+Restores complete context including position, completed work, remaining work, decisions, and blockers.
+</objective>
+
+<execution_context>
+@.continue-here.md
+@state/STATE.json
+@CLAUDE.md
+</execution_context>
+
+<context>
+**Resume Work Workflow:**
+1. Check for `.continue-here.md` file
+2. Load and display handoff contents
+3. Restore context from handoff
+4. Identify next steps
+5. Offer to continue work
+</context>
+
+<process>
+**Execute resume-work workflow:**
+
+1. **Check for Handoff File**
+   ```bash
+   if [ -f .continue-here.md ]; then
+     echo "Found handoff file"
+   else
+     echo "No .continue-here.md found. Check STATE.json for last phase."
+     exit 1
+   fi
+   ```
+
+2. **Load Handoff**
+   - Read `.continue-here.md`
+   - Parse all sections
+   - Extract phase name and status
+
+3. **Display Context**
+   ```
+   ════════════════════════════════════════════════════════
+   RESUMING WORK
+   ════════════════════════════════════════════════════════
+
+   Phase: {phase-name}
+   Status: {status}
+   Paused: {timestamp}
+
+   ───────────────────────────────────────────────────────────
+   POSITION
+   ───────────────────────────────────────────────────────────
+   {current position}
+
+   ───────────────────────────────────────────────────────────
+   COMPLETED WORK
+   ───────────────────────────────────────────────────────────
+   ✓ {completed item 1}
+   ✓ {completed item 2}
+
+   ───────────────────────────────────────────────────────────
+   REMAINING WORK
+   ───────────────────────────────────────────────────────────
+   ○ {remaining item 1}
+   ○ {remaining item 2}
+
+   ───────────────────────────────────────────────────────────
+   DECISIONS MADE
+   ───────────────────────────────────────────────────────────
+   {decisions}
+
+   ───────────────────────────────────────────────────────────
+   BLOCKERS
+   ───────────────────────────────────────────────────────────
+   {blockers}
+
+   ════════════════════════════════════════════════════════
+   ```
+
+4. **Confirm Ready to Continue**
+   - Ask: "Ready to continue work?"
+   - If yes: Proceed
+   - If no: Exit, handoff file preserved
+
+5. **Submit Event**
+   - Event type: WORK_RESUMED
+   - Include: phaseId, handoffFile, timestamp
+   - Write to state/events/
+
+6. **Route to Next Action**
+   - Suggest: `forge execute <phase>` to continue execution
+   - Or: Manual work based on next steps
+   - Or: `forge discuss <phase>` to gather more context
+</process>
+
+<deliverables>
+- Context restored from .continue-here.md
+- Event: WORK_RESUMED in state/events/
+- STATE.json updated
+</deliverables>
+
+<next_steps>
+- Continue execution: `forge execute <phase>`
+- Update plan if needed: `forge plan <phase>`
+- Or proceed with manual work based on next steps
+</next_steps>
+
+<cleanup>
+After successfully resuming and completing work:
+- Remove .continue-here.md
+- Submit WORK_COMPLETED event
+</cleanup>

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/verify.md

@@ -0,0 +1,174 @@
+---
+name: forge:verify
+description: Verify a phase plan against requirements and success criteria. Use when user says "forge verify <phase>" or wants to validate a plan.
+argument-hint: <phase-name>
+allowed-tools:
+  - Read
+  - Glob
+  - Grep
+  - Bash
+---
+
+<objective>
+Verify that a phase plan achieves its goals and covers all requirements through goal-backward analysis.
+
+Purpose: Validate plan completeness before execution.
+Output: VERIFICATION.md with coverage analysis and gaps identified.
+</objective>
+
+<execution_context>
+**Load these files NOW:**
+
+- @.planning/phases/<phase>/PLAN.md (Task breakdown)
+- @REQUIREMENTS.md (Project requirements)
+- @ROADMAP.md (Milestone context)
+- @CLAUDE.md (Success criteria patterns)
+</execution_context>
+
+<context>
+**Phase:** $ARGUMENTS
+**Verification Type:** Goal-backward analysis
+**Focus:** Requirements coverage, integration completeness, end-to-end flows
+</context>
+
+<process>
+**Execute verification workflow:**
+
+1. **Load Plan & Requirements**
+   - Read PLAN.md task list
+   - Read REQUIREMENTS.md entries
+   - Load milestone goals from ROADMAP.md
+
+2. **Requirements Coverage Analysis**
+
+   For each requirement in REQUIREMENTS.md:
+   ```
+   REQ-1: User authentication
+   ├─ Covered by: auth-001, auth-002
+   ├─ Task acceptance criteria maps to requirement? ✅
+   └─ Verification method defined? ✅
+
+   REQ-2: API rate limiting
+   ├─ Covered by: None
+   └─ ❌ GAP: No task for rate limiting
+   ```
+
+3. **Goal-Backward Verification**
+
+   For each milestone goal:
+   ```
+   Goal: "Users can authenticate and authorize"
+   └─ Can we trace from goal → tasks → acceptance?
+       ├─ auth-001: Login endpoint ✅
+       ├─ auth-002: Session management ✅
+       ├─ auth-003: Permission checks ✅
+       └─ Integration flow tested? ❌ Missing
+   ```
+
+4. **Integration Completeness**
+
+   Check cross-phase integration:
+   ```
+   Phase A (API) → Phase B (Frontend)
+   ├─ API contract defined? ✅ contracts/auth-api.yaml
+   ├─ Frontend consumes API? ✅ ui-auth-001
+   └─ Integration test exists? ❌ Gap
+   ```
+
+5. **Dependency Validation**
+
+   Verify dependency graph:
+   ```
+   ✅ No circular dependencies
+   ✅ All dependencies have tasks
+   ✅ Critical path identified
+   ⚠  Long dependency chain: api-001 → api-002 → api-003 → api-004
+   ```
+
+6. **Task Atomicity Check**
+
+   Verify each task is atomic:
+   ```
+   ✅ auth-001: Single owner, single concept
+   ❌ ui-002: Too broad (split into ui-002a, ui-002b)
+   ```
+
+7. **Generate VERIFICATION.md**
+   ```markdown
+   # <Phase> Verification
+
+   ## Requirements Coverage
+   - REQ-1: ✅ Covered (auth-001, auth-002)
+   - REQ-2: ❌ Gap - no rate limiting task
+   ...
+
+   ## Goals Verification
+   - Goal 1: ✅ Achievable through tasks
+   - Goal 2: ⚠ Gap - integration test missing
+   ...
+
+   ## Integration Checks
+   - Phase A → Phase B: ✅ Contract defined
+   - Frontend → API: ⚠ Integration test missing
+   ...
+
+   ## Task Atomicity
+   - All tasks atomic? ✅
+   - Task count within limit? ✅ (5/6)
+
+   ## Gaps Identified
+   1. REQ-2: No rate limiting
+   2. Integration test for auth flow
+   ...
+
+   ## Recommendations
+   - Add task api-005 for rate limiting
+   - Add task int-001 for integration tests
+   ...
+   ```
+
+8. **Route Decision**
+
+   If gaps found:
+   ```
+   - Ask user: "Add tasks for gaps?"
+   - If yes: Update PLAN.md
+   - If no: Document and proceed
+   ```
+
+   If verification passes:
+   ```
+   - Mark phase ready for execution
+   - Offer `forge execute <phase>`
+   ```
+</process>
+
+<deliverables>
+- .planning/phases/<phase>/VERIFICATION.md
+- Updated PLAN.md (if gaps addressed)
+- Requirements coverage matrix
+- Gap analysis report
+</deliverables>
+
+<verification_criteria>
+Plan passes verification when:
+- ✅ All requirements covered (or gaps documented)
+- ✅ All goals achievable through tasks
+- ✅ Integration points identified and tested
+- ✅ Dependency graph valid (no cycles)
+- ✅ All tasks atomic (single concept, single owner)
+- ✅ Task count ≤ 6
+- ✅ Acceptance criteria defined
+- ✅ Verification methods specified
+</verification_criteria>
+
+<next_steps>
+If verification passes:
+- Run `forge execute <phase>` to start execution
+- Or manually assign tasks to agents
+
+If gaps found:
+- Update PLAN.md with additional tasks
+- Re-run `forge verify <phase>`
+- Or document risks and proceed
+</next_steps>

package/README.md

@@ -6,6 +6,7 @@ A multi-agent development framework for Claude Code Agent Teams that forges prod
 
 [![npm version](https://badge.fury.io/js/forge-dev-framework.svg)](https://www.npmjs.com/package/forge-dev-framework)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
 ## Features
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forge-dev-framework",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "description": "Full Orchestration for Rapid Git Engineering - A multi-agent development framework for Claude Code Agent Teams",
   "main": "dist/cli/index.js",
   "bin": {