mindforge-cc 2.1.0 → 2.1.2

package/.agent/hooks/mindforge-statusline.js

@@ -0,0 +1,119 @@
+#!/usr/bin/env node
+// mindforge-hook-version: 1.28.0
+// Claude Code Statusline - MindForge Edition
+// Shows: model | current task | directory | context usage
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+// Read JSON from stdin
+let input = '';
+// Timeout guard: if stdin doesn't close within 3s (e.g. pipe issues on
+// Windows/Git Bash), exit silently instead of hanging. See #775.
+const stdinTimeout = setTimeout(() => process.exit(0), 3000);
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', chunk => input += chunk);
+process.stdin.on('end', () => {
+  clearTimeout(stdinTimeout);
+  try {
+    const data = JSON.parse(input);
+    const model = data.model?.display_name || 'Claude';
+    const dir = data.workspace?.current_dir || process.cwd();
+    const session = data.session_id || '';
+    const remaining = data.context_window?.remaining_percentage;
+
+    // Context window display (shows USED percentage scaled to usable context)
+    // Claude Code reserves ~16.5% for autocompact buffer, so usable context
+    // is 83.5% of the total window. We normalize to show 100% at that point.
+    const AUTO_COMPACT_BUFFER_PCT = 16.5;
+    let ctx = '';
+    if (remaining != null) {
+      // Normalize: subtract buffer from remaining, scale to usable range
+      const usableRemaining = Math.max(0, ((remaining - AUTO_COMPACT_BUFFER_PCT) / (100 - AUTO_COMPACT_BUFFER_PCT)) * 100);
+      const used = Math.max(0, Math.min(100, Math.round(100 - usableRemaining)));
+
+      // Write context metrics to bridge file for the context-monitor PostToolUse hook.
+      // The monitor reads this file to inject agent-facing warnings when context is low.
+      if (session) {
+        try {
+          const bridgePath = path.join(os.tmpdir(), `claude-ctx-${session}.json`);
+          const bridgeData = JSON.stringify({
+            session_id: session,
+            remaining_percentage: remaining,
+            used_pct: used,
+            timestamp: Math.floor(Date.now() / 1000)
+          });
+          fs.writeFileSync(bridgePath, bridgeData);
+        } catch (e) {
+          // Silent fail -- bridge is best-effort, don't break statusline
+        }
+      }
+
+      // Build progress bar (10 segments)
+      const filled = Math.floor(used / 10);
+      const bar = '█'.repeat(filled) + '░'.repeat(10 - filled);
+
+      // Color based on usable context thresholds
+      if (used < 50) {
+        ctx = ` \x1b[32m${bar} ${used}%\x1b[0m`;
+      } else if (used < 65) {
+        ctx = ` \x1b[33m${bar} ${used}%\x1b[0m`;
+      } else if (used < 80) {
+        ctx = ` \x1b[38;5;208m${bar} ${used}%\x1b[0m`;
+      } else {
+        ctx = ` \x1b[5;31m💀 ${bar} ${used}%\x1b[0m`;
+      }
+    }
+
+    // Current task from todos
+    let task = '';
+    const homeDir = os.homedir();
+    // Respect CLAUDE_CONFIG_DIR for custom config directory setups (#870)
+    const claudeDir = process.env.CLAUDE_CONFIG_DIR || path.join(homeDir, '.agent');
+    const todosDir = path.join(claudeDir, 'todos');
+    if (session && fs.existsSync(todosDir)) {
+      try {
+        const files = fs.readdirSync(todosDir)
+          .filter(f => f.startsWith(session) && f.includes('-agent-') && f.endsWith('.json'))
+          .map(f => ({ name: f, mtime: fs.statSync(path.join(todosDir, f)).mtime }))
+          .sort((a, b) => b.mtime - a.mtime);
+
+        if (files.length > 0) {
+          try {
+            const todos = JSON.parse(fs.readFileSync(path.join(todosDir, files[0].name), 'utf8'));
+            const inProgress = todos.find(t => t.status === 'in_progress');
+            if (inProgress) task = inProgress.activeForm || '';
+          } catch (e) {}
+        }
+      } catch (e) {
+        // Silently fail on file system errors - don't break statusline
+      }
+    }
+
+    // MindForge update available?
+    let mindforgeUpdate = '';
+    const cacheFile = path.join(claudeDir, 'cache', 'mindforge-update-check.json');
+    if (fs.existsSync(cacheFile)) {
+      try {
+        const cache = JSON.parse(fs.readFileSync(cacheFile, 'utf8'));
+        if (cache.update_available) {
+          mindforgeUpdate = '\x1b[33m⬆ /mindforge:update\x1b[0m │ ';
+        }
+        if (cache.stale_hooks && cache.stale_hooks.length > 0) {
+          mindforgeUpdate += '\x1b[31m⚠ stale hooks — run /mindforge:update\x1b[0m │ ';
+        }
+      } catch (e) {}
+    }
+
+    // Output
+    const dirname = path.basename(dir);
+    if (task) {
+      process.stdout.write(`${mindforgeUpdate}\x1b[2m${model}\x1b[0m │ \x1b[1m${task}\x1b[0m │ \x1b[2m${dirname}\x1b[0m${ctx}`);
+    } else {
+      process.stdout.write(`${mindforgeUpdate}\x1b[2m${model}\x1b[0m │ \x1b[2m${dirname}\x1b[0m${ctx}`);
+    }
+  } catch (e) {
+    // Silent fail - don't break statusline on parse errors
+  }
+});

