mindforge-cc 2.0.0 → 2.1.1

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>

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

@@ -0,0 +1,131 @@
+---
+name: mindforge-complete-milestone
+description: Archive completed milestone and prepare for next version
+---
+
+
+<objective>
+Mark milestone {{version}} complete, archive to milestones/, and update ROADMAP.md and REQUIREMENTS.md.
+
+Purpose: Create historical record of shipped version, archive milestone artifacts (roadmap + requirements), and prepare for next milestone.
+Output: Milestone archived (roadmap + requirements), PROJECT.md evolved, git tagged.
+</objective>
+
+<execution_context>
+**Load these files NOW (before proceeding):**
+
+- @.agent/workflows/mindforge-complete-milestone.md (main workflow)
+- @.agent/templates/milestone-archive.md (archive template)
+  </execution_context>
+
+<context>
+**Project files:**
+- `.planning/ROADMAP.md`
+- `.planning/REQUIREMENTS.md`
+- `.planning/STATE.md`
+- `.planning/PROJECT.md`
+
+**User input:**
+
+- Version: {{version}} (e.g., "1.0", "1.1", "2.0")
+  </context>
+
+<process>
+
+**Follow complete-milestone.md workflow:**
+
+0. **Check for audit:**
+
+   - Look for `.planning/v{{version}}-MILESTONE-AUDIT.md`
+   - If missing or stale: recommend `/mindforge-audit-milestone` first
+   - If audit status is `gaps_found`: recommend `/mindforge-plan-milestone-gaps` first
+   - If audit status is `passed`: proceed to step 1
+
+   ```markdown
+   ## Pre-flight Check
+
+   {If no v{{version}}-MILESTONE-AUDIT.md:}
+   ⚠ No milestone audit found. Run `/mindforge-audit-milestone` first to verify
+   requirements coverage, cross-phase integration, and E2E flows.
+
+   {If audit has gaps:}
+   ⚠ Milestone audit found gaps. Run `/mindforge-plan-milestone-gaps` to create
+   phases that close the gaps, or proceed anyway to accept as tech debt.
+
+   {If audit passed:}
+   ✓ Milestone audit passed. Proceeding with completion.
+   ```
+
+1. **Verify readiness:**
+
+   - Check all phases in milestone have completed plans (SUMMARY.md exists)
+   - Present milestone scope and stats
+   - Wait for confirmation
+
+2. **Gather stats:**
+
+   - Count phases, plans, tasks
+   - Calculate git range, file changes, LOC
+   - Extract timeline from git log
+   - Present summary, confirm
+
+3. **Extract accomplishments:**
+
+   - Read all phase SUMMARY.md files in milestone range
+   - Extract 4-6 key accomplishments
+   - Present for approval
+
+4. **Archive milestone:**
+
+   - Create `.planning/milestones/v{{version}}-ROADMAP.md`
+   - Extract full phase details from ROADMAP.md
+   - Fill milestone-archive.md template
+   - Update ROADMAP.md to one-line summary with link
+
+5. **Archive requirements:**
+
+   - Create `.planning/milestones/v{{version}}-REQUIREMENTS.md`
+   - Mark all v1 requirements as complete (checkboxes checked)
+   - Note requirement outcomes (validated, adjusted, dropped)
+   - Delete `.planning/REQUIREMENTS.md` (fresh one created for next milestone)
+
+6. **Update PROJECT.md:**
+
+   - Add "Current State" section with shipped version
+   - Add "Next Milestone Goals" section
+   - Archive previous content in `<details>` (if v1.1+)
+
+7. **Commit and tag:**
+
+   - Stage: MILESTONES.md, PROJECT.md, ROADMAP.md, STATE.md, archive files
+   - Commit: `chore: archive v{{version}} milestone`
+   - Tag: `git tag -a v{{version}} -m "[milestone summary]"`
+   - Ask about pushing tag
+
+8. **Offer next steps:**
+   - `/mindforge-new-milestone` — start next milestone (questioning → research → requirements → roadmap)
+
+</process>
+
+<success_criteria>
+
+- Milestone archived to `.planning/milestones/v{{version}}-ROADMAP.md`
+- Requirements archived to `.planning/milestones/v{{version}}-REQUIREMENTS.md`
+- `.planning/REQUIREMENTS.md` deleted (fresh for next milestone)
+- ROADMAP.md collapsed to one-line entry
+- PROJECT.md updated with current state
+- Git tag v{{version}} created
+- Commit successful
+- User knows next steps (including need for fresh requirements)
+  </success_criteria>
+
+<critical_rules>
+
+- **Load workflow first:** Read complete-milestone.md before executing
+- **Verify completion:** All phases must have SUMMARY.md files
+- **User confirmation:** Wait for approval at verification gates
+- **Archive before deleting:** Always create archive files before updating/deleting originals
+- **One-line summary:** Collapsed milestone in ROADMAP.md should be single line with link
+- **Context efficiency:** Archive keeps ROADMAP.md and REQUIREMENTS.md constant size per milestone
+- **Fresh requirements:** Next milestone starts with `/mindforge-new-milestone` which includes requirements definition
+  </critical_rules>

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

