mindforge-cc 6.2.0-alpha → 6.2.0

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

@@ -1,35 +1,139 @@
 ---
-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
+description: Use QUICK for:
 ---
 
-<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>
+# 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"]
+}
+```

package/.claude/commands/mindforge/record-learning.md

@@ -0,0 +1,22 @@
+---
+description: Append a new Learning Entry to the Evolution Log in AGENTS_LEARNING.md
+---
+
+# /mindforge:record-learning
+
+Append a new Learning Entry to the `Evolution Log`. Recording learnings regularly is a MANDATORY practice to build project intelligence.
+
+## Usage
+
+`/mindforge:record-learning`
+
+This command initiates a session-end recording. You should provide details on:
+- **Context**: What task was being performed.
+- **Mistake**: What went wrong.
+- **Root Cause**: Why it happened.
+- **Fix**: What was done.
+- **Prevention Rule**: Rule to avoid this in the future.
+- **Category**: (Best Practice, Anti-Pattern, Bug Fix, Architecture).
+
+## Example
+Run after a complex debugging session to capture the root cause and the specific engineering oversight to prevent it from happening again.

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

@@ -1,29 +1,14 @@
 ---
-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
+description: Execute the complete MindForge v1.0.0 (or any version) release pipeline.
 ---
 
-<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>
+# 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.
 
-<execution_context>
-.claude/commands/mindforge/release.md
-</execution_context>
+## Purpose
+Execute the complete MindForge v1.0.0 (or any version) release pipeline.
+Intended for the MindForge core team.
 
-<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>
+## Gate: Production Readiness Checklist

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

@@ -1,29 +1,30 @@
 ---
-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
+description: 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>
+# /mindforge:remember
 
-<execution_context>
-.claude/commands/mindforge/remember.md
-</execution_context>
+Manage the MindForge long-term memory (knowledge graph).
 
-<context>
-Storage: MindForge Knowledge Graph.
-Visibility: Project-local vs. Global memory.
-</context>
+## Usage
 
-<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>
+- Add an entry:
+  ```bash
+  node bin/mindforge-cli.js remember --add "Your knowledge" --topic "Title"
+  ```
+- Search memories:
+  ```bash
+  node bin/mindforge-cli.js remember --search "query" --global
+  ```
+- View statistics:
+  ```bash
+  node bin/mindforge-cli.js remember --stats
+  ```
+- Promote to global:
+  ```bash
+  node bin/mindforge-cli.js remember --promote "id"
+  ```
+
+## 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.

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

@@ -1,29 +1,16 @@
 ---
-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
+description: Deep research using Gemini 1.5 Pro's 1-million-token context window.
 ---
 
-<objective>
-Leverage large-context models to ingest massive amounts of external documentation and local code simultaneously to answer complex architectural or compliance questions.
-</objective>
+# MindForge v2 — Research Command
+# Usage: /mindforge:research [topic] [--type general|library|codebase|compliance] [--url URL]
 
-<execution_context>
-.claude/commands/mindforge/research.md
-</execution_context>
+## Purpose
+Deep research using Gemini 1.5 Pro's 1-million-token context window.
+Uses **Context7 MCP** as the primary engine for real-time documentation and code example retrieval.
 
-<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>
+## Capabilities
+- Ingest full library documentation via Context7.
+- Codebase-wide architectural analysis.
+- Regulatory compliance audits.
+- Real-time resolution of version-specific API contracts.

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

@@ -1,32 +1,31 @@
 ---
-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
+description: 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>
+# MindForge — Retrospective Command
+# Usage: /mindforge:retrospective [phase N|milestone M] [--template agile|4ls|starfish]
 
-<execution_context>
-.claude/commands/mindforge/retrospective.md
-</execution_context>
+Facilitate a structured retrospective with objective metrics + qualitative insights.
 
-<context>
-Target: Specified Phase or Milestone.
-Data: Task stats, pass rates, UAT results, security findings.
-Knowledge: MINDFORGE.md (for potential config updates).
-</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.
+6. Run `/mindforge:record-learning` to sync any new architectural "Aha!" moments or significant anti-patterns discovered during this phase/milestone.
 
-<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>
+## Step 5 — Apply learnings to MINDFORGE.md
+Ask explicitly:
+`Based on this retrospective, should we update MINDFORGE.md to improve future phases?`
+
+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

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

@@ -1,37 +1,161 @@
 ---
-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
+description: - /mindforge:review (no args) → review all uncommitted changes (git diff)
 ---
 
-<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>
+# 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."