mindforge-cc 2.0.0 → 2.1.0

package/.claude/commands/mindforge/new-runtime.md

@@ -1,19 +1,29 @@
-# /mindforge:new-runtime
+---
+name: mindforge:new-runtime
+description: Scaffold support for a new AI coding runtime
+argument-hint: [name]
+allowed-tools:
+  - run_command
+  - list_dir
+  - write_to_file
+---
 
-Scaffold support for a new AI coding runtime.
+<objective>
+Extend MindForge to support additional AI environments (Zed, Cursor, Void, etc.) by scaffolding the necessary instruction files and updating the global installer configuration.
+</objective>
 
-## Usage
+<execution_context>
+.claude/commands/mindforge/new-runtime.md
+</execution_context>
 
-/mindforge:new-runtime [name]
+<context>
+Config: bin/installer-core.js
+Targets: Global and Local scopes.
+</context>
 
-## Action
-
-1.  Identify target runtime's entry file format (e.g. .myrules, instructions.md)
-2.  Scaffold the required directories in both global and local scopes
-3.  Add a new entry to the RUNTIMES configuration in `bin/installer-core.js`
-4.  Generate first-run instructions for the new runtime
-
-## Examples
-
-/mindforge:new-runtime void-editor
-/mindforge:new-runtime zed-ai
+<process>
+1. **Identify**: Determine the specific instruction file format for the target runtime.
+2. **Scaffold**: Create the directory structure and placeholder documentation for the new integration.
+3. **Configure**: Update the central `installer-core.js` mapping to include the new runtime identifier.
+4. **Onboard**: Generate customized first-run instructions for the user to enable the runtime immediately.
+</process>

package/.claude/commands/mindforge/next.md