@@ -0,0 +1,163 @@
+---
+name: mindforge-debug
+description: Systematic debugging with persistent state across context resets
+---
+
+
+<objective>
+Debug issues using scientific method with subagent isolation.
+
+**Orchestrator role:** Gather symptoms, spawn mindforge-debugger agent, handle checkpoints, spawn continuations.
+
+**Why subagent:** Investigation burns context fast (reading files, forming hypotheses, testing). Fresh 200k context per investigation. Main context stays lean for user interaction.
+</objective>
+
+<context>
+User's issue: $ARGUMENTS
+
+Check for active sessions:
+```bash
+ls .planning/debug/*.md 2>/dev/null | grep -v resolved | head -5
+```
+</context>
+
+<process>
+
+## 0. Initialize Context
+
+```bash
+INIT=$(node ".agent/bin/mindforge-tools.cjs" state load)
+if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
+```
+
+Extract `commit_docs` from init JSON. Resolve debugger model:
+```bash
+debugger_model=$(node ".agent/bin/mindforge-tools.cjs" resolve-model mindforge-debugger --raw)
+```
+
+## 1. Check Active Sessions
+
+If active sessions exist AND no $ARGUMENTS:
+- List sessions with status, hypothesis, next action
+- User picks number to resume OR describes new issue
+
+If $ARGUMENTS provided OR user describes new issue:
+- Continue to symptom gathering
+
+## 2. Gather Symptoms (if new issue)
+
+Use AskUserQuestion for each:
+
+1. **Expected behavior** - What should happen?
+2. **Actual behavior** - What happens instead?
+3. **Error messages** - Any errors? (paste or describe)
+4. **Timeline** - When did this start? Ever worked?
+5. **Reproduction** - How do you trigger it?
+
+After all gathered, confirm ready to investigate.
+
+## 3. Spawn mindforge-debugger Agent
+
+Fill prompt and spawn:
+
+```markdown
+<objective>
+Investigate issue: {slug}
+
+**Summary:** {trigger}
+</objective>
+
+<symptoms>
+expected: {expected}
+actual: {actual}
+errors: {errors}
+reproduction: {reproduction}
+timeline: {timeline}
+</symptoms>
+
+<mode>
+symptoms_prefilled: true
+goal: find_and_fix
+</mode>
+
+<debug_file>
+Create: .planning/debug/{slug}.md
+</debug_file>
+```
+
+```
+Task(
+  prompt=filled_prompt,
+  subagent_type="mindforge-debugger",
+  model="{debugger_model}",
+  description="Debug {slug}"
+)
+```
+
+## 4. Handle Agent Return
+
+**If `## ROOT CAUSE FOUND`:**
+- Display root cause and evidence summary
+- Offer options:
+  - "Fix now" - spawn fix subagent
+  - "Plan fix" - suggest /mindforge-plan-phase --gaps
+  - "Manual fix" - done
+
+**If `## CHECKPOINT REACHED`:**
+- Present checkpoint details to user
+- Get user response
+- If checkpoint type is `human-verify`:
+  - If user confirms fixed: continue so agent can finalize/resolve/archive
+  - If user reports issues: continue so agent returns to investigation/fixing
+- Spawn continuation agent (see step 5)
+
+**If `## INVESTIGATION INCONCLUSIVE`:**
+- Show what was checked and eliminated
+- Offer options:
+  - "Continue investigating" - spawn new agent with additional context
+  - "Manual investigation" - done
+  - "Add more context" - gather more symptoms, spawn again
+
+## 5. Spawn Continuation Agent (After Checkpoint)
+
+When user responds to checkpoint, spawn fresh agent:
+
+```markdown
+<objective>
+Continue debugging {slug}. Evidence is in the debug file.
+</objective>
+
+<prior_state>
+<files_to_read>
+- .planning/debug/{slug}.md (Debug session state)
+</files_to_read>
+</prior_state>
+
+<checkpoint_response>
+**Type:** {checkpoint_type}
+**Response:** {user_response}
+</checkpoint_response>
+
+<mode>
+goal: find_and_fix
+</mode>
+```
+
+```
+Task(
+  prompt=continuation_prompt,
+  subagent_type="mindforge-debugger",
+  model="{debugger_model}",
+  description="Continue debug {slug}"
+)
+```
+
+</process>
+
+<success_criteria>
+- [ ] Active sessions checked
+- [ ] Symptoms gathered (if new)
+- [ ] mindforge-debugger spawned with context
+- [ ] Checkpoints handled correctly
+- [ ] Root cause confirmed before fixing
+</success_criteria>