mindforge-cc 2.0.0-alpha.9 → 2.1.0

package/.claude/commands/mindforge/qa.md

@@ -1,16 +1,31 @@
-# /mindforge:qa
+---
+name: mindforge:qa
+description: Run systematic visual QA on changed UI surfaces
+argument-hint: [--phase N] [--auto]
+allowed-tools:
+  - run_command
+  - list_dir
+  - open_browser_url
+  - view_file
+---
 
-## Usage
-`@mindforge qa [--phase N] [--auto]`
+<objective>
+Automatically identify UI regressions and visual bugs by scanning phase diffs for frontend changes, navigating to affected pages, and performing automated sanity checks.
+</objective>
 
-## Description
-Runs systematic visual QA on UI surfaces changed in the current phase.
-Analyzes git diff to find pages, navigates to them, and looks for errors.
+<execution_context>
+.claude/commands/mindforge/qa.md
+</execution_context>
 
-## Options
-- `--phase N`: Target specific phase for reporting (defaults to current).
-- `--auto`: Automatically run after successful wave execution if configured.
+<context>
+Scope: Files changed in the target phase.
+Output: QA-REPORT report and automated Playwright regression tests.
+</context>
 
-## Output
-- `QA-REPORT-[N].md`: Found bugs with screenshots.
-- `tests/regression/*.test.ts`: Playwright tests to prevent bug recurrence.
+<process>
+1. **Diff Analysis**: Identify changed pages/routes from git history.
+2. **Visual Scan**: Navigate to affected URLs using the browser tool.
+3. **Bug Hunting**: Look for console errors, hydration issues, and visual brokenness.
+4. **Reporting**: Generate a `QA-REPORT-[N].md` with screenshots of findings.
+5. **Sanitization**: Draft regression tests in `tests/regression/` to prevent recurrence.
+</process>

package/.claude/commands/mindforge/quick.md