@@ -1,105 +1,34 @@
-# MindForge — Next Command
-# Usage: /mindforge:next
-
-Auto-detect the current project state and execute the appropriate next step.
-The user does not need to know the workflow. MindForge figures it out.
-
-## HANDOFF.json priority rule
-Check HANDOFF.json BEFORE running the decision tree.
-
-If HANDOFF.json exists AND `updated_at` is within 48 hours AND `next_task` is not null:
-present the HANDOFF state first. Only run the decision tree if the user declines
-or the HANDOFF.json is stale.
-
-## State detection logic
-
-Read STATE.md and HANDOFF.json. Then follow this decision tree:
-
-### Decision tree
-
-```
-Does .planning/PROJECT.md exist AND have content?
-  NO  → Run /mindforge:init-project
-  YES → Continue
-
-Does .planning/ROADMAP.md exist AND have phases defined?
-  NO  → Tell user: "Project is initialised but no phases are defined yet.
-         Describe what Phase 1 should accomplish and I'll plan it."
-         Then run /mindforge:plan-phase 1
-  YES → Continue
-
-Read the phase status from STATE.md.
-
-Does the current phase have plans? (check .planning/phases/[N]/PLAN-[N]-*.md)
-  NO  → Run /mindforge:plan-phase [N]
-  YES → Continue
-
-Do SUMMARY files exist for all plans in the current phase?
-  NO  → Run /mindforge:execute-phase [N]
-  YES → Continue
-
-Does VERIFICATION.md exist for the current phase?
-  NO  → Run /mindforge:verify-phase [N] (automated part)
-  YES → Continue
-
-Does UAT.md exist and show all tests passing?
-  NO  → Run /mindforge:verify-phase [N] (UAT part)
-  YES → Continue
-
-Is this phase marked as shipped in STATE.md?
-  NO  → Run /mindforge:ship [N]
-  YES → Continue
-
-Are there more phases in ROADMAP.md?
-  YES → Increment phase number. Run /mindforge:plan-phase [N+1]
-  NO  → Tell user: "All phases complete! Run /mindforge:ship [N] for the final release."
-```
-
-## Partial phase execution handling
-In the decision tree step "Do SUMMARY files exist for all plans?":
-
-Do not treat this as binary. Check individually:
-
-```
-PLAN-[N]-01.md exists?          SUMMARY-[N]-01.md exists?
-PLAN-[N]-02.md exists?          SUMMARY-[N]-02.md exists?
-PLAN-[N]-03.md exists?          SUMMARY-[N]-03.md exists?
-```
-
-If some SUMMARY files exist and some don't: this is a partially-executed phase.
-Report: "Phase [N] is partially executed: plans [X, Y] are done, [Z] is not."
-Ask: "Resume execution from Plan [Z]? (yes/no)"
-Do not restart the entire phase — resume from the first missing SUMMARY.
-
-## Before auto-executing: always confirm
-Before running any command automatically, tell the user:
-
-```
-MindForge next step detected:
-  Current state : [description of current state]
-  Next action   : [what will be run]
-  Command       : /mindforge:[command] [args]
-
-Run this now? (yes/no/different)
-```
-
-If user says "different": ask what they want to do instead.
-If user says "yes": proceed with the detected command.
-
-## Handling HANDOFF.json (session restart)
-If HANDOFF.json has a `next_task` field from a previous session:
-Present it prominently:
-
-```
-Previous session found:
-  Saved at  : [updated_at from HANDOFF.json]
-  Left off  : [last_completed_task]
-  Next task : [next_task]
-
-Options:
-  1. Continue from where we left off
-  2. Check current state and determine next step fresh
-  3. Tell me what you want to do
-
-Choose 1, 2, or 3:
-```
+---
+name: mindforge:next
+description: Auto-detect the current state and execute the appropriate next step
+argument-hint: none
+allowed-tools:
+  - list_dir
+  - view_file
+---
+
+<objective>
+Simplify the developer workflow by automatically determining the most logical next action based on the current project state, guided by `STATE.md` and `HANDOFF.json`.
+</objective>
+
+<execution_context>
+.claude/commands/mindforge/next.md
+</execution_context>
+
+<context>
+Priority: `HANDOFF.json` is used for session continuity if updated within 48 hours.
+State Awareness: Detects missing initialisation, missing plans, partial execution, or pending verification/shipping.
+</context>
+
+<process>
+1. **Session Check**: Read `HANDOFF.json`. If a fresh `next_task` exists, offer to resume.
+2. **State Analysis**: Run the decision tree against `STATE.md`:
+    - Not initialised? → `init-project`.
+    - No phases? → `plan-phase 1`.
+    - Plan missing? → `plan-phase [N]`.
+    - Partial execution? → Offer to resume `execute-phase [N]`.
+    - Pending verification? → `verify-phase [N]`.
+    - Pending shipping? → `ship [N]`.
+3. **Handling Partially Executed Phases**: Identify specifically which plans lack SUMMARY files and offer targeted resumption.
+4. **Confirm**: Present the detected next step and command to the user for confirmation before acting.
+</process>

package/.claude/commands/mindforge/note.md

@@ -0,0 +1,35 @@
+---
+name: mindforge:note
+description: Capture an idea, task, or issue that surfaces during a session as a quick note for later
+argument-hint: <text> [list|promote N]
+allowed-tools:
+  - list_dir
+  - view_file
+  - write_to_file
+  - multi_replace_file_content
+---
+
+<objective>
+Provide a zero-friction way to capture ephemeral thoughts, bugs, or todos during an active session without interrupting the current flow, with the ability to later promote them to official tasks.
+</objective>
+
+<execution_context>
+.claude/commands/mindforge/note.md
+</execution_context>
+
+<context>
+Arguments: $ARGUMENTS (The note text or subcommand like `list` or `promote`)
+Storage: .planning/notes/
+Target for Promotion: ROADMAP.md or STATE.md
+</context>
+
+<process>
+1. **Route Subcommand**:
+    - If `list`: Read all files in `.planning/notes/` and present them.
+    - If `promote <N>`: Read note N, add it to current phase/milestone in STATE.md or ROADMAP.md, then move the note to `.planning/notes/archived/`.
+    - Else (default): Capture the text.
+2. **Capture Flow**:
+    - Ensure `.planning/notes/` directory.
+    - Create a file `note_[timestamp].md` with the content.
+3. **Confirm**: Quick confirmation of capture or promotion result.
+</process>

