mindforge-cc 2.1.0 → 2.1.2

package/.agent/skills/mindforge-remove-workspace/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: mindforge-remove-workspace
+description: Remove a MindForge workspace and clean up worktrees
+---
+
+<context>
+**Arguments:**
+- `<workspace-name>` (required) — Name of the workspace to remove
+</context>
+
+<objective>
+Remove a workspace directory after confirmation. For worktree strategy, runs `git worktree remove` for each member repo first. Refuses if any repo has uncommitted changes.
+</objective>
+
+<execution_context>
+@.agent/workflows/mindforge-remove-workspace.md
+@.agent/references/ui-brand.md
+</execution_context>
+
+<process>
+Execute the remove-workspace workflow from @.agent/workflows/mindforge-remove-workspace.md end-to-end.
+</process>

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

@@ -0,0 +1,186 @@
+---
+name: mindforge-research-phase
+description: Research how to implement a phase (standalone - usually use /mindforge-plan-phase instead)
+---
+
+
+<objective>
+Research how to implement a phase. Spawns mindforge-phase-researcher agent with phase context.
+
+**Note:** This is a standalone research command. For most workflows, use `/mindforge-plan-phase` which integrates research automatically.
+
+**Use this command when:**
+- You want to research without planning yet
+- You want to re-research after planning is complete
+- You need to investigate before deciding if a phase is feasible
+
+**Orchestrator role:** Parse phase, validate against roadmap, check existing research, gather context, spawn researcher agent, present results.
+
+**Why subagent:** Research burns context fast (WebSearch, Context7 queries, source verification). Fresh 200k context for investigation. Main context stays lean for user interaction.
+</objective>
+
+<context>
+Phase number: $ARGUMENTS (required)
+
+Normalize phase input in step 1 before any directory lookups.
+</context>
+
+<process>
+
+## 0. Initialize Context
+
+```bash
+INIT=$(node ".agent/bin/mindforge-tools.cjs" init phase-op "$ARGUMENTS")
+if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
+```
+
+Extract from init JSON: `phase_dir`, `phase_number`, `phase_name`, `phase_found`, `commit_docs`, `has_research`, `state_path`, `requirements_path`, `context_path`, `research_path`.
+
+Resolve researcher model:
+```bash
+RESEARCHER_MODEL=$(node ".agent/bin/mindforge-tools.cjs" resolve-model mindforge-phase-researcher --raw)
+```
+
+## 1. Validate Phase
+
+```bash
+PHASE_INFO=$(node ".agent/bin/mindforge-tools.cjs" roadmap get-phase "${phase_number}")
+```
+
+**If `found` is false:** Error and exit. **If `found` is true:** Extract `phase_number`, `phase_name`, `goal` from JSON.
+
+## 2. Check Existing Research
+
+```bash
+ls .planning/phases/${PHASE}-*/RESEARCH.md 2>/dev/null
+```
+
+**If exists:** Offer: 1) Update research, 2) View existing, 3) Skip. Wait for response.
+
+**If doesn't exist:** Continue.
+
+## 3. Gather Phase Context
+
+Use paths from INIT (do not inline file contents in orchestrator context):
+- `requirements_path`
+- `context_path`
+- `state_path`
+
+Present summary with phase description and what files the researcher will load.
+
+## 4. Spawn mindforge-phase-researcher Agent
+
+Research modes: ecosystem (default), feasibility, implementation, comparison.
+
+```markdown
+<research_type>
+Phase Research — investigating HOW to implement a specific phase well.
+</research_type>
+
+<key_insight>
+The question is NOT "which library should I use?"
+
+The question is: "What do I not know that I don't know?"
+
+For this phase, discover:
+- What's the established architecture pattern?
+- What libraries form the standard stack?
+- What problems do people commonly hit?
+- What's SOTA vs what the agent's training thinks is SOTA?
+- What should NOT be hand-rolled?
+</key_insight>
+
+<objective>
+Research implementation approach for Phase {phase_number}: {phase_name}
+Mode: ecosystem
+</objective>
+
+<files_to_read>
+- {requirements_path} (Requirements)
+- {context_path} (Phase context from discuss-phase, if exists)
+- {state_path} (Prior project decisions and blockers)
+</files_to_read>
+
+<additional_context>
+**Phase description:** {phase_description}
+</additional_context>
+
+<downstream_consumer>
+Your RESEARCH.md will be loaded by `/mindforge-plan-phase` which uses specific sections:
+- `## Standard Stack` → Plans use these libraries
+- `## Architecture Patterns` → Task structure follows these
+- `## Don't Hand-Roll` → Tasks NEVER build custom solutions for listed problems
+- `## Common Pitfalls` → Verification steps check for these
+- `## Code Examples` → Task actions reference these patterns
+
+Be prescriptive, not exploratory. "Use X" not "Consider X or Y."
+</downstream_consumer>
+
+<quality_gate>
+Before declaring complete, verify:
+- [ ] All domains investigated (not just some)
+- [ ] Negative claims verified with official docs
+- [ ] Multiple sources for critical claims
+- [ ] Confidence levels assigned honestly
+- [ ] Section names match what plan-phase expects
+</quality_gate>
+
+<output>
+Write to: .planning/phases/${PHASE}-{slug}/${PHASE}-RESEARCH.md
+</output>
+```
+
+```
+Task(
+  prompt=filled_prompt,
+  subagent_type="mindforge-phase-researcher",
+  model="{researcher_model}",
+  description="Research Phase {phase}"
+)
+```
+
+## 5. Handle Agent Return
+
+**`## RESEARCH COMPLETE`:** Display summary, offer: Plan phase, Dig deeper, Review full, Done.
+
+**`## CHECKPOINT REACHED`:** Present to user, get response, spawn continuation.
+
+**`## RESEARCH INCONCLUSIVE`:** Show what was attempted, offer: Add context, Try different mode, Manual.
+
+## 6. Spawn Continuation Agent
+
+```markdown
+<objective>
+Continue research for Phase {phase_number}: {phase_name}
+</objective>
+
+<prior_state>
+<files_to_read>
+- .planning/phases/${PHASE}-{slug}/${PHASE}-RESEARCH.md (Existing research)
+</files_to_read>
+</prior_state>
+
+<checkpoint_response>
+**Type:** {checkpoint_type}
+**Response:** {user_response}
+</checkpoint_response>
+```
+
+```
+Task(
+  prompt=continuation_prompt,
+  subagent_type="mindforge-phase-researcher",
+  model="{researcher_model}",
+  description="Continue research Phase {phase}"
+)
+```
+
+</process>
+
+<success_criteria>
+- [ ] Phase validated against roadmap
+- [ ] Existing research checked
+- [ ] mindforge-phase-researcher spawned with context
+- [ ] Checkpoints handled correctly
+- [ ] User knows next steps
+</success_criteria>