@@ -1,135 +1,35 @@
-# MindForge — Quick Command
-# Usage: /mindforge:quick [--research] [--review] [--full]
-# For ad-hoc tasks that don't need full lifecycle management.
-
-## When to use quick vs plan-phase
-Use QUICK for:
-- Bug fixes not tied to a current phase
-- Small improvements (< 3 files, < 2 hours)
-- Dependency updates
-- Documentation corrections
-- One-off scripts or utilities
-
-Use PLAN-PHASE for:
-- Feature development
-- Anything touching more than 6 files
-- Anything requiring research before implementation
-- Anything with external dependencies or stakeholder requirements
-
-## Step 1 — Task intake
-
-Ask the user:
-"What do you want to do?"
-
-Listen to the description. If the task sounds larger than "quick" scope
-(more than 6 files, architectural change, new feature), say:
-"This sounds like more than a quick task. I recommend using /mindforge:plan-phase
- instead to ensure it's properly planned and verified. Want to proceed with quick anyway?"
-
-## Step 2 — Optional research (--research flag or user requests it)
-
-If `--research` is provided or the task involves unfamiliar libraries:
-Spawn a focused research subagent. Give it:
-- The task description
-- The current tech stack from PROJECT.md
-Ask it to: investigate the best approach, identify gotchas, recommend specific
-libraries (with versions), and write a brief research note.
-
-Report research findings to the user before proceeding.
-
-## Step 3 — Create a quick plan
-
-### Sequential quick task numbering
-Determine the next quick task number by scanning `.planning/quick/`:
-1. List directories matching `[0-9][0-9][0-9]-*`
-2. Take the max numeric prefix and add 1 (start at 001 if none exist)
-3. If a directory already exists for the chosen number, require `--force` to proceed
-
-Create `.planning/quick/[NNN]-[slug]/PLAN.md` where NNN is a sequential number
-and slug is a 2-4 word kebab-case description.
-
-Example: `.planning/quick/001-fix-login-null-check/PLAN.md`
-
-Use the standard XML plan format:
-```xml
-<task type="quick">
-  <n>[task name]</n>
-  <persona>[appropriate persona]</persona>
-  <files>[files to touch]</files>
-  <context>[relevant context]</context>
-  <action>[implementation instructions]</action>
-  <verify>[verification command]</verify>
-  <done>[definition of done]</done>
-</task>
-```
-
-Show the plan to the user. Wait for approval before executing.
-
-## Step 4 — Execute the quick plan
-
-### Security auto-trigger (mandatory)
-Before execution, scan the task description and files for security keywords:
-auth, authentication, login, password, token, JWT, session, payment, PII, upload,
-credential, secret, key.
-
-If any keyword matches: load `security-review/SKILL.md` and activate
-`security-reviewer.md` persona for the implementation. This is required even
-without the `--full` flag.
-
-1. Load persona from `.mindforge/personas/`
-2. Load any relevant skills based on task keywords
-3. Execute the plan
-4. Run `<verify>` — must pass before committing
-5. Commit: `[type](quick/[NNN]): [task name]`
-6. Write `.planning/quick/[NNN]-[slug]/SUMMARY.md`
-
-### STATE.md update policy
-Quick tasks do not change phase status. If there is no active phase, note the
-quick task completion in STATE.md under "Last completed task".
-
-## Step 5 — Optional review (--review flag)
-
-If `--review` is provided:
-Activate `code-quality.md` skill on the diff.
-Report any issues before committing.
-If BLOCKING issues found: fix before commit.
-
-## Step 6 — Optional full mode (--full flag)
-
-If `--full` is provided, additionally:
-- Run the project's full test suite (not just task-specific verify)
-- Run the type checker and linter
-- Activate `security-reviewer.md` if the task touches any security-sensitive code
-- Write an AUDIT entry for the quick task
-
-## Linting always runs
-Regardless of flags, after every quick task execution:
-1. Run the project's linter (from CONVENTIONS.md — check which linter applies)
-2. If lint errors found: fix them before committing.
-3. Linting is not part of `--full` — it is always part of quick.
-
-## Flags are composable
-```
-/mindforge:quick                     # minimal — task, plan, execute
-/mindforge:quick --research          # adds domain research step
-/mindforge:quick --review            # adds code quality review of diff
-/mindforge:quick --full              # adds full test suite + linting + security
-/mindforge:quick --research --full   # all of the above
-```
-
-## AUDIT entry for quick tasks
-```json
-{
-  "id": "uuid",
-  "timestamp": "ISO-8601",
-  "event": "quick_task_completed",
-  "agent": "mindforge-orchestrator",
-  "phase": null,
-  "session_id": "sess_abc",
-  "quick_id": "001",
-  "task_name": "Fix login null check",
-  "commit_sha": "abc1234",
-  "files_changed": ["src/auth/login.ts"],
-  "flags_used": ["--review"]
-}
-```
+---
+name: mindforge:quick
+description: Execute an ad-hoc task without full lifecycle management
+argument-hint: [--research] [--review] [--full]
+allowed-tools:
+  - run_command
+  - view_file
+  - write_to_file
+  - list_dir
+---
+
+<objective>
+Provide a lightweight workflow for small bug fixes, documentation updates, or dependency maintenance that bypasses the formal phase planning while maintaining strict security and quality guardrails.
+</objective>
+
+<execution_context>
+.claude/commands/mindforge/quick.md
+</execution_context>
+
+<context>
+Scope: < 6 files, < 2 hours of work.
+Storage: .planning/quick/[NNN]-[slug]/
+Flags: --research (add pre-analysis), --review (add quality check), --full (add comprehensive tests/linting).
+</context>
+
+<process>
+1. **Intake**: Verify the task fits within the "Quick" scope. Redirect to `/mindforge:plan-phase` if too large.
+2. **Research (Optional)**: If `--research` is set, spawn a subagent to investigate the approach and write a research note.
+3. **Plan**: Generate an XML-based task plan in the `.planning/quick/` directory with a sequential ID.
+4. **Security Check**: Automatically load `security-review/SKILL.md` if the task touches sensitive keywords (Auth, PII, Secrets).
+5. **Execute**: Implement the plan, run the specified verify command, and fix any lint errors.
+6. **Review (Optional)**: If `--review` is set, perform a code quality audit on the diff.
+7. **Finalize**: Commit the changes with the `quick/[NNN]` prefix and write a `SUMMARY.md`.
+8. **Audit**: Log `quick_task_completed` with file counts and flag usage.
+</process>