package/.claude/commands/mindforge/plan-phase.md

@@ -1,125 +1,34 @@
-Plan a project phase. Usage: /mindforge:plan-phase [N]
-
-## Pre-check
-If N is not given, read STATE.md for the current phase number and increment by 1.
-Read PROJECT.md, REQUIREMENTS.md, ARCHITECTURE.md, and STATE.md before proceeding.
-
-## Pre-read (before any questions or planning)
-
-Read these files in order:
-1. `.planning/PROJECT.md`
-2. `.planning/REQUIREMENTS.md`
-3. `.planning/ARCHITECTURE.md`
-4. `.planning/STATE.md`
-5. `.planning/phases/phase-[N]/CONTEXT.md` (if it exists)
-
-### If CONTEXT.md exists for phase [N]:
-This means `/mindforge:discuss-phase [N]` was already run.
-The user's implementation decisions are already captured.
-DO NOT re-ask questions that CONTEXT.md already answers.
-Read CONTEXT.md completely before asking any clarifying questions.
-Report: "I've read the phase discussion context. [N] decisions were captured.
-Planning will follow these decisions."
-
-### If CONTEXT.md has open questions:
-Read the "Open questions" section in CONTEXT.md.
-Present unresolved questions to the user NOW, before planning begins.
-Do not create plans that assume answers to open questions without confirming first.
-
-### If CONTEXT.md does NOT exist for phase [N]:
-Proceed normally with the discussion → planning flow.
-
-## Step 1 — Discuss phase scope
-Ask:
-1. "Describe what Phase [N] should accomplish. 2-3 sentences."
-2. "Have you already made any implementation decisions for this phase?
-    (libraries, patterns, approaches) If yes, list them."
-3. "Are there any constraints I should know about?
-    (deadlines, dependencies on other teams, tech limitations)"
-
-Write answers to `.planning/phases/phase-[N]/CONTEXT.md`.
-
-If `.planning/phases/phase-[N]/CONTEXT.md` already exists:
-1. Read it first.
-2. If it has "Open questions", ask the user to resolve them before planning.
-3. Update CONTEXT.md with the answers and mark those questions as resolved.
-
-### If CONTEXT.md exists — skip already-answered questions
-Only ask about areas NOT covered in CONTEXT.md.
-Example: if CONTEXT.md captures the layout decision, do not ask "What layout do you want?"
-Respect the prior discussion. Build on it. Do not repeat it.
-
-## Step 2 — Domain research (spawn subagent)
-Spawn a research subagent with this context only:
-- The tech stack from PROJECT.md
-- The phase scope from CONTEXT.md
-- CONVENTIONS.md
-
-Instruct it to investigate:
-1. Best available libraries for this phase's requirements (with version numbers)
-2. Common pitfalls and anti-patterns for this tech domain
-3. Relevant architectural patterns (with tradeoffs)
-4. Any known security considerations specific to this domain
-
-Write findings to `.planning/phases/phase-[N]/RESEARCH.md`.
-
-## Step 3 — Create atomic task plans
-Based on CONTEXT.md and RESEARCH.md, create 3-6 PLAN files.
-Each plan must be completable in a single fresh context window.
-Each plan targets specific files — no plan should touch more than 6 files.
-
-File naming: `.planning/phases/phase-[N]/PLAN-[N]-[NN].md`
-Example: `.planning/phases/1/PLAN-1-01.md`
-
-Each plan uses this XML format:
-
-```xml
-<task type="auto">
-  <n>Short descriptive task name</n>
-  <persona>developer</persona>
-  <phase>[N]</phase>
-  <plan>[NN]</plan>
-  <dependencies>List any PLAN files that must complete before this one, or "none"</dependencies>
-  <files>
-    src/exact/file/path.ts
-    src/another/file.ts
-  </files>
-  <context>
-    Relevant decisions from ARCHITECTURE.md:
-    - [decision]
-    Skills to load before starting:
-    - [skill name if applicable, or "none"]
-  </context>
-  <action>
-    Precise implementation instructions.
-    Include exact library names and versions.
-    Include the approach, not just the goal.
-    Include specific anti-patterns to avoid.
-  </action>
-  <verify>
-    [Exact runnable command or check]
-    Example: curl -X POST localhost:3000/api/auth/login -d '{"email":"test@test.com","password":"test"}' | jq .status
-    Must produce a deterministic pass/fail result.
-  </verify>
-  <done>One sentence definition of done.</done>
-</task>
-```
-
-## Step 4 — Validate plans
-Check every plan against REQUIREMENTS.md:
-- Does this plan implement anything out of scope? If yes: revise.
-- Does this plan contradict ARCHITECTURE.md? If yes: create an ADR first.
-- Is the `<verify>` step actually runnable? If no: rewrite it.
-
-## Step 5 — Update state and confirm
-Update STATE.md: current phase = N, status = "Phase N planned, ready to execute".
-
-Tell the user:
-"✅ Phase [N] planned. [X] task plans created.
-
-Plans:
-  PLAN-[N]-01: [task name]
-  PLAN-[N]-02: [task name]
-  ...
-
-Run /mindforge:execute-phase [N] to begin execution."
+---
+name: mindforge:plan-phase
+description: Plan a project phase by generating atomic task plans
+argument-hint: [N]
+allowed-tools:
+  - view_file
+  - write_to_file
+  - list_dir
+---
+
+<objective>
+Generate a series of atomic, verifiable task plans for a specific project phase, incorporating domain research and captured implementation decisions.
+</objective>
+
+<execution_context>
+.claude/commands/mindforge/plan-phase.md
+</execution_context>
+
+<context>
+Arguments: $ARGUMENTS (Phase N)
+Prerequisites: PROJECT.md, REQUIREMENTS.md, ARCHITECTURE.md, STATE.md, and optionally CONTEXT.md.
+Output: .planning/phases/phase-[N]/PLAN-[N]-[NN].md
+</context>
+
+<process>
+1. **Pre-read**: Resolve phase number and read all foundational context files. If `CONTEXT.md` exists, respect prior decisions.
+2. **Domain Research**: Investigate best libraries, pitfalls, and patterns. Save to `RESEARCH.md`.
+3. **Task Planning**: Create 3-6 atomic PLAN files using the MindForge XML task format. Each plan must be:
+    - Completatable in one window.
+    - Targeted at <6 files.
+    - Verifiable via a deterministic command.
+4. **Validation**: Cross-reference plans against requirements and architecture. Ensure `<verify>` steps are runnable.
+5. **Finalize**: Update `STATE.md` and display the list of generated plans to the user.
+</process>