package/.agent/hooks/mindforge-workflow-guard.js

@@ -0,0 +1,94 @@
+#!/usr/bin/env node
+// mindforge-hook-version: 1.28.0
+// MindForge Workflow Guard — PreToolUse hook
+// Detects when Claude attempts file edits outside a MindForge workflow context
+// (no active /mindforge: command or Task subagent) and injects an advisory warning.
+//
+// This is a SOFT guard — it advises, not blocks. The edit still proceeds.
+// The warning nudges Claude to use /mindforge:quick or /mindforge:fast instead of
+// making direct edits that bypass state tracking.
+//
+// Enable via config: hooks.workflow_guard: true (default: false)
+// Only triggers on Write/Edit tool calls to non-.planning/ files.
+
+const fs = require('fs');
+const path = require('path');
+
+let input = '';
+const stdinTimeout = setTimeout(() => process.exit(0), 3000);
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', chunk => input += chunk);
+process.stdin.on('end', () => {
+  clearTimeout(stdinTimeout);
+  try {
+    const data = JSON.parse(input);
+    const toolName = data.tool_name;
+
+    // Only guard Write and Edit tool calls
+    if (toolName !== 'Write' && toolName !== 'Edit') {
+      process.exit(0);
+    }
+
+    // Check if we're inside a MindForge workflow (Task subagent or /mindforge: command)
+    // Subagents have a session_id that differs from the parent
+    // and typically have a description field set by the orchestrator
+    if (data.tool_input?.is_subagent || data.session_type === 'task') {
+      process.exit(0);
+    }
+
+    // Check the file being edited
+    const filePath = data.tool_input?.file_path || data.tool_input?.path || '';
+
+    // Allow edits to .planning/ files (MindForge state management)
+    if (filePath.includes('.planning/') || filePath.includes('.planning\\')) {
+      process.exit(0);
+    }
+
+    // Allow edits to common config/docs files that don't need MindForge tracking
+    const allowedPatterns = [
+      /\.gitignore$/,
+      /\.env/,
+      /CLAUDE\.md$/,
+      /AGENTS\.md$/,
+      /GEMINI\.md$/,
+      /settings\.json$/,
+    ];
+    if (allowedPatterns.some(p => p.test(filePath))) {
+      process.exit(0);
+    }
+
+    // Check if workflow guard is enabled
+    const cwd = data.cwd || process.cwd();
+    const configPath = path.join(cwd, '.planning', 'config.json');
+    if (fs.existsSync(configPath)) {
+      try {
+        const config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+        if (!config.hooks?.workflow_guard) {
+          process.exit(0); // Guard disabled (default)
+        }
+      } catch (e) {
+        process.exit(0);
+      }
+    } else {
+      process.exit(0); // No MindForge project — don't guard
+    }
+
+    // If we get here: MindForge project, guard enabled, file edit outside .planning/,
+    // not in a subagent context. Inject advisory warning.
+    const output = {
+      hookSpecificOutput: {
+        hookEventName: "PreToolUse",
+        additionalContext: `⚠️ WORKFLOW ADVISORY: You're editing ${path.basename(filePath)} directly without a MindForge command. ` +
+          'This edit will not be tracked in STATE.md or produce a SUMMARY.md. ' +
+          'Consider using /mindforge:fast for trivial fixes or /mindforge:quick for larger changes ' +
+          'to maintain project state tracking. ' +
+          'If this is intentional (e.g., user explicitly asked for a direct edit), proceed normally.'
+      }
+    };
+
+    process.stdout.write(JSON.stringify(output));
+  } catch (e) {
+    // Silent fail — never block tool execution
+    process.exit(0);
+  }
+});

