mindforge-cc 2.0.0 → 2.1.0

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

@@ -0,0 +1,32 @@
+---
+name: mindforge:add-backlog
+description: Capture ideas in a "parking lot" to keep them out of the active phase sequence
+argument-hint: <description>
+allowed-tools:
+  - view_file
+  - write_to_file
+  - replace_file_content
+  - multi_replace_file_content
+---
+
+<objective>
+Capture an idea, task, or feature request in a "parking lot" section of the ROADMAP.md to prevent it from cluttering the active development phases.
+</objective>
+
+<execution_context>
+.claude/commands/mindforge/add-backlog.md
+</execution_context>
+
+<context>
+Arguments: $ARGUMENTS (The description of the backlog item)
+Target File: ROADMAP.md
+State: Uses 999.x numbering scheme for backlog items.
+</context>
+
+<process>
+1. **Read ROADMAP.md**: Locate the `## Backlog` or `## Future Milestones` section.
+2. **Initialize if missing**: If no backlog section exists, create `## Backlog` at the end of the file.
+3. **Determine numbering**: Find the last `999.x` item. If none, start with `999.1`.
+4. **Append item**: Add the new backlog item with the determined number and the provided description.
+5. **Confirm**: Notify the user that the item has been parked in the backlog.
+</process>

package/.agent/mindforge/agent.md

@@ -0,0 +1,31 @@
+---
+name: mindforge:agent
+description: Spawn or invoke a specialized enterprise persona from the MindForge library
+argument-hint: "[persona-name] [prompt]"
+allowed-tools:
+  - list_dir
+  - view_file
+---
+
+<objective>
+Provide an on-demand mechanism to "spawn" any of the 13+ standardized MindForge personas. This allows the user to switch the AI assistant's context, role, and process to a specific specialized mode (e.g., Roadmapper, Security Reviewer, Analyst).
+</objective>
+
+<execution_context>
+.claude/commands/mindforge/agent.md
+</execution_context>
+
+<context>
+Personas Directory: `.mindforge/personas/`
+State: Loads the persona's XML-tagged structure into the active system context.
+</context>
+
+<process>
+1. **List Personas**: If no arguments are provided, list all available `.md` files in `.mindforge/personas/` with their name and description (parsed from YAML).
+2. **Load Persona**: If a name is provided:
+    - Locate `.mindforge/personas/[name].md`.
+    - Read the file content.
+    - Present the persona's role and success criteria to the user.
+3. **Switch Mode**: Instruct the AI (through the current session context) to adopt the role, philosophy, and process defined in the loaded file.
+4. **Initial Task**: If a prompt is provided as the second argument, immediately execute that prompt using the newly adopted persona.
+</process>

package/.agent/mindforge/do.md