package/.claude/commands/mindforge/plant-seed.md

@@ -0,0 +1,31 @@
+---
+name: mindforge:plant-seed
+description: Capture speculative ideas with triggers that surface automatically when relevant
+argument-hint: <idea>
+allowed-tools:
+  - list_dir
+  - write_to_file
+  - view_file
+---
+
+<objective>
+Capture speculative or long-term ideas (seeds) and store them in a way that they can be automatically resurfaced when a relevant future milestone or phase is started.
+</objective>
+
+<execution_context>
+.claude/commands/mindforge/plant-seed.md
+</execution_context>
+
+<context>
+Arguments: $ARGUMENTS (The speculative idea)
+Storage: .planning/seeds/
+Trigger mechanism: Files in this directory are checked during `init-project` or `milestone` creation.
+</context>
+
+<process>
+1. **Ensure storage**: Verify `.planning/seeds/` exists; create if not.
+2. **Generate filename**: Create a slugified filename based on the idea or a timestamp.
+3. **Write seed**: Create a markdown file with the idea, any inferred triggers (tags/keywords), and the current timestamp.
+4. **Link to system**: Add a note to the master seed index if one exists.
+5. **Confirm**: Let the user know the seed has been planted and what might trigger its resurrection.
+</process>

package/.claude/commands/mindforge/plugins.md