package/.agent/mindforge/discuss-phase.md

@@ -58,7 +58,7 @@ Do not batch questions (unless `--batch` flag is provided).
 5. "Data retention requirements? When can records be deleted?"
 
 ### Integration phases — ask about:
-1. "Have you already chosen the third-party service / API? If so, which?"
+1. "Have you already chosen the third-party service / API? If so, which? (I will query Context7 for current docs if available)"
 2. "What should happen if the third-party service is down? Queue / fail / fallback?"
 3. "Webhooks or polling for receiving updates?"
 4. "Any rate limits you know about on their end?"

package/.agent/mindforge/help.md

@@ -20,4 +20,4 @@ If `.planning/PROJECT.md` is missing, treat the project as "Not initialised".
    "Next step:       [read STATE.md next action]"
 
 5. If CLAUDE.md has not been read this session, remind the user to ensure
-   it is loaded as the agent's system context.
+   it is loaded as MindForge's system context.

package/.agent/mindforge/learn.md

@@ -37,10 +37,11 @@ load automatically whenever relevant work begins.
 ### Learn from npm package docs
 ```
 /mindforge:learn npm:zod
+/mindforge:learn context7:zod
 /mindforge:learn npm:drizzle-orm
-/mindforge:learn npm:@tanstack/react-query
+/mindforge:learn context7:drizzle-orm
 ```
-→ Fetches README from npm registry
+→ Fetches README from npm registry or real-time docs from Context7
 → Extracts patterns from the package documentation
 
 ### Learn from current session

package/.agent/mindforge/research.md

@@ -3,9 +3,10 @@
 
 ## Purpose
 Deep research using Gemini 1.5 Pro's 1-million-token context window.
-Incorporate local code context and remote documentation simultaneously.
+Uses **Context7 MCP** as the primary engine for real-time documentation and code example retrieval.
 
 ## Capabilities
-- Ingest full library documentation.
+- Ingest full library documentation via Context7.
 - Codebase-wide architectural analysis.
 - Regulatory compliance audits.
+- Real-time resolution of version-specific API contracts.

package/.agent/mindforge/steer.md

@@ -1,7 +1,7 @@
 # /mindforge:steer "[instruction]"
 
 **Purpose**: Injects mid-execution guidance into the running autonomous engine.
-Steering guidance is applied at the next task boundary to course-correct the agent.
+Steering guidance is applied at the next task boundary to course-correct MindForge.
 
 ## Usage
 - `/mindforge:steer "Use the new logger in all created files"`

package/.agent/settings.json