package/.claude/commands/mindforge/release.md

@@ -1,10 +1,29 @@
-# MindForge — Release Command
-# Usage: /mindforge:release [--version X.Y.Z] [--dry-run] [--checklist-only]
-# ⚠️  This command is for releasing the MindForge framework itself.
-#     For releasing your project phases, use /mindforge:ship instead.
+---
+name: mindforge:release
+description: Execute the MindForge framework release pipeline
+argument-hint: [--version X.Y.Z] [--dry-run]
+allowed-tools:
+  - run_command
+  - view_file
+  - write_to_file
+---
 
-## Purpose
-Execute the complete MindForge v1.0.0 (or any version) release pipeline.
-Intended for the MindForge core team.
+<objective>
+Coordinate the release of the MindForge framework itself (Core Team only), ensuring all readiness checks pass, changelogs are updated, and packages are correctly versioned.
+</objective>
 
-## Gate: Production Readiness Checklist
+<execution_context>
+.claude/commands/mindforge/release.md
+</execution_context>
+
+<context>
+Scope: Framework Core (not project phases).
+Gates: Production readiness checklist.
+</context>
+
+<process>
+1. **Checklist Audit**: Verify all framework readiness items (tests, docs, security) are marked [x].
+2. **Dry Run**: Preview the release artifacts and target version.
+3. **Pipeline Execution**: Bump versions, update the main CHANGELOG.md, and tag the release in git.
+4. **Finalize**: Trigger the publication to the official registry.
+</process>

package/.claude/commands/mindforge/remember.md

@@ -1,14 +1,29 @@
-# /mindforge:remember
+---
+name: mindforge:remember
+description: Manage long-term memory and knowledge graph entries
+argument-hint: [--add "content"] [--search "query"] [--promote "id"]
+allowed-tools:
+  - view_file
+  - write_to_file
+  - run_command
+---
 
-Manage the MindForge long-term memory (knowledge graph).
+<objective>
+Provide a manual interface for steering the agent's long-term memory, allowing users to add specific project knowledge, search the existing graph, and promote local learnings to global availability.
+</objective>
 
-## Usage
+<execution_context>
+.claude/commands/mindforge/remember.md
+</execution_context>
 
-- `/mindforge:remember --add "Your knowledge content"`: Manually add an entry.
-- `/mindforge:remember --search "your query"`: Search the knowledge base.
-- `/mindforge:remember --stats`: View memory statistics.
-- `/mindforge:remember --promote "id"`: Promote a project entry to global memory.
+<context>
+Storage: MindForge Knowledge Graph.
+Visibility: Project-local vs. Global memory.
+</context>
 
-## Description
-
-MindForge capture, stores, and retrieves knowledge (architectural decisions, code patterns, team preferences) across all sessions and projects. This command allows for manual management and querying of this data.
+<process>
+1. **Add**: Capture one-off decisions or constraints manually into the memory store.
+2. **Search**: Query the knowledge base across sessions to retrieve previously captured patterns.
+3. **Promote**: Elevate a specific project-level finding to "Global" status for use in future repositories.
+4. **Analyze**: Provide stats on memory usage and activation frequency.
+</process>

package/.claude/commands/mindforge/research.md