package/.agent/skills/mindforge-resume-work/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: mindforge-resume-work
+description: Resume work from previous session with full context restoration
+---
+
+
+<objective>
+Restore complete project context and resume work seamlessly from previous session.
+
+Routes to the resume-project workflow which handles:
+
+- STATE.md loading (or reconstruction if missing)
+- Checkpoint detection (.continue-here files)
+- Incomplete work detection (PLAN without SUMMARY)
+- Status presentation
+- Context-aware next action routing
+  </objective>
+
+<execution_context>
+@.agent/workflows/mindforge-resume-project.md
+</execution_context>
+
+<process>
+**Follow the resume-project workflow** from `@.agent/workflows/mindforge-resume-project.md`.
+
+The workflow handles all resumption logic including:
+
+1. Project existence verification
+2. STATE.md loading or reconstruction
+3. Checkpoint and incomplete work detection
+4. Visual status presentation
+5. Context-aware option offering (checks CONTEXT.md before suggesting plan vs discuss)
+6. Routing to appropriate next command
+7. Session continuity updates
+   </process>

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

@@ -0,0 +1,31 @@
+---
+name: mindforge-review
+description: Request cross-AI peer review of phase plans from external AI CLIs
+---
+
+
+<objective>
+Invoke external AI CLIs (Gemini, the agent, Codex) to independently review phase plans.
+Produces a structured REVIEWS.md with per-reviewer feedback that can be fed back into
+planning via /mindforge-plan-phase --reviews.
+
+**Flow:** Detect CLIs → Build review prompt → Invoke each CLI → Collect responses → Write REVIEWS.md
+</objective>
+
+<execution_context>
+@.agent/workflows/mindforge-review.md
+</execution_context>
+
+<context>
+Phase number: extracted from $ARGUMENTS (required)
+
+**Flags:**
+- `--gemini` — Include Gemini CLI review
+- `--claude` — Include the agent CLI review (uses separate session)
+- `--codex` — Include Codex CLI review
+- `--all` — Include all available CLIs
+</context>
+
+<process>
+Execute the review workflow from @.agent/workflows/mindforge-review.md end-to-end.
+</process>

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