@@ -0,0 +1,38 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node .agent/hooks/mindforge-check-update.js"
+          }
+        ]
+      }
+    ],
+    "AfterTool": [
+      {
+        "matcher": "Bash|Edit|Write|MultiEdit|Agent|Task",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node .agent/hooks/mindforge-context-monitor.js",
+            "timeout": 10
+          }
+        ]
+      }
+    ],
+    "BeforeTool": [
+      {
+        "matcher": "Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node .agent/hooks/mindforge-prompt-guard.js",
+            "timeout": 5
+          }
+        ]
+      }
+    ]
+  }
+}

package/.agent/skills/mindforge-add-backlog/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: mindforge-add-backlog
+description: Add an idea to the backlog parking lot (999.x numbering)
+---
+
+
+<objective>
+Add a backlog item to the roadmap using 999.x numbering. Backlog items are
+unsequenced ideas that aren't ready for active planning — they live outside
+the normal phase sequence and accumulate context over time.
+</objective>
+
+<process>
+
+1. **Read ROADMAP.md** to find existing backlog entries:
+   ```bash
+   cat .planning/ROADMAP.md
+   ```
+
+2. **Find next backlog number:**
+   ```bash
+   NEXT=$(node ".agent/bin/mindforge-tools.cjs" phase next-decimal 999 --raw)
+   ```
+   If no 999.x phases exist, start at 999.1.
+
+3. **Create the phase directory:**
+   ```bash
+   SLUG=$(node ".agent/bin/mindforge-tools.cjs" generate-slug "$ARGUMENTS")
+   mkdir -p ".planning/phases/${NEXT}-${SLUG}"
+   touch ".planning/phases/${NEXT}-${SLUG}/.gitkeep"
+   ```
+
+4. **Add to ROADMAP.md** under a `## Backlog` section. If the section doesn't exist, create it at the end:
+
+   ```markdown
+   ## Backlog
+
+   ### Phase {NEXT}: {description} (BACKLOG)
+
+   **Goal:** [Captured for future planning]
+   **Requirements:** TBD
+   **Plans:** 0 plans
+
+   Plans:
+   - [ ] TBD (promote with /mindforge-review-backlog when ready)
+   ```
+
+5. **Commit:**
+   ```bash
+   node ".agent/bin/mindforge-tools.cjs" commit "docs: add backlog item ${NEXT} — ${ARGUMENTS}" --files .planning/ROADMAP.md ".planning/phases/${NEXT}-${SLUG}/.gitkeep"
+   ```
+
+6. **Report:**
+   ```
+   ## 📋 Backlog Item Added
+
+   Phase {NEXT}: {description}
+   Directory: .planning/phases/{NEXT}-{slug}/
+
+   This item lives in the backlog parking lot.
+   Use /mindforge-discuss-phase {NEXT} to explore it further.
+   Use /mindforge-review-backlog to promote items to active milestone.
+   ```
+
+</process>
+
+<notes>
+- 999.x numbering keeps backlog items out of the active phase sequence
+- Phase directories are created immediately, so /mindforge-discuss-phase and /mindforge-plan-phase work on them
+- No `Depends on:` field — backlog items are unsequenced by definition
+- Sparse numbering is fine (999.1, 999.3) — always uses next-decimal
+</notes>

package/.agent/skills/mindforge-add-phase/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: mindforge-add-phase
+description: Add phase to end of current milestone in roadmap
+---
+
+
+<objective>
+Add a new integer phase to the end of the current milestone in the roadmap.
+
+Routes to the add-phase workflow which handles:
+- Phase number calculation (next sequential integer)
+- Directory creation with slug generation
+- Roadmap structure updates
+- STATE.md roadmap evolution tracking
+</objective>
+
+<execution_context>
+@.agent/workflows/mindforge-add-phase.md
+</execution_context>
+
+<context>
+Arguments: $ARGUMENTS (phase description)
+
+Roadmap and state are resolved in-workflow via `init phase-op` and targeted tool calls.
+</context>
+
+<process>
+**Follow the add-phase workflow** from `@.agent/workflows/mindforge-add-phase.md`.
+
+The workflow handles all logic including:
+1. Argument parsing and validation
+2. Roadmap existence checking
+3. Current milestone identification
+4. Next phase number calculation (ignoring decimals)
+5. Slug generation from description
+6. Phase directory creation
+7. Roadmap entry insertion
+8. STATE.md updates
+</process>