@@ -1,40 +1,34 @@
-# MindForge — Plugins Command
-# Usage: /mindforge:plugins [list|install|uninstall|info|validate|create] [name]
+---
+name: mindforge:plugins
+description: Manage MindForge plugins and their permission scopes
+argument-hint: [list|install|uninstall|info|validate|create]
+allowed-tools:
+  - run_command
+  - list_dir
+  - view_file
+  - write_to_file
+---
 
-## list
-Read PLUGINS-MANIFEST.md. Display installed plugins with version and permissions.
-If no plugins: "No plugins installed. Find plugins: npm search mindforge-plugin"
+<objective>
+Extend MindForge core functionality through a secure plugin architecture, managing the lifecycle and security boundaries of installed extensions.
+</objective>
 
-## install [plugin-name]
-Full installation protocol per plugin-loader.md:
-1. Resolve package: `mindforge-plugin-[name]` convention
-2. Download to chmod 700 temp directory
-3. Validate plugin.json manifest
-4. Check plugin_api_version compatibility (1.0.0 required)
-5. Run injection guard on ALL .md files in the plugin
-6. Run Level 1 + 2 skill validation on all SKILL.md files
-7. Display permission list for user approval:
-   ```
-   Plugin: mindforge-plugin-jira-advanced v1.0.0
-   Requests these permissions:
-     • read_audit_log:  read AUDIT.jsonl ✅ (safe)
-     • write_audit_log: append to AUDIT.jsonl ⚠️
-     • network_access:  make HTTP requests ⚠️
-   Install? (yes/no)
-   ```
-8. Install components (commands, skills, personas, hooks)
-9. Add to PLUGINS-MANIFEST.md
-10. Write AUDIT entry
+<execution_context>
+.claude/commands/mindforge/plugins.md
+</execution_context>
 
-## uninstall [plugin-name]
-Remove all installed components. Update PLUGINS-MANIFEST.md.
-Confirm: "This will remove [N] commands, [N] skills from this plugin."
+<context>
+Manifest: PLUGINS-MANIFEST.md
+Loader: plugin-loader.md
+Security: Level 1+2 skill validation, injection guards, and explicit permission prompts.
+</context>
 
-## info [plugin-name]
-Display: version, description, author, permissions, commands, skills, personas, hooks.
-
-## validate
-Validate all installed plugins for compatibility, injection safety, permission scope.
-
-## create [plugin-name]
-Generate a plugin scaffold:
+<process>
+1. **Route Action**:
+    - `list`: Show installed plugins and versions.
+    - `install`: Execute the full installation protocol (download, validate manifest, run security guards, prompt for permissions).
+    - `uninstall`: Cleanly remove all components and update the manifest.
+    - `validate`: Audit all installed plugins for injection safety and permission compliance.
+2. **Permission Management**: Display a clear list of requested permissions (network, registry, audit write) and await user approval.
+3. **Audit**: Log all plugin installations and removals.
+</process>

package/.claude/commands/mindforge/pr-review.md