@@ -0,0 +1,58 @@
+---
+name: mindforge-review-backlog
+description: Review and promote backlog items to active milestone
+---
+
+
+<objective>
+Review all 999.x backlog items and optionally promote them into the active
+milestone sequence or remove stale entries.
+</objective>
+
+<process>
+
+1. **List backlog items:**
+   ```bash
+   ls -d .planning/phases/999* 2>/dev/null || echo "No backlog items found"
+   ```
+
+2. **Read ROADMAP.md** and extract all 999.x phase entries:
+   ```bash
+   cat .planning/ROADMAP.md
+   ```
+   Show each backlog item with its description, any accumulated context (CONTEXT.md, RESEARCH.md), and creation date.
+
+3. **Present the list to the user** via AskUserQuestion:
+   - For each backlog item, show: phase number, description, accumulated artifacts
+   - Options per item: **Promote** (move to active), **Keep** (leave in backlog), **Remove** (delete)
+
+4. **For items to PROMOTE:**
+   - Find the next sequential phase number in the active milestone
+   - Rename the directory from `999.x-slug` to `{new_num}-slug`:
+     ```bash
+     NEW_NUM=$(node ".agent/bin/mindforge-tools.cjs" phase add "${DESCRIPTION}" --raw)
+     ```
+   - Move accumulated artifacts to the new phase directory
+   - Update ROADMAP.md: move the entry from `## Backlog` section to the active phase list
+   - Remove `(BACKLOG)` marker
+   - Add appropriate `**Depends on:**` field
+
+5. **For items to REMOVE:**
+   - Delete the phase directory
+   - Remove the entry from ROADMAP.md `## Backlog` section
+
+6. **Commit changes:**
+   ```bash
+   node ".agent/bin/mindforge-tools.cjs" commit "docs: review backlog — promoted N, removed M" --files .planning/ROADMAP.md
+   ```
+
+7. **Report summary:**
+   ```
+   ## 📋 Backlog Review Complete
+
+   Promoted: {list of promoted items with new phase numbers}
+   Kept: {list of items remaining in backlog}
+   Removed: {list of deleted items}
+   ```
+
+</process>

package/.agent/skills/mindforge-session-report/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: mindforge-session-report
+description: Generate a session report with token usage estimates, work summary, and outcomes
+---
+
+<objective>
+Generate a structured SESSION_REPORT.md document capturing session outcomes, work performed, and estimated resource usage. Provides a shareable artifact for post-session review.
+</objective>
+
+<execution_context>
+@.agent/workflows/mindforge-session-report.md
+</execution_context>
+
+<process>
+Execute the session-report workflow from @.agent/workflows/mindforge-session-report.md end-to-end.
+</process>

package/.agent/skills/mindforge-set-profile/SKILL.md

@@ -0,0 +1,9 @@
+---
+name: mindforge-set-profile
+description: Switch model profile for MindForge agents (quality/balanced/budget/inherit)
+---
+
+
+Show the following output to the user verbatim, with no extra commentary:
+
+!`node ".agent/bin/mindforge-tools.cjs" config-set-model-profile $ARGUMENTS --raw`

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

@@ -0,0 +1,32 @@
+---
+name: mindforge-settings
+description: Configure MindForge workflow toggles and model profile
+---
+
+
+<objective>
+Interactive configuration of MindForge workflow agents and model profile via multi-question prompt.
+
+Routes to the settings workflow which handles:
+- Config existence ensuring
+- Current settings reading and parsing
+- Interactive 5-question prompt (model, research, plan_check, verifier, branching)
+- Config merging and writing
+- Confirmation display with quick command references
+</objective>
+
+<execution_context>
+@.agent/workflows/mindforge-settings.md
+</execution_context>
+
+<process>
+**Follow the settings workflow** from `@.agent/workflows/mindforge-settings.md`.
+
+The workflow handles all logic including:
+1. Config file creation with defaults if missing
+2. Current config reading
+3. Interactive settings presentation with pre-selection
+4. Answer parsing and config merging
+5. File writing
+6. Confirmation display
+</process>

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