package/.agent/skills/mindforge-add-tests/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: mindforge-add-tests
+description: Generate tests for a completed phase based on UAT criteria and implementation
+---
+
+<objective>
+Generate unit and E2E tests for a completed phase, using its SUMMARY.md, CONTEXT.md, and VERIFICATION.md as specifications.
+
+Analyzes implementation files, classifies them into TDD (unit), E2E (browser), or Skip categories, presents a test plan for user approval, then generates tests following RED-GREEN conventions.
+
+Output: Test files committed with message `test(phase-{N}): add unit and E2E tests from add-tests command`
+</objective>
+
+<execution_context>
+@.agent/workflows/mindforge-add-tests.md
+</execution_context>
+
+<context>
+Phase: $ARGUMENTS
+
+@.planning/STATE.md
+@.planning/ROADMAP.md
+</context>
+
+<process>
+Execute the add-tests workflow from @.agent/workflows/mindforge-add-tests.md end-to-end.
+Preserve all workflow gates (classification approval, test plan approval, RED-GREEN verification, gap reporting).
+</process>

package/.agent/skills/mindforge-add-todo/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: mindforge-add-todo
+description: Capture idea or task as todo from current conversation context
+---
+
+
+<objective>
+Capture an idea, task, or issue that surfaces during a MindForge session as a structured todo for later work.
+
+Routes to the add-todo workflow which handles:
+- Directory structure creation
+- Content extraction from arguments or conversation
+- Area inference from file paths
+- Duplicate detection and resolution
+- Todo file creation with frontmatter
+- STATE.md updates
+- Git commits
+</objective>
+
+<execution_context>
+@.agent/workflows/mindforge-add-todo.md
+</execution_context>
+
+<context>
+Arguments: $ARGUMENTS (optional todo description)
+
+State is resolved in-workflow via `init todos` and targeted reads.
+</context>
+
+<process>
+**Follow the add-todo workflow** from `@.agent/workflows/mindforge-add-todo.md`.
+
+The workflow handles all logic including:
+1. Directory ensuring
+2. Existing area checking
+3. Content extraction (arguments or conversation)
+4. Area inference
+5. Duplicate checking
+6. File creation with slug generation
+7. STATE.md updates
+8. Git commits
+</process>

package/.agent/skills/mindforge-audit-milestone/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: mindforge-audit-milestone
+description: Audit milestone completion against original intent before archiving
+---
+
+<objective>
+Verify milestone achieved its definition of done. Check requirements coverage, cross-phase integration, and end-to-end flows.
+
+**This command IS the orchestrator.** Reads existing VERIFICATION.md files (phases already verified during execute-phase), aggregates tech debt and deferred gaps, then spawns integration checker for cross-phase wiring.
+</objective>
+
+<execution_context>
+@.agent/workflows/mindforge-audit-milestone.md
+</execution_context>
+
+<context>
+Version: $ARGUMENTS (optional — defaults to current milestone)
+
+Core planning files are resolved in-workflow (`init milestone-op`) and loaded only as needed.
+
+**Completed Work:**
+Glob: .planning/phases/*/*-SUMMARY.md
+Glob: .planning/phases/*/*-VERIFICATION.md
+</context>
+
+<process>
+Execute the audit-milestone workflow from @.agent/workflows/mindforge-audit-milestone.md end-to-end.
+Preserve all workflow gates (scope determination, verification reading, integration check, requirements coverage, routing).
+</process>

package/.agent/skills/mindforge-audit-uat/SKILL.md