@@ -1,41 +1,32 @@
-# MindForge — PR Review Command
-# Usage: /mindforge:pr-review [--diff path] [--sha base..head] [--output github|json|markdown]
-
-Run the AI PR review engine on a pull request diff.
-
-Steps:
-1. Determine diff source:
-   - `--diff path`: read diff from file
-   - `--sha base..head`: run `git diff base..head`
-   - Default: `git diff HEAD~1` (last commit) or `git diff --staged` (staged changes)
-
-2. Load review context (per ai-reviewer.md):
-   - PROJECT.md, ARCHITECTURE.md, CONVENTIONS.md, SECURITY.md
-   - Current phase's CONTEXT.md (if in an active phase)
-   - Any active ADRs relevant to changed files
-
-3. Detect change type and select review template:
-   - Auth/security changes → Security-focused review template
-   - Database migrations → Database migration review template
-   - API changes → API breaking change review template
-   - Default → Standard review template
-
-4. Check API availability:
-   - ANTHROPIC_API_KEY set? If not: warn and skip AI review
-   - Check daily review limit (from ai-reviewer.md)
-   - Check cache: has this SHA been reviewed in the last 60 minutes?
-
-5. Call Claude API (per ai-reviewer.md buildSystemPrompt + buildReviewPrompt)
-   - Handle errors gracefully — API unavailable is NOT a build failure
-   - Timeout: 60 seconds
-
-6. Format output per --output flag:
-   - github: GitHub-flavoured markdown for PR comment
-   - json: structured JSON with findings array
-   - markdown: standard markdown
-
-7. Write to output:
-   - If in CI: write to /tmp/mindforge-review.md (read by GitHub Actions step)
-   - If interactive: display to user
-
-8. Write AUDIT entry
+---
+name: mindforge:pr-review
+description: Run the AI PR review engine on a pull request diff
+argument-hint: [--diff path] [--sha base..head] [--output github|json|markdown]
+allowed-tools:
+  - run_command
+  - view_file
+  - write_to_file
+---
+
+<objective>
+Automate the review of pull request diffs using an AI engine, providing structured feedback in various formats (GitHub, JSON, Markdown) tailored to the type of changes made.
+</objective>
+
+<execution_context>
+.claude/commands/mindforge/pr-review.md
+</execution_context>
+
+<context>
+Source: Diff file, SHA range, or staged changes.
+Knowledge: PROJECT.md, ARCHITECTURE.md, CONVENTIONS.md, SECURITY.md.
+Environment: Requires ANTHROPIC_API_KEY for external model calls.
+</context>
+
+<process>
+1. **Determine Source**: Extract the diff from the provided path, SHA range, or git state.
+2. **Load Context**: Gather project-level documentation and relevant ADRs.
+3. **Select Template**: Detect change type (Auth, DB, API) and select the corresponding review template.
+4. **Execute Review**: Invoke the Claude API with the built system/review prompts.
+5. **Format Output**: Generate the report according to the `--output` flag (GitHub-flavoured MD, JSON, or standard MD).
+6. **Finalize**: Write to the specified destination (CI /tmp/ or interactive console) and log the event.
+</process>

package/.claude/commands/mindforge/profile-team.md

@@ -1,23 +1,30 @@
-# MindForge — Profile Team Command
-# Usage: /mindforge:profile-team [--refresh] [--developer email] [--questionnaire]
+---
+name: mindforge:profile-team
+description: Generate and maintain team/developer profiles for response personalization
+argument-hint: [--refresh] [--developer email] [--questionnaire]
+allowed-tools:
+  - view_file
+  - write_to_file
+  - run_command
+---
 
-Generate and maintain team/developer profiles for response personalization.
+<objective>
+Enhance agent collaboration by building profiles of individual developers and the team as a whole, tailoring guidance and responses based on observed patterns and declared preferences.
+</objective>
 
-## Data sources
-1. Declared questionnaire preferences
-2. Inferred patterns from AUDIT + git history + metrics
-3. Defaults from org conventions
+<execution_context>
+.claude/commands/mindforge/profile-team.md
+</execution_context>
 
-## Outputs
-- `.mindforge/team/TEAM-PROFILE.md`
-- `.mindforge/team/profiles/PROFILE-[dev-id].md`
+<context>
+Sources: AUDIT logs, git history, metrics, and interactive questionnaires.
+Storage: .mindforge/team/profiles/
+</context>
 
-## Modes
-- `--refresh`: inference-only update
-- `--developer`: target one developer profile
-- `--questionnaire`: prompt preference questions before writing
-
-## AUDIT
-```json
-{ "event": "team_profile_updated", "developers_profiled": 1, "method": "inferred" }
-```
+<process>
+1. **Data Harvest**: Analyze recent commits and audit logs to infer developer style and expertise.
+2. **Preference Intake**: If `--questionnaire` is set, ask preference questions about verbosity, explanation depth, and review style.
+3. **Synthesis**: Update the `.mindforge/team/TEAM-PROFILE.md` and individual developer profile files.
+4. **Refresh**: Run periodic updates to account for shifting team dynamics or new members.
+5. **Audit**: Log `team_profile_updated` with developer counts.
+</process>