@@ -0,0 +1,16 @@
+---
+name: mindforge-ship
+description: Create PR, run review, and prepare for merge after verification passes
+---
+
+<objective>
+Bridge local completion → merged PR. After /mindforge-verify-work passes, ship the work: push branch, create PR with auto-generated body, optionally trigger review, and track the merge.
+
+Closes the plan → execute → verify → ship loop.
+</objective>
+
+<execution_context>
+@.agent/workflows/mindforge-ship.md
+</execution_context>
+
+Execute the ship workflow from @.agent/workflows/mindforge-ship.md end-to-end.

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

@@ -0,0 +1,16 @@
+---
+name: mindforge-stats
+description: Display project statistics — phases, plans, requirements, git metrics, and timeline
+---
+
+<objective>
+Display comprehensive project statistics including phase progress, plan execution metrics, requirements completion, git history stats, and project timeline.
+</objective>
+
+<execution_context>
+@.agent/workflows/mindforge-stats.md
+</execution_context>
+
+<process>
+Execute the stats workflow from @.agent/workflows/mindforge-stats.md end-to-end.
+</process>

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

@@ -0,0 +1,123 @@
+---
+name: mindforge-thread
+description: Manage persistent context threads for cross-session work
+---
+
+
+<objective>
+Create, list, or resume persistent context threads. Threads are lightweight
+cross-session knowledge stores for work that spans multiple sessions but
+doesn't belong to any specific phase.
+</objective>
+
+<process>
+
+**Parse $ARGUMENTS to determine mode:**
+
+<mode_list>
+**If no arguments or $ARGUMENTS is empty:**
+
+List all threads:
+```bash
+ls .planning/threads/*.md 2>/dev/null
+```
+
+For each thread, read the first few lines to show title and status:
+```
+## Active Threads
+
+| Thread | Status | Last Updated |
+|--------|--------|-------------|
+| fix-deploy-key-auth | OPEN | 2026-03-15 |
+| pasta-tcp-timeout | RESOLVED | 2026-03-12 |
+| perf-investigation | IN PROGRESS | 2026-03-17 |
+```
+
+If no threads exist, show:
+```
+No threads found. Create one with: /mindforge-thread <description>
+```
+</mode_list>
+
+<mode_resume>
+**If $ARGUMENTS matches an existing thread name (file exists):**
+
+Resume the thread — load its context into the current session:
+```bash
+cat ".planning/threads/${THREAD_NAME}.md"
+```
+
+Display the thread content and ask what the user wants to work on next.
+Update the thread's status to `IN PROGRESS` if it was `OPEN`.
+</mode_resume>
+
+<mode_create>
+**If $ARGUMENTS is a new description (no matching thread file):**
+
+Create a new thread:
+
+1. Generate slug from description:
+   ```bash
+   SLUG=$(node ".agent/bin/mindforge-tools.cjs" generate-slug "$ARGUMENTS")
+   ```
+
+2. Create the threads directory if needed:
+   ```bash
+   mkdir -p .planning/threads
+   ```
+
+3. Write the thread file:
+   ```bash
+   cat > ".planning/threads/${SLUG}.md" << 'EOF'
+   # Thread: {description}
+
+   ## Status: OPEN
+
+   ## Goal
+
+   {description}
+
+   ## Context
+
+   *Created from conversation on {today's date}.*
+
+   ## References
+
+   - *(add links, file paths, or issue numbers)*
+
+   ## Next Steps
+
+   - *(what the next session should do first)*
+   EOF
+   ```
+
+4. If there's relevant context in the current conversation (code snippets,
+   error messages, investigation results), extract and add it to the Context
+   section.
+
+5. Commit:
+   ```bash
+   node ".agent/bin/mindforge-tools.cjs" commit "docs: create thread — ${ARGUMENTS}" --files ".planning/threads/${SLUG}.md"
+   ```
+
+6. Report:
+   ```
+   ## 🧵 Thread Created
+
+   Thread: {slug}
+   File: .planning/threads/{slug}.md
+
+   Resume anytime with: /mindforge-thread {slug}
+   ```
+</mode_create>
+
+</process>
+
+<notes>
+- Threads are NOT phase-scoped — they exist independently of the roadmap
+- Lighter weight than /mindforge-pause-work — no phase state, no plan context
+- The value is in Context and Next Steps — a cold-start session can pick up immediately
+- Threads can be promoted to phases or backlog items when they mature:
+  /mindforge-add-phase or /mindforge-add-backlog with context from the thread
+- Thread files live in .planning/threads/ — no collision with phases or other MindForge structures
+</notes>

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