@@ -0,0 +1,20 @@
+---
+name: mindforge-audit-uat
+description: Cross-phase audit of all outstanding UAT and verification items
+---
+
+<objective>
+Scan all phases for pending, skipped, blocked, and human_needed UAT items. Cross-reference against codebase to detect stale documentation. Produce prioritized human test plan.
+</objective>
+
+<execution_context>
+@.agent/workflows/mindforge-audit-uat.md
+</execution_context>
+
+<context>
+Core planning files are loaded in-workflow via CLI.
+
+**Scope:**
+Glob: .planning/phases/*/*-UAT.md
+Glob: .planning/phases/*/*-VERIFICATION.md
+</context>

package/.agent/skills/mindforge-autonomous/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: mindforge-autonomous
+description: Run all remaining phases autonomously — discuss→plan→execute per phase
+---
+
+<objective>
+Execute all remaining milestone phases autonomously. For each phase: discuss → plan → execute. Pauses only for user decisions (grey area acceptance, blockers, validation requests).
+
+Uses ROADMAP.md phase discovery and Skill() flat invocations for each phase command. After all phases complete: milestone audit → complete → cleanup.
+
+**Creates/Updates:**
+- `.planning/STATE.md` — updated after each phase
+- `.planning/ROADMAP.md` — progress updated after each phase
+- Phase artifacts — CONTEXT.md, PLANs, SUMMARYs per phase
+
+**After:** Milestone is complete and cleaned up.
+</objective>
+
+<execution_context>
+@.agent/workflows/mindforge-autonomous.md
+@.agent/references/ui-brand.md
+</execution_context>
+
+<context>
+Optional flag: `--from N` — start from phase N instead of the first incomplete phase.
+
+Project context, phase list, and state are resolved inside the workflow using init commands (`mindforge-tools.cjs init milestone-op`, `mindforge-tools.cjs roadmap analyze`). No upfront context loading needed.
+</context>
+
+<process>
+Execute the autonomous workflow from @.agent/workflows/mindforge-autonomous.md end-to-end.
+Preserve all workflow gates (phase discovery, per-phase execution, blocker handling, progress display).
+</process>

package/.agent/skills/mindforge-check-todos/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: mindforge-check-todos
+description: List pending todos and select one to work on
+---
+
+
+<objective>
+List all pending todos, allow selection, load full context for the selected todo, and route to appropriate action.
+
+Routes to the check-todos workflow which handles:
+- Todo counting and listing with area filtering
+- Interactive selection with full context loading
+- Roadmap correlation checking
+- Action routing (work now, add to phase, brainstorm, create phase)
+- STATE.md updates and git commits
+</objective>
+
+<execution_context>
+@.agent/workflows/mindforge-check-todos.md
+</execution_context>
+
+<context>
+Arguments: $ARGUMENTS (optional area filter)
+
+Todo state and roadmap correlation are loaded in-workflow using `init todos` and targeted reads.
+</context>
+
+<process>
+**Follow the check-todos workflow** from `@.agent/workflows/mindforge-check-todos.md`.
+
+The workflow handles all logic including:
+1. Todo existence checking
+2. Area filtering
+3. Interactive listing and selection
+4. Full context loading with file summaries
+5. Roadmap correlation checking
+6. Action offering and execution
+7. STATE.md updates
+8. Git commits
+</process>

package/.agent/skills/mindforge-cleanup/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: mindforge-cleanup
+description: Archive accumulated phase directories from completed milestones
+---
+
+<objective>
+Archive phase directories from completed milestones into `.planning/milestones/v{X.Y}-phases/`.
+
+Use when `.planning/phases/` has accumulated directories from past milestones.
+</objective>
+
+<execution_context>
+@.agent/workflows/mindforge-cleanup.md
+</execution_context>
+
+<process>
+Follow the cleanup workflow at @.agent/workflows/mindforge-cleanup.md.
+Identify completed milestones, show a dry-run summary, and archive on confirmation.
+</process>