@@ -0,0 +1,31 @@
+---
+name: mindforge:do
+description: Smart natural language dispatcher to route intent to the right MindForge command
+argument-hint: <text>
+allowed-tools:
+  - list_dir
+  - view_file
+---
+
+<objective>
+Provide a high-level, natural language interface for users to interact with MindForge without needing to remember specific command names. Routes user intent to the most appropriate internal command.
+</objective>
+
+<execution_context>
+.claude/commands/mindforge/do.md
+</execution_context>
+
+<context>
+Arguments: $ARGUMENTS (The user's intent in plain English)
+Knowledge: Must be aware of all available `.claude/commands/mindforge/*.md` definitions.
+</context>
+
+<process>
+1. **Analyze input**: Parse the user's natural language request.
+2. **Match command**: Compare the intent against the descriptions and objectives of all known MindForge commands.
+3. **Execute match**:
+    - If a clear match is found, immediately pivot to that command's logic.
+    - If multiple matches are possible, ask the user for clarification.
+    - If no match is found, suggest the most relevant command or offer `/mindforge:help`.
+4. **Learn (Optional)**: If the user confirms a routing was correct, record the mapping for future intent resolution.
+</process>

package/.agent/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/.agent/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/.agent/mindforge/review-backlog.md

@@ -0,0 +1,34 @@
+---
+name: mindforge:review-backlog
+description: Review and promote backlog items to the active phase sequence
+argument-hint: [optional filters]
+allowed-tools:
+  - view_file
+  - write_to_file
+  - replace_file_content
+  - multi_replace_file_content
+---
+
+<objective>
+Review items currently parked in the ROADMAP.md backlog and facilitate their promotion to the active development plan.
+</objective>
+
+<execution_context>
+.claude/commands/mindforge/review-backlog.md
+</execution_context>
+
+<context>
+Target File: ROADMAP.md, STATE.md
+State: Resolves the next available phase number from STATE.md for promotion.
+</context>
+
+<process>
+1. **Read ROADMAP.md**: Extract all items under the `## Backlog` section (999.x).
+2. **Present to User**: List the backlog items and ask which one(s) should be promoted.
+3. **Determine Promotion Slot**: Read STATE.md to find the next sequential phase number.
+4. **Promote Item**:
+    - Move the item from the backlog to the active milestone list.
+    - Renumber the item to the next available phase number.
+5. **Update STATE.md**: Add the new phase to STATE.md in `unplanned` or `planned` status as appropriate.
+6. **Confirm**: Summarize the promotion to the user.
+</process>

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

@@ -0,0 +1,39 @@
+---
+name: mindforge:session-report
+description: Generate a post-session summary document capturing work performed and resource usage
+argument-hint: none
+allowed-tools:
+  - run_command
+  - view_file
+  - write_to_file
+  - list_dir
+---
+
+<objective>
+Generate a comprehensive summary of an active coding session, providing a clear trail of work for stakeholders and a diagnostic record of resource usage (tokens, time, etc.).
+</objective>
+
+<execution_context>
+.claude/commands/mindforge/session-report.md
+</execution_context>
+
+<context>
+Storage: .planning/reports/
+Data sources: Git logs, terminal history, `STATE.md`, and session memory.
+</context>
+
+<process>
+1. **Gather Data**:
+    - Get recent git commits and diff summaries.
+    - Read the current `STATE.md` for phase/plan status updates.
+    - Extract key decisions or findings from the session.
+2. **Profile Resources**:
+    - Estimate token usage if possible.
+    - Calculate session duration.
+3. **Draft Report**: Create `SESSION_REPORT_[timestamp].md` containing:
+    - Summary of Work Performed
+    - Outcomes achieved (Plans "completed")
+    - Key Decisions
+    - Resource Usage Profile
+4. **Confirm**: Notify the user and provide a link to the report.
+</process>

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

@@ -0,0 +1,34 @@
+---
+name: mindforge:ui-phase
+description: Generate a UI Design Contract (UI-SPEC.md) for the current phase
+argument-hint: [N]
+allowed-tools:
+  - view_file
+  - write_to_file
+  - list_dir
+---
+
+<objective>
+Generate a detailed UI design contract (UI-SPEC.md) for a frontend development phase to ensure consistent spacing, typography, color palettes, and accessibility standards before implementation.
+</objective>
+
+<execution_context>
+.claude/commands/mindforge/ui-phase.md
+</execution_context>
+
+<context>
+Arguments: $ARGUMENTS (The phase number [N], optional)
+Configuration: MINDFORGE.md `UI_PHASE_ACCESSIBILITY_STANDARD`
+State: Resolves the phase from STATE.md if N is not provided.
+</context>
+
+<process>
+1. **Identify Phase**: Get the current or targeted phase number.
+2. **Read Inputs**: Read `REQUIREMENTS.md` and `DESIGN_SYSTEM.md`.
+3. **Generate UI-SPEC.md**:
+    - Define component-level spacing and layout for the phase.
+    - Specify required colors and typography from the design system.
+    - List accessibility requirements (WCAG level).
+4. **Finalize**: Write `UI-SPEC.md` to the phase's planning directory or the root `.planning/`.
+5. **Confirm**: Provide a link to the user for review.
+</process>

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

@@ -0,0 +1,36 @@
+---
+name: mindforge:ui-review
+description: Perform a retroactive visual audit of implemented UI against the DESIGN_SYSTEM.md and UI-SPEC.md
+argument-hint: [N]
+allowed-tools:
+  - view_file
+  - write_to_file
+  - read_browser_page
+  - open_browser_url
+---
+
+<objective>
+Perform a retroactive, multi-pillar visual audit of implemented UI features against the defined Design System and UI-SPEC.md to ensure pixel-perfect fidelity and accessibility compliance.
+</objective>
+
+<execution_context>
+.claude/commands/mindforge/ui-review.md
+</execution_context>
+
+<context>
+Arguments: $ARGUMENTS (The phase number [N], optional)
+Sources: `DESIGN_SYSTEM.md`, `UI-SPEC.md`, and the live application UI.
+</context>
+
+<process>
+1. **Identify Target**: Determine the phase to review.
+2. **Audit Application**:
+    - Use the browser tool to inspect the implemented features.
+    - Compare against the `UI-SPEC.md` for spacing, colors, and layout.
+    - Audit for accessibility (ARIA labels, contrast, keyboard navigation).
+3. **Generate UI-REVIEW.md**:
+    - Grade each pillar (Layout, Color, Typography, etc.).
+    - List specific "Needs Work" items.
+    - Provide "Approved" status if all criteria are met.
+4. **Finalize**: Notify the user of the audit results.
+</process>

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

@@ -0,0 +1,31 @@
+---
+name: mindforge:validate-phase
+description: Audit the current phase for requirement coverage and test gaps
+argument-hint: [N]
+allowed-tools:
+  - view_file
+  - list_dir
+---
+
+<objective>
+Audit a completed project phase to ensure every requirement has been addressed and that corresponding automated tests have been implemented and are passing.
+</objective>
+
+<execution_context>
+.claude/commands/mindforge/validate-phase.md
+</execution_context>
+
+<context>
+Arguments: $ARGUMENTS (The phase number [N], optional)
+Knowledge: `STATE.md`, `REQUIREMENTS.md`, and the codebase test suite.
+</context>
+
+<process>
+1. **Identify Phase**: Resolve the targeted phase.
+2. **Cross-reference**:
+    - List all requirements in `REQUIREMENTS.md` marked for this phase.
+    - Verify implementation of each requirement in the code.
+    - Check for the existence of passing tests for each requirement.
+3. **Analyze Gaps**: Identify any "orphaned" requirements or features missing tests.
+4. **Report Findings**: Summarize coverage and call out specific gaps to the user.
+</process>

package/.agent/mindforge/workstreams.md

@@ -0,0 +1,35 @@
+---
+name: mindforge:workstreams
+description: Manage parallel feature tracks with isolated state
+argument-hint: [list|create|switch|status|complete]
+allowed-tools:
+  - list_dir
+  - view_file
+  - write_to_file
+  - run_command
+---
+
+<objective>
+Enable developers to work on multiple features or bugs concurrently within the same codebase without state collision. Provides isolated tracking for each "workstream".
+</objective>
+
+<execution_context>
+.claude/commands/mindforge/workstreams.md
+</execution_context>
+
+<context>
+Arguments: $ARGUMENTS (Switch subcommand)
+Storage: .planning/workstreams/
+State: Each workstream maintains its own subset of `STATE.md` or a local context file.
+</context>
+
+<process>
+1. **Route Subcommand**:
+    - `list`: Show all active and archived workstreams in `.planning/workstreams/`.
+    - `create <name>`: Initialize a new workstream directory and baseline state.
+    - `switch <name>`: Update the global pointer in `STATE.md` to the targeted workstream.
+    - `status`: Show the current active workstream and its progress.
+2. **Manage Isolation**:
+    - When switching, ensure current work is saved or stashed if necessary.
+3. **Confirm**: Success/Failure status message to user.
+</process>

package/.claude/commands/mindforge/add-backlog.md

@@ -0,0 +1,32 @@
+---
+name: mindforge:add-backlog
+description: Capture ideas in a "parking lot" to keep them out of the active phase sequence
+argument-hint: <description>
+allowed-tools:
+  - view_file
+  - write_to_file
+  - replace_file_content
+  - multi_replace_file_content
+---
+
+<objective>
+Capture an idea, task, or feature request in a "parking lot" section of the ROADMAP.md to prevent it from cluttering the active development phases.
+</objective>
+
+<execution_context>
+.claude/commands/mindforge/add-backlog.md
+</execution_context>
+
+<context>
+Arguments: $ARGUMENTS (The description of the backlog item)
+Target File: ROADMAP.md
+State: Uses 999.x numbering scheme for backlog items.
+</context>
+
+<process>
+1. **Read ROADMAP.md**: Locate the `## Backlog` or `## Future Milestones` section.
+2. **Initialize if missing**: If no backlog section exists, create `## Backlog` at the end of the file.
+3. **Determine numbering**: Find the last `999.x` item. If none, start with `999.1`.
+4. **Append item**: Add the new backlog item with the determined number and the provided description.
+5. **Confirm**: Notify the user that the item has been parked in the backlog.
+</process>

package/.claude/commands/mindforge/agent.md

@@ -0,0 +1,31 @@
+---
+name: mindforge:agent
+description: Spawn or invoke a specialized enterprise persona from the MindForge library
+argument-hint: "[persona-name] [prompt]"
+allowed-tools:
+  - list_dir
+  - view_file
+---
+
+<objective>
+Provide an on-demand mechanism to "spawn" any of the 13+ standardized MindForge personas. This allows the user to switch the AI assistant's context, role, and process to a specific specialized mode (e.g., Roadmapper, Security Reviewer, Analyst).
+</objective>
+
+<execution_context>
+.claude/commands/mindforge/agent.md
+</execution_context>
+
+<context>
+Personas Directory: `.mindforge/personas/`
+State: Loads the persona's XML-tagged structure into the active system context.
+</context>
+
+<process>
+1. **List Personas**: If no arguments are provided, list all available `.md` files in `.mindforge/personas/` with their name and description (parsed from YAML).
+2. **Load Persona**: If a name is provided:
+    - Locate `.mindforge/personas/[name].md`.
+    - Read the file content.
+    - Present the persona's role and success criteria to the user.
+3. **Switch Mode**: Instruct the AI (through the current session context) to adopt the role, philosophy, and process defined in the loaded file.
+4. **Initial Task**: If a prompt is provided as the second argument, immediately execute that prompt using the newly adopted persona.
+</process>

package/.claude/commands/mindforge/approve.md

@@ -1,18 +1,30 @@
-Process pending approvals and emergency overrides. Usage:
-`/mindforge:approve [approval-id] [--approve|--reject] [--reason "..."] [--emergency]`
+---
+name: mindforge:approve
+description: Process pending approvals and emergency overrides
+argument-hint: [approval-id] [--approve|--reject] [--reason "..."] [--emergency]
+allowed-tools:
+  - list_dir
+  - view_file
+  - write_to_file
+---
 
-## Listing approvals
-Scan `.planning/approvals/` and show only files with `status: pending` unless
- the user explicitly asks for historical records.
+<objective>
+Manage the governance layer by reviewing and confirming high-tier architectural or security changes, ensuring all sensitive operations have explicit human authorization.
+</objective>
 
-## Standard approval flow
-1. Read the approval file
-2. Confirm current identity from `git config user.email` or `$USER`
-3. Validate approver eligibility from `INTEGRATIONS-CONFIG.md`
-4. Record approval or rejection with timestamp and reason
+<execution_context>
+.claude/commands/mindforge/approve.md
+</execution_context>
 
-## Emergency overrides
-Emergency override requires the `--emergency` flag.
-Read `EMERGENCY_APPROVERS` from `INTEGRATIONS-CONFIG.md` and deny the request if
- the current identity is not listed. Document that git-config-based identity is
- a convenience layer, not a high-assurance identity proof.
+<context>
+Storage: .planning/approvals/
+Governance Config: INTEGRATIONS-CONFIG.md
+</context>
+
+<process>
+1. **List**: Scan for pending approval requests and present them to the user.
+2. **Identity Verification**: Confirm the user's identity via git config or environment.
+3. **Audit Eligibility**: Verify the user has sufficient permissions for the requested tier.
+4. **Record Verdict**: Update the approval file with status, timestamp, and the provided reason.
+5. **Emergency Override**: If `--emergency` is used, bypass standard checks if the identity matches the pre-defined emergency approver list.
+</process>

package/.claude/commands/mindforge/audit.md

@@ -1,30 +1,34 @@
-Query `.planning/AUDIT.jsonl` by phase, event, date, severity, integration, or
- agent. Usage: `/mindforge:audit [filters]`
+---
+name: mindforge:audit
+description: Query the .planning/AUDIT.jsonl log by phase, event, date, or severity
+argument-hint: [filters]
+allowed-tools:
+  - run_command
+  - view_file
+  - list_dir
+---
 
-## Supported options
-- `--phase N`
-- `--event NAME`
-- `--agent NAME`
-- `--severity LEVEL`
-- `--date YYYY-MM-DD`
-- `--summary`
-- `--verify`
-- `--export PATH`
+<objective>
+Provide a structured interface to query and validate the project's audit logs, ensuring accountability and traceability of all agent actions and system events.
+</objective>
 
-## Summary mode
-Summarise counts by event, severity, integration, and phase.
-Entries with `"phase": null` are reported as `project-level`, not dropped.
+<execution_context>
+.claude/commands/mindforge/audit.md
+</execution_context>
 
-## Verify mode
-Validate JSONL shape and chronological ordering.
-Timestamp comparison may use string comparison because ISO-8601 UTC timestamps
- with a `Z` suffix sort lexicographically.
+<context>
+Storage: .planning/AUDIT.jsonl
+Archive: .planning/audit-archive/
+Filters: --phase, --event, --agent, --severity, --date, --summary, --verify, --export
+</context>
 
-## Archive rotation
-If the active audit log exceeds 10,000 lines, rotate it into
- `.planning/audit-archive/` before continuing heavy writes. Rotation must never
- delete history; it archives then resets the active file.
-
-## Export safety
-Validate export paths stay inside the project directory. If a path traversal or
- unsafe destination is requested, export into `.planning/` instead.
+<process>
+1. **Parse Filters**: Identify the search criteria (phase, event, severity, etc.).
+2. **Execute Query**:
+    - Use `grep` or `jq` (if available via bash) to filter the JSONL file.
+    - If `--summary`: Aggregate counts by event and severity.
+    - If `--verify`: Check for JSON validity and chronological integrity.
+3. **Handle Large Logs**: If the log exceeds 10,000 lines, rotate it to the archive directory.
+4. **Export (Optional)**: If `--export` is used, write filtered results to the target path (ensuring project boundary safety).
+5. **Display**: Present the filtered log or summary to the user.
+</process>

package/.claude/commands/mindforge/auto.md

@@ -1,22 +1,33 @@
-# /mindforge:auto [Phase N]
+---
+name: mindforge:auto
+description: Start the MindForge Autonomous Execution Engine
+argument-hint: [Phase N] [--resume] [--headless] [--dry-run]
+allowed-tools:
+  - run_command
+  - list_dir
+  - view_file
+  - write_to_file
+---
 
-**Purpose**: Starts the MindForge Autonomous Execution Engine for the
-specified phase. The agent will execute all waves, handle repairs, and
-perform compliance gates without requiring human confirmation.
+<objective>
+Execute a planned phase entirely unattended, coordinating wave fulfillment, self-repair of minor failures, and compliance gating while maintaining a persistent state checkpoint.
+</objective>
 
-## Usage
-- `/mindforge:auto --phase 3` (Standard unattended mode)
-- `/mindforge:auto --resume` (Resumes from last checkpoint)
-- `/mindforge:auto --headless` (CI/CD optimized output)
-- `/mindforge:auto --dry-run` (Show the wave DAG and plan without executing)
+<execution_context>
+.claude/commands/mindforge/auto.md
+</execution_context>
 
-## Behavior
-- **Zero-Interaction**: Auto-approves Tier 1/2 changes if gates pass.
-- **Self-Repair**: Tries RETRY/DECOMPOSE before asking for help.
-- **Checkpointing**: Constant state persistence in `HANDOFF.json`.
-- **Governance**: ESCALATES on Tier 3 changes (Auth/Payment/PII).
+<context>
+Storage: HANDOFF.json checkpoints.
+Governance: Auto-approves Tier 1/2; Escalates Tier 3.
+Notifications: Requires Slack/Discord webhooks for mission-critical alerts.
+</context>
 
-## Environment Variables
-- `AUTO_MODE_TIMEOUT_MINUTES`: Default 120.
-- `AUTO_PUSH_ON_WAVE_COMPLETE`: Default false.
-- `SLACK_WEBHOOK_URL`: Required for notifications.
+<process>
+1. **Boot**: Load the specifies phase or resume from the last known checkpoint in `HANDOFF.json`.
+2. **Wave Engine**: Execute the DAG of tasks sequentially or in parallel based on dependencies.
+3. **Self-Repair**: Automatically attempt to retry or decompose tasks that encounter recoverable errors.
+4. **Gating**: Evaluate compliance gates between waves. Escalates to human for Tier 3 changes.
+5. **Persistence**: Save state after every successful tool call or task completion.
+6. **Finalize**: Shift status to "Verify Pending" once all waves are complete.
+</process>