@@ -0,0 +1,24 @@
+---
+name: mindforge-ui-phase
+description: Generate UI design contract (UI-SPEC.md) for frontend phases
+---
+
+<objective>
+Create a UI design contract (UI-SPEC.md) for a frontend phase.
+Orchestrates mindforge-ui-researcher and mindforge-ui-checker.
+Flow: Validate → Research UI → Verify UI-SPEC → Done
+</objective>
+
+<execution_context>
+@.agent/workflows/mindforge-ui-phase.md
+@.agent/references/ui-brand.md
+</execution_context>
+
+<context>
+Phase number: $ARGUMENTS — optional, auto-detects next unplanned phase if omitted.
+</context>
+
+<process>
+Execute @.agent/workflows/mindforge-ui-phase.md end-to-end.
+Preserve all workflow gates.
+</process>

package/.agent/skills/mindforge-ui-review/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: mindforge-ui-review
+description: Retroactive 6-pillar visual audit of implemented frontend code
+---
+
+<objective>
+Conduct a retroactive 6-pillar visual audit. Produces UI-REVIEW.md with
+graded assessment (1-4 per pillar). Works on any project.
+Output: {phase_num}-UI-REVIEW.md
+</objective>
+
+<execution_context>
+@.agent/workflows/mindforge-ui-review.md
+@.agent/references/ui-brand.md
+</execution_context>
+
+<context>
+Phase: $ARGUMENTS — optional, defaults to last completed phase.
+</context>
+
+<process>
+Execute @.agent/workflows/mindforge-ui-review.md end-to-end.
+Preserve all workflow gates.
+</process>

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

@@ -0,0 +1,35 @@
+---
+name: mindforge-update
+description: Update MindForge to latest version with changelog display
+---
+
+
+<objective>
+Check for MindForge updates, install if available, and display what changed.
+
+Routes to the update workflow which handles:
+- Version detection (local vs global installation)
+- npm version checking
+- Changelog fetching and display
+- User confirmation with clean install warning
+- Update execution and cache clearing
+- Restart reminder
+</objective>
+
+<execution_context>
+@.agent/workflows/mindforge-update.md
+</execution_context>
+
+<process>
+**Follow the update workflow** from `@.agent/workflows/mindforge-update.md`.
+
+The workflow handles all logic including:
+1. Installed version detection (local/global)
+2. Latest version checking via npm
+3. Version comparison
+4. Changelog fetching and extraction
+5. Clean install warning display
+6. User confirmation
+7. Update execution
+8. Cache clearing
+</process>

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

@@ -0,0 +1,26 @@
+---
+name: mindforge-validate-phase
+description: Retroactively audit and fill Nyquist validation gaps for a completed phase
+---
+
+<objective>
+Audit Nyquist validation coverage for a completed phase. Three states:
+- (A) VALIDATION.md exists — audit and fill gaps
+- (B) No VALIDATION.md, SUMMARY.md exists — reconstruct from artifacts
+- (C) Phase not executed — exit with guidance
+
+Output: updated VALIDATION.md + generated test files.
+</objective>
+
+<execution_context>
+@.agent/workflows/mindforge-validate-phase.md
+</execution_context>
+
+<context>
+Phase: $ARGUMENTS — optional, defaults to last completed phase.
+</context>
+
+<process>
+Execute @.agent/workflows/mindforge-validate-phase.md.
+Preserve all workflow gates.
+</process>