@@ -1,11 +1,29 @@
-# MindForge v2 — Research Command
-# Usage: /mindforge:research [topic] [--type general|library|codebase|compliance] [--url URL]
+---
+name: mindforge:research
+description: Perform deep technical or architectural research
+argument-hint: [topic] [--type library|codebase|compliance]
+allowed-tools:
+  - run_command
+  - read_url_content
+  - view_file
+---
 
-## Purpose
-Deep research using Gemini 1.5 Pro's 1-million-token context window.
-Incorporate local code context and remote documentation simultaneously.
+<objective>
+Leverage large-context models to ingest massive amounts of external documentation and local code simultaneously to answer complex architectural or compliance questions.
+</objective>
 
-## Capabilities
-- Ingest full library documentation.
-- Codebase-wide architectural analysis.
-- Regulatory compliance audits.
+<execution_context>
+.claude/commands/mindforge/research.md
+</execution_context>
+
+<context>
+Engine: Gemini 2.0 Pro (high token limit required).
+Analysis Areas: Library integration, codebase-wide patterns, compliance audits.
+</context>
+
+<process>
+1. **Define Scope**: Identify target documentation URLs and local source paths.
+2. **Ingest**: Read all relevant sources into the analysis model's context.
+3. **Synthesize**: Answer the user's research topic with citations to specific docs and files.
+4. **Document**: Capture key findings for possible promotion to a skill via `/mindforge:learn`.
+</process>

package/.claude/commands/mindforge/retrospective.md

@@ -1,26 +1,32 @@
-# MindForge — Retrospective Command
-# Usage: /mindforge:retrospective [phase N|milestone M] [--template agile|4ls|starfish]
+---
+name: mindforge:retrospective
+description: Facilitate a structured retrospective with metrics and insights
+argument-hint: [phase N|milestone M] [--template agile|4ls|starfish]
+allowed-tools:
+  - view_file
+  - write_to_file
+  - list_dir
+---
 
-Facilitate a structured retrospective with objective metrics + qualitative insights.
+<objective>
+Guide the project team through a structured reflection session at the end of a phase or milestone, combining quantitative delivery data with qualitative feedback to drive process improvement.
+</objective>
 
-## Workflow
-1. Gather quantitative signals (tasks, verify pass rate, findings, UAT, approvals).
-2. Run structured discussion by template.
-3. Write retrospective artifact in `.planning/phases/...` or `.planning/milestones/...`.
-4. Create follow-up tasks/tickets for action items.
-5. Update metrics with retrospective-completed event.
+<execution_context>
+.claude/commands/mindforge/retrospective.md
+</execution_context>
 
-## Step 5 — Apply learnings to MINDFORGE.md
-Ask explicitly:
-`Based on this retrospective, should we update MINDFORGE.md to improve future phases?`
+<context>
+Target: Specified Phase or Milestone.
+Data: Task stats, pass rates, UAT results, security findings.
+Knowledge: MINDFORGE.md (for potential config updates).
+</objective>
 
-If yes:
-- propose exact config changes
-- apply only after confirmation
-- commit with clear rationale
-
-Common mappings:
-- vague plans -> lower discuss threshold / enable auto-discuss
-- low verify pass rate -> lower max tasks per phase
-- rising security findings -> force-load `security-review,data-privacy`
-- frequent compaction pressure -> lower compaction threshold
+<process>
+1. **Signal Gathering**: Collect quantitative performance data for the target period.
+2. **Facilitate Discussion**: Run the interview based on the selected template (Agile, 4Ls, etc.).
+3. **Document**: Write the retrospective artifact in the phase or milestone directory.
+4. **Action Items**: Create follow-up tasks for process improvements.
+5. **Config Update**: Prompt the user to update `MINDFORGE.md` based on learnings (e.g., adjusting task limits).
+6. **Log**: Record `retrospective_completed` in metrics.
+</process>

