forge-dev-framework 1.1.0 → 1.2.0

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/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

@@ -1,174 +1,95 @@
 ---
 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.
+description: Verify all phase plans against requirements and generate gap closure plans.
 argument-hint: <phase-name>
 allowed-tools:
   - Read
+  - Write
   - Glob
   - Grep
   - Bash
+  - Task
 ---
 
-<objective>
-Verify that a phase plan achieves its goals and covers all requirements through goal-backward analysis.
+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`.
 
-Purpose: Validate plan completeness before execution.
-Output: VERIFICATION.md with coverage analysis and gaps identified.
-</objective>
+**Read:** All `.planning/phases/{phase}/*-PLAN.md` files, all `*-SUMMARY.md` files (if execution happened), REQUIREMENTS.md, ROADMAP.md, state/STATE.json
 
-<execution_context>
-**Load these files NOW:**
+**Steps:**
 
-- @.planning/phases/<phase>/PLAN.md (Task breakdown)
-- @REQUIREMENTS.md (Project requirements)
-- @ROADMAP.md (Milestone context)
-- @CLAUDE.md (Success criteria patterns)
-</execution_context>
+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
 
-<context>
-**Phase:** $ARGUMENTS
-**Verification Type:** Goal-backward analysis
-**Focus:** Requirements coverage, integration completeness, end-to-end flows
-</context>
+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
 
-<process>
-**Execute verification workflow:**
+3. **Goal-backward analysis** — For each milestone goal from ROADMAP.md:
+   - Trace: goal → plans → tasks → acceptance criteria
+   - Flag missing links in the chain
 
-1. **Load Plan & Requirements**
-   - Read PLAN.md task list
-   - Read REQUIREMENTS.md entries
-   - Load milestone goals from ROADMAP.md
+4. **Integration completeness** — Check cross-plan contracts defined, integration points covered, no conflicting file modifications across plans in the same wave.
 
-2. **Requirements Coverage Analysis**
+5. **Dependency validation** — Verify plan dependency graph is acyclic, all depends_on references are valid plan numbers, wave assignments are correct.
 
-   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
-   ```
+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
 
-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
-   ```
+7. **Write VERIFICATION.md** — `.planning/phases/{phase}/VERIFICATION.md` with:
+   ```markdown
+   # {Phase} Verification
+   **Verified:** [timestamp]
+   **Result:** {PASS | GAPS FOUND}
 
-6. **Task Atomicity Check**
+   ## Requirements Coverage
+   | Requirement | Status | Covered By |
+   |-------------|--------|------------|
+   | REQ-001     | Covered | Plan 01, Task 1 |
+   | REQ-003     | GAP    | — |
 
-   Verify each task is atomic:
-   ```
-   ✅ auth-001: Single owner, single concept
-   ❌ ui-002: Too broad (split into ui-002a, ui-002b)
-   ```
+   ## Goal-Backward Analysis
+   [Results per goal]
 
-7. **Generate VERIFICATION.md**
-   ```markdown
-   # <Phase> Verification
+   ## Integration Check
+   [Results]
 
-   ## 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
-   ...
-   ```
+   ## Dependency Validation
+   [Results]
 
-8. **Route Decision**
+   ## Scope Validation
+   [Results]
 
-   If gaps found:
-   ```
-   - Ask user: "Add tasks for gaps?"
-   - If yes: Update PLAN.md
-   - If no: Document and proceed
+   ## Gaps Summary
+   {count} gaps identified requiring remediation.
    ```
 
-   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>
+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`);
+}

package/.claude/hooks/forge-event-guard.cjs

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+// FORGE Hook: Event Immutability Guard
+// PreToolUse on Edit — prevents modifying existing event files in state/events/
+// Events are append-only per FORGE architecture
+
+const path = require('path');
+
+let input = '';
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', chunk => input += chunk);
+process.stdin.on('end', () => {
+  try {
+    const data = JSON.parse(input);
+    const toolName = data.tool_name || '';
+    const filePath = data.tool_input?.file_path || '';
+
+    // Only guard Edit operations on event files
+    if (toolName === 'Edit' && filePath) {
+      const resolved = path.resolve(filePath);
+      const eventsDir = path.resolve(process.cwd(), 'state', 'events');
+
+      if (resolved.startsWith(eventsDir) && resolved.endsWith('.json')) {
+        process.stdout.write(JSON.stringify({
+          decision: 'block',
+          reason: 'FORGE: Events are append-only. Cannot edit files in state/events/. Write new events instead.'
+        }));
+        return;
+      }
+    }
+
+    process.stdout.write(JSON.stringify({ decision: 'approve' }));
+  } catch (e) {
+    // Don't block on parse errors
+    process.stdout.write(JSON.stringify({ decision: 'approve' }));
+  }
+});

package/.claude/hooks/forge-size-guard.cjs

@@ -0,0 +1,55 @@
+#!/usr/bin/env node
+// FORGE Hook: File Size Guard
+// PostToolUse on Write/Edit — warns when artifacts exceed token limits
+// Limits: CLAUDE.md ~2000t, rules ~1000t, REQUIREMENTS.md ~4000t, PLAN.md ~6000t
+
+const fs = require('fs');
+const path = require('path');
+
+// Approximate tokens as chars/4
+const LIMITS = {
+  'CLAUDE.md': { tokens: 2000, chars: 8000 },
+  'REQUIREMENTS.md': { tokens: 4000, chars: 16000 },
+  'PLAN.md': { tokens: 6000, chars: 24000 },
+};
+const RULES_LIMIT = { tokens: 1000, chars: 4000 };
+
+let input = '';
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', chunk => input += chunk);
+process.stdin.on('end', () => {
+  try {
+    const data = JSON.parse(input);
+    const filePath = data.tool_input?.file_path || data.tool_result?.file_path || '';
+
+    if (!filePath) {
+      process.stdout.write(JSON.stringify({ decision: 'approve' }));
+      return;
+    }
+
+    const basename = path.basename(filePath);
+    const resolved = path.resolve(filePath);
+
+    // Check specific file limits
+    let limit = LIMITS[basename];
+
+    // Check rules directory
+    if (!limit && resolved.includes('.claude/rules/') && resolved.endsWith('.md')) {
+      limit = RULES_LIMIT;
+    }
+
+    if (limit && fs.existsSync(resolved)) {
+      const size = fs.statSync(resolved).size;
+      if (size > limit.chars) {
+        const approxTokens = Math.round(size / 4);
+        process.stderr.write(
+          `\x1b[33m⚠ FORGE: ${basename} is ~${approxTokens} tokens (limit: ~${limit.tokens}). Consider trimming.\x1b[0m\n`
+        );
+      }
+    }
+
+    process.stdout.write(JSON.stringify({ decision: 'approve' }));
+  } catch (e) {
+    process.stdout.write(JSON.stringify({ decision: 'approve' }));
+  }
+});

package/.claude/rules/api-patterns.md

@@ -1,98 +1,13 @@
-# FORGE API Design Patterns
-
-> **Scope:** Internal FORGE APIs and interfaces between components.
-
-## File Naming
-
-- Use `kebab-case.ts` for files
-- Use `PascalCase` for types, interfaces, classes
-- Use `camelCase` for functions, variables
-
-## Module Structure
-
-Each module exports:
-1. Types/interfaces first
-2. Functions/operations
-3. Constants at the end
-
-```typescript
-// src/state/event-types.ts
-export interface StateEvent { ... }
-export interface TaskStartedEvent extends StateEvent { ... }
-
-export function createEvent(type: EventType, payload: unknown): StateEvent { ... }
-
-export const EVENT_TYPES = ['TASK_STARTED', 'TASK_COMPLETED', ...] as const;
-```
-
-## Error Handling
-
-- Define custom error types extending `Error`
-- Include error codes for programmatic handling
-- Provide context in error messages
-
-```typescript
-export class StateValidationError extends Error {
-  constructor(
-    public schema: string,
-    public errors: z.ZodError,
-  ) {
-    super(`State validation failed for ${schema}: ${errors.message}`);
-    this.name = 'StateValidationError';
-  }
-}
-```
-
-## Async Operations
-
-- Use `async/await`, not Promises directly
-- Return typed promises: `Promise<T>`
-- Handle rejections with try/catch
-
-```typescript
-export async function loadState(path: string): Promise<State> {
-  try {
-    const content = await fs.readFile(path, 'utf-8');
-    return JSON.parse(content);
-  } catch (error) {
-    throw new StateLoadError(path, error);
-  }
-}
-```
-
-## Input Validation
-
-- Use Zod schemas for all public APIs
-- Validate at module boundaries
-- Return typed results, never `any`
-
-```typescript
-import { z } from 'zod';
-
-const EventSchema = z.object({
-  eventId: z.string(),
-  timestamp: z.string().datetime(),
-  taskId: z.string(),
-  actor: z.string(),
-  type: z.enum(EVENT_TYPES),
-  payload: z.unknown(),
-});
-
-export function parseEvent(data: unknown): StateEvent {
-  return EventSchema.parse(data);
-}
-```
-
-## File I/O
-
-- Use absolute paths from project root
-- Check file existence before reading
-- Use atomic writes (write to temp, then rename)
-
-```typescript
-export async function writeState(path: string, state: State): Promise<void> {
-  const tmpPath = `${path}.tmp`;
-  await fs.writeFile(tmpPath, JSON.stringify(state, null, 2));
-  await fs.rename(tmpPath, path);
-}
-```
+---
+globs:
+  - "src/**/*.ts"
+---
+
+# API Design Patterns
+
+- **Files:** `kebab-case.ts` | **Types:** `PascalCase` | **Functions:** `camelCase`
+- **Module exports order:** types/interfaces → functions → constants
+- **Errors:** Custom error classes extending `Error` with error codes and context
+- **Async:** Use `async/await` with typed `Promise<T>` returns, try/catch for rejections
+- **Validation:** Zod schemas at all public API boundaries — never return `any`
+- **File I/O:** Absolute paths from project root, check existence, atomic writes (write to temp → rename)

package/.claude/rules/context-efficiency.md

@@ -0,0 +1,10 @@
+# Context Efficiency
+
+- **Read selectively:** Use `offset`/`limit` for large files — don't read entire files when only a section matters
+- **Minimize re-reads:** Cache key info in your working memory instead of re-reading the same file multiple times
+- **Short outputs:** Prefer concise tool output — pipe through `head`/`tail` when full output isn't needed
+- **Atomic tasks:** One task = one focused context. Don't accumulate unrelated work in a single session
+- **Summarize early:** After reading large files, extract what you need and move on — don't keep raw content in context
+- **Event hygiene:** Old events auto-archive after 7 days (SessionStart hook). Don't read archived events unless replaying state
+- **File size limits:** CLAUDE.md ~2000t, rules ~1000t each, REQUIREMENTS.md ~4000t, PLAN.md ~6000t (enforced by PostToolUse hook)
+- **Team messages:** Keep inter-agent messages concise — include only actionable information