forge-dev-framework 1.0.1 → 1.1.0

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

@@ -0,0 +1,85 @@
+---
+name: forge:init
+description: Initialize FORGE in the current project directory. Use this when the user says "forge init" or wants to set up FORGE in an existing project.
+argument-hint: [--quick]
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+---
+
+<objective>
+Initialize FORGE in the current project directory with complete project structure and configuration.
+
+Purpose: Set up FORGE's multi-agent development system in an existing or new project.
+Output: Complete FORGE directory structure, state engine, templates, and CLI configuration.
+</objective>
+
+<execution_context>
+**Load these files NOW:**
+
+- @CLAUDE.md (FORGE architecture)
+- @ROADMAP.md (Implementation plan)
+- @src/cli/init.ts (Init command implementation)
+</execution_context>
+
+<context>
+**Target Directory:** Current working directory (process.cwd())
+**Initialization Mode:** Standard or --quick (skip interactive prompts)
+
+**Actions Performed:**
+- Create state/, contracts/, .planning/, .claude/, src/ directories
+- Copy CLAUDE.md template
+- Initialize state/STATE.json
+- Create .gitignore if needed
+- Configure forge.config.json
+</context>
+
+<process>
+**Execute the init command:**
+
+1. **Directory Structure**
+   ```bash
+   mkdir -p state/events
+   mkdir -p contracts
+   mkdir -p .planning
+   mkdir -p .claude/rules
+   mkdir -p src/{cli,commands,generators,git,utils}
+   mkdir -p .github/workflows
+   mkdir -p .worktrees
+   ```
+
+2. **Core Artifacts**
+   - Copy CLAUDE.md template → project root
+   - Create state/STATE.json with initial project state
+   - Create .planning/forge.config.json with default configuration
+
+3. **Git Setup**
+   - Create/update .gitignore with FORGE patterns
+   - Initialize git repository if not exists
+   - Set up pre-commit hooks
+
+4. **Dependencies**
+   - Create package.json if not exists
+   - Install FORGE dependencies: chalk, commander, execa, zod, handlebars
+   - Add build scripts: build, test, dev
+
+5. **Verification**
+   - Run `npm run build` (if TypeScript)
+   - Check `forge status` output
+   - Verify directory structure
+
+6. **Output**
+   - Show created files
+   - Display next steps
+   - Offer `forge help` for available commands
+</process>
+
+<deliverables>
+- Complete FORGE directory structure
+- state/STATE.json (initial state)
+- .planning/forge.config.json (configuration)
+- CLAUDE.md (project constitution)
+- .gitignore with FORGE patterns
+- package.json with dependencies
+</deliverables>

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

@@ -0,0 +1,98 @@
+---
+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>` 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 inserted phase
+- Updated dependencies for subsequent phases
+- Event: PHASE_INSERTED 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
+- Notify team of dependency changes
+</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,103 @@
+---
+name: forge:new-project
+description: Initialize a new FORGE project with team coordination, state engine, and artifact generation. Use this when the user asks to "create a FORGE project", "start a new FORGE project", "initialize FORGE", or wants to use FORGE for multi-agent development.
+argument-hint: [project-name]
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - AskUserQuestion
+---
+
+<objective>
+Initialize a new FORGE project with complete project structure, state engine, team coordination system, and artifact generation capabilities.
+
+Purpose: Set up a new multi-agent development project using FORGE's architecture.
+Output: Complete FORGE project structure with CLAUDE.md, state engine, templates, and CLI commands.
+</objective>
+
+<execution_context>
+**Load these files NOW (before proceeding):**
+
+- @CLAUDE.md (FORGE's architecture and patterns)
+- @ROADMAP.md (FORGE's implementation plan)
+- @REQUIREMENTS.md (Milestone 1 acceptance criteria)
+- @bin/forge.ts (CLI entry point)
+</execution_context>
+
+<context>
+**Project Location:** Current working directory or specified project-name argument
+**Project Type:** New FORGE multi-agent development project
+
+**FORGE Capabilities:**
+- Event-sourced state engine with single-writer merge
+- Contract-first protocol for cross-agent coordination
+- Template-based artifact generation (CLAUDE.md, REQUIREMENTS.md, etc.)
+- Git worktree isolation for parallel task execution
+- 5-6 task limit enforcement per phase
+- Atomic commit enforcement with conventional format
+</context>
+
+<process>
+**Follow this workflow to initialize a new FORGE project:**
+
+1. **Project Setup**
+   - Create project directory if name provided
+   - Run `forge init` or initialize structure manually
+   - Create state/, contracts/, .planning/, .claude/rules/, src/ directories
+
+2. **Core Artifacts**
+   - Generate CLAUDE.md with project constitution
+   - Create initial REQUIREMENTS.md with project-specific requirements
+   - Set up ROADMAP.md with milestone breakdown
+   - Create PLAN.md with dependency graph
+
+3. **State Engine**
+   - Initialize state/STATE.json with project metadata
+   - Create state/STATE.schema.json for validation
+   - Set up state/events/ directory for append-only event log
+
+4. **Team Configuration**
+   - Create .claude/rules/ with project-specific rules
+   - Set up CODEOWNERS for file ownership boundaries
+   - Configure agent roles and permissions
+
+5. **Template System**
+   - Copy FORGE templates to src/templates/
+   - Configure token limits for artifacts
+   - Set up template engine integration
+
+6. **Git Integration**
+   - Initialize git repository if needed
+   - Create .worktrees/ directory structure
+   - Set up pre-commit hooks for conventional commits
+   - Create .github/workflows/ for CI/CD
+
+7. **Verification**
+   - Run `npm run build` to verify TypeScript compilation
+   - Run `npm test` to verify test suite
+   - Check `forge status` to confirm project initialization
+
+8. **Handoff**
+   - Provide user with next steps (forge discuss, forge plan)
+   - Show available commands with `forge help`
+   - Explain how to use agent teams for development
+</process>
+
+<deliverables>
+- Complete FORGE project structure
+- CLAUDE.md with project constitution
+- Initial REQUIREMENTS.md and ROADMAP.md
+- Configured state engine with STATE.json
+- Template system ready for artifact generation
+- Git repository with proper hooks
+- Build passing with zero errors
+</deliverables>
+
+<next_steps>
+After project initialization:
+1. Run `forge discuss <phase>` to capture project context
+2. Run `forge plan <phase>` to generate atomic task breakdown
+3. Use agent teams for parallel task execution
+4. Track progress with `forge status`
+</next_steps>

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-work`
+   ```
+
+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-work`
+- Handoff file will be automatically loaded
+- All context preserved
+</next_steps>

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

@@ -0,0 +1,144 @@
+---
+name: forge:plan
+description: Generate research-backed atomic task breakdown for a phase. Use when user says "forge plan <phase>" or wants to create a detailed task plan.
+argument-hint: <phase-name>
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Task
+---
+
+<objective>
+Generate atomic task breakdown (5-6 tasks max) with dependency graph for a specific phase, backed by research and verified against requirements.
+
+Purpose: Create executable plan with clear tasks, dependencies, and acceptance criteria.
+Output: PLAN.md with task breakdown, Mermaid dependency graph, and verification criteria.
+</objective>
+
+<execution_context>
+**Load these files NOW:**
+
+- @CLAUDE.md (5-6 task limit rule)
+- @REQUIREMENTS.md (Verification requirements)
+- @ROADMAP.md (Milestone context)
+- @.planning/phases/<phase>/CONTEXT.md (if exists)
+- @state/STATE.json (Current state)
+</execution_context>
+
+<context>
+**Phase:** $ARGUMENTS
+**Task Limit:** 5-6 atomic tasks maximum (FORGE hard rule)
+**Requirement:** Must verify against REQUIREMENTS.md
+
+**Planning Constraints:**
+- Tasks must be atomic (one concept, one owner)
+- Dependencies explicit and acyclic
+- Each task has clear acceptance criteria
+- Total tasks ≤ 6 (break into sub-phases if needed)
+</context>
+
+<process>
+**Execute planning workflow:**
+
+1. **Context Loading**
+   - Read CONTEXT.md if exists (from forge discuss)
+   - Load REQUIREMENTS.md for verification
+   - Check STATE.json for current milestone
+
+2. **Research Phase** (if gray areas identified)
+   ```
+   Spawn research agents for unknowns:
+   - gs-phase-researcher → domain research
+   - Returns: RESEARCH.md with findings
+   ```
+
+3. **Task Generation** (5-6 task limit enforced)
+
+   For each task, define:
+   ```
+   - ID: milestone-number-task (e.g., api-003, ui-002)
+   - Name: Clear, concise title
+   - Owner: Specialist role
+   - Type: feat, fix, test, docs, refactor
+   - Dependencies: Array of task IDs
+   - Files: Owned file paths
+   - Contracts: Required API contracts
+   - Acceptance: Given/When/Then criteria
+   - Verify: Test command or verification method
+   ```
+
+4. **Dependency Graph**
+   ```mermaid
+   graph TD
+     api-001[Create user model] --> api-002[Implement user CRUD]
+     api-002 --> api-003[Add authentication]
+     core-001[Database setup] --> api-001
+   ```
+
+5. **Requirements Verification**
+   - Map each task to REQUIREMENTS.md entries
+   - Ensure all requirements covered
+   - Identify gaps and add tasks as needed
+   - Verify no requirement orphaned
+
+6. **Write PLAN.md**
+   ```markdown
+   # <Phase Name> Plan
+
+   ## Overview
+   [Phase purpose and goals]
+
+   ## Tasks (5-6 max)
+   | ID | Name | Owner | Dependencies | Status |
+   |----|------|-------|--------------|--------|
+   | api-001 | ... | backend | - | pending |
+   ...
+
+   ## Dependency Graph
+   [Mermaid graph]
+
+   ## Requirements Coverage
+   - REQ-1: Covered by api-001, api-002
+   - REQ-2: Covered by core-001
+   ...
+
+   ## Definition of Done
+   - All tasks complete
+   - All tests passing
+   - Requirements verified
+   - Integration tested
+   ```
+
+7. **State Update**
+   - Submit PHASE_PLANNED event
+   - Update STATE.json with task list
+   - Add tasks to STATE.tasks array
+
+8. **Route to Execution**
+   - Offer `forge execute <phase>` to run tasks
+   - Or show manual task assignment
+</process>
+
+<deliverables>
+- .planning/phases/<phase>/PLAN.md (task breakdown)
+- Event: PHASE_PLANNED in state/events/
+- STATE.json updated with tasks
+- Requirements coverage matrix
+</deliverables>
+
+<verification>
+Before completing plan:
+- ✅ Total tasks ≤ 6
+- ✅ All tasks atomic (single owner)
+- ✅ Dependency graph acyclic
+- ✅ All requirements covered
+- ✅ Acceptance criteria defined
+- ✅ Verification methods specified
+</verification>
+
+<next_steps>
+- Run `forge execute <phase>` to execute plan with agent teams
+- Or manually assign tasks to specialists
+- Track progress with `forge status`
+</next_steps>