package/.claude/commands/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/.claude/commands/mindforge/review.md

@@ -1,157 +1,37 @@
-# MindForge — Review Command
-# Usage: /mindforge:review [path|phase N|--staged|--last-commit]
-# Performs a comprehensive code review using code-quality and security skills.
-
-## Review targets
-- `/mindforge:review` (no args) → review all uncommitted changes (`git diff`)
-- `/mindforge:review --staged` → review staged changes (`git diff --cached`)
-- `/mindforge:review --last-commit` → review the last commit (`git diff HEAD~1`)
-- `/mindforge:review phase [N]` → review all commits in phase N
-- `/mindforge:review [file-path]` → review a specific file
-- `/mindforge:review [dir-path]` → review all files in a directory
-
-## Step 1 — Establish review scope
-
-Based on the target argument, build the file list to review:
-```bash
-# Uncommitted changes
-git diff --name-only
-
-# Staged changes
-git diff --cached --name-only
-
-# Last commit
-git diff HEAD~1 --name-only
-
-# Phase N (all commits between phase start and phase end tags)
-git log --oneline --name-only [phase-start-sha]..[phase-end-sha]
-```
-
-Display the file list to the user before reviewing:
-"Reviewing [N] files: [list]"
-
-## Step 2 — Load review personas and skills
-
-Activate TWO personas simultaneously for a comprehensive review:
-
-**Primary:** `code-quality.md` — structural quality, conventions, complexity
-**Secondary:** `security-reviewer.md` — security issues, data exposure, auth
-
-Load these skills:
-- `code-quality/SKILL.md` — always
-- `security-review/SKILL.md` — always
-- Contextual skills based on file types detected in the diff:
-  - `.ts`/`.tsx` → also load `api-design/SKILL.md` (if routes present)
-  - Database migration files → also load `database-patterns/SKILL.md`
-  - UI component files → also load `accessibility/SKILL.md`
-
-## Step 3 — Review each file
-
-For each file in the review scope:
-
-**Read the full file content** (not just the diff — context matters).
-**Read the diff for this file** to understand what changed.
-
-Apply ALL of the following checks:
-
-### Code quality checks
-- [ ] Functions within length limits (CONVENTIONS.md standard)
-- [ ] Cyclomatic complexity ≤ 10 (count if/else/switch/catch/ternary branches)
-- [ ] No magic numbers (named constants used instead)
-- [ ] No commented-out code
-- [ ] No `TODO` or `FIXME` left uncommitted
-- [ ] Error handling is explicit (no empty catch blocks)
-- [ ] Naming is precise and unambiguous (no `data`, `info`, `temp`)
-- [ ] Every exported function has a JSDoc/docstring
-- [ ] DRY: no logic duplicated 3+ times
-- [ ] No dead code (imports/variables defined but never used)
-
-### Convention checks (from CONVENTIONS.md)
-- [ ] File naming follows convention
-- [ ] Import order follows the defined order
-- [ ] All forbidden patterns are absent
-- [ ] Architecture boundaries respected (services don't import routes, etc.)
-
-### Security checks (from security-review SKILL)
-- [ ] No hardcoded credentials or secrets
-- [ ] User input validated at boundaries
-- [ ] SQL queries parameterised
-- [ ] Sensitive data not in logs or error messages
-- [ ] New dependencies CVE-scanned
-
-### Type safety (TypeScript projects)
-- [ ] No `any` types without justification comment
-- [ ] No `as unknown as X` casting without justification
-- [ ] All function parameters typed (no implicit any)
-- [ ] Return types explicitly declared on public functions
-
-## Step 4 — Write the review report
-
-Create `.planning/phases/[current-phase]/CODE-REVIEW-[timestamp].md`
-or `.planning/quick/review-[timestamp].md` for ad-hoc reviews:
-
-```markdown
-# Code Review Report
-**Date:** [ISO-8601]
-**Reviewer:** MindForge (code-quality + security-reviewer)
-**Scope:** [what was reviewed]
-**Files reviewed:** [N]
-
-## Summary
-[2-3 sentences: overall quality, major themes, recommendation]
-
-## Findings
-
-### 🔴 Blocking (must fix before merge)
-| # | File | Line | Issue | Recommendation |
-|---|---|---|---|---|
-| 1 | src/auth/login.ts | 47 | Parameterised query not used | Use `db.query('SELECT * FROM users WHERE id = $1', [id])` |
-
-### 🟠 Major (should fix in this PR)
-| # | File | Line | Issue | Recommendation |
-|---|---|---|---|---|
-| 1 | src/api/users.ts | 23 | Function is 67 lines (limit: 40) | Extract `validateUserInput` to separate function |
-
-### 🟡 Minor (fix in follow-up)
-| # | File | Line | Issue | Recommendation |
-|---|---|---|---|---|
-| 1 | src/models/order.ts | 8 | Missing JSDoc on exported function | Add `@param`, `@returns`, `@throws` |
-
-### 💡 Suggestions (optional improvements)
-| # | File | Line | Suggestion |
-|---|---|---|---|
-| 1 | src/services/email.ts | 15 | Consider memoising the template compilation |
-
-## Metrics
-- Files reviewed: [N]
-- Lines reviewed: [N]  
-- Blocking findings: [N]
-- Major findings: [N]
-- Minor findings: [N]
-- Suggestions: [N]
-
-## Verdict
-✅ APPROVED — No blocking or major findings
-⚠️  APPROVED WITH CONDITIONS — Fix [N] major findings
-❌ CHANGES REQUIRED — [N] blocking findings must be fixed
-```
-
-## Step 5 — Write AUDIT entry
-
-```json
-{
-  "event": "code_review_completed",
-  "scope": "[what was reviewed]",
-  "files_reviewed": [N],
-  "blocking_findings": [N],
-  "major_findings": [N],
-  "verdict": "approved | changes_required",
-  "report_path": ".planning/.../CODE-REVIEW-[timestamp].md"
-}
-```
-
-## Step 6 — Report to user
-
-Display a summary of findings.
-If blocking findings exist: do not allow merge.
-Tell the user: "Fix the [N] blocking issues, then run /mindforge:review again to re-check."
+---
+name: mindforge:review
+description: Perform a comprehensive code quality and security review
+argument-hint: [path|phase N|--staged|--last-commit]
+allowed-tools:
+  - run_command
+  - view_file
+  - write_to_file
+  - list_dir
+---
+
+<objective>
+Conduct a deep code review of a specified target (files, directories, phases, or git SHAs), focusing on structural quality, security vulnerabilities, and adherence to project conventions.
+</objective>
+
+<execution_context>
+.claude/commands/mindforge/review.md
+</execution_context>
+
+<context>
+Target: Staged changes, last commit, specific phase, or path.
+Personas: code-quality.md, security-reviewer.md
+Skills: code-quality, security-review, accessibility (for UI), api-design (for routes), database-patterns (for migrations).
+</context>
+
+<process>
+1. **Establish Scope**: Use `git diff` or `git log` to determine the list of files needing review.
+2. **Initialize Personas**: Load the appropriate reviewer personas and skills based on file types.
+3. **Audit Implementation**: For each file, read full content and check:
+    - Code quality (complexity, naming, error handling).
+    - Conventions (from CONVENTIONS.md).
+    - Security (secrets, validation, injection).
+    - Type safety (TS specifics).
+4. **Generate Report**: Write `CODE-REVIEW-[timestamp].md` with categorized findings (Blocking, Major, Minor, Suggestion) and an overall verdict.
+5. **Update State**: Log `code_review_completed` in `AUDIT.jsonl`.
+6. **Report**: Summarize findings to the user and block merge if "Blocking" issues exist.
+</process>