mindforge-cc 2.2.0 → 2.3.5

package/.agent/workflows/mindforge:next.md

@@ -0,0 +1,108 @@
+---
+description: Auto-detect the current project state and execute the appropriate next step.
+---
+# 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:
+```

package/.agent/workflows/mindforge:note.md

@@ -0,0 +1,27 @@
+---
+description: Capture an idea, task, or issue that surfaces during a session as a quick note for later
+---
+<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/workflows/mindforge:plan-phase.md

@@ -0,0 +1,128 @@
+---
+description: Plan a project phase. Usage: /mindforge:plan-phase [N]
+---
+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."

package/.agent/workflows/mindforge:plant-seed.md

@@ -0,0 +1,24 @@
+---
+description: Capture speculative ideas with triggers that surface automatically when relevant
+---
+<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/workflows/mindforge:plugins.md

@@ -0,0 +1,43 @@
+---
+description: Read PLUGINS-MANIFEST.md. Display installed plugins with version and permissions.
+---
+# MindForge — Plugins Command
+# Usage: /mindforge:plugins [list|install|uninstall|info|validate|create] [name]
+
+## list
+Read PLUGINS-MANIFEST.md. Display installed plugins with version and permissions.
+If no plugins: "No plugins installed. Find plugins: npm search mindforge-plugin"
+
+## 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
+
+## uninstall [plugin-name]
+Remove all installed components. Update PLUGINS-MANIFEST.md.
+Confirm: "This will remove [N] commands, [N] skills from this plugin."
+
+## 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:

package/.agent/workflows/mindforge:pr-review.md

@@ -0,0 +1,44 @@
+---
+description: Run the AI PR review engine on a pull request diff.
+---
+# 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

package/.agent/workflows/mindforge:profile-team.md

@@ -0,0 +1,26 @@
+---
+description: Generate and maintain team/developer profiles for response personalization.
+---
+# MindForge — Profile Team Command
+# Usage: /mindforge:profile-team [--refresh] [--developer email] [--questionnaire]
+
+Generate and maintain team/developer profiles for response personalization.
+
+## Data sources
+1. Declared questionnaire preferences
+2. Inferred patterns from AUDIT + git history + metrics
+3. Defaults from org conventions
+
+## Outputs
+- `.mindforge/team/TEAM-PROFILE.md`
+- `.mindforge/team/profiles/PROFILE-[dev-id].md`
+
+## 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" }
+```

package/.agent/workflows/mindforge:publish-skill.md

@@ -0,0 +1,22 @@
+---
+description: Publish a skill to the npm registry (or private registry).
+---
+# MindForge — Publish Skill Command
+# Usage: /mindforge:publish-skill [skill-dir] [--registry URL] [--dry-run]
+
+Publish a skill to the npm registry (or private registry).
+
+Pre-publication checklist:
+1. Run full skill validation (Level 1 + 2 + 3 from skill-validator.md)
+   Fail if Level 1 or 2 fails. Warn if Level 3 fails.
+2. Verify package.json has `mindforge` field with all required sub-fields
+3. Verify CHANGELOG.md has an entry for the current version
+4. Check if version already published: `npm info [package-name]@[version]`
+   If already published: error "Version already exists. Bump the version."
+5. Run `npm pack --dry-run` to preview what will be published
+6. Confirm with user: "These files will be published: [list]. Proceed? (yes/no)"
+7. If --dry-run: stop here, show preview only
+8. Publish: `npm publish --access public`
+9. Verify: `npm info [package-name]@[version]` — confirm publication succeeded
+10. Write AUDIT: `{ "event": "skill_published", "package": "...", "version": "..." }`
+11. Report: "✅ [package-name]@[version] published to npm registry"

package/.agent/workflows/mindforge:qa.md

@@ -0,0 +1,19 @@
+---
+description: @mindforge qa [--phase N] [--auto]
+---
+# /mindforge:qa
+
+## Usage
+`@mindforge qa [--phase N] [--auto]`
+
+## 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.
+
+## Options
+- `--phase N`: Target specific phase for reporting (defaults to current).
+- `--auto`: Automatically run after successful wave execution if configured.
+
+## Output
+- `QA-REPORT-[N].md`: Found bugs with screenshots.
+- `tests/regression/*.test.ts`: Playwright tests to prevent bug recurrence.

package/.agent/workflows/mindforge:quick.md

@@ -0,0 +1,138 @@
+---
+description: Use QUICK for:
+---
+# 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/.agent/workflows/mindforge:release.md

@@ -0,0 +1,13 @@
+---
+description: Execute the complete MindForge v1.0.0 (or any version) release pipeline.
+---
+# 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.
+
+## Purpose
+Execute the complete MindForge v1.0.0 (or any version) release pipeline.
+Intended for the MindForge core team.
+
+## Gate: Production Readiness Checklist

package/.agent/workflows/mindforge:remember.md

@@ -0,0 +1,29 @@
+---
+description: Manage the MindForge long-term memory (knowledge graph).
+---
+# /mindforge:remember
+
+Manage the MindForge long-term memory (knowledge graph).
+
+## Usage
+
+- 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/.agent/workflows/mindforge:research.md

@@ -0,0 +1,15 @@
+---
+description: Deep research using Gemini 1.5 Pro's 1-million-token context window.
+---
+# MindForge v2 — Research Command
+# Usage: /mindforge:research [topic] [--type general|library|codebase|compliance] [--url URL]
+
+## 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.
+
+## Capabilities
+- Ingest full library documentation via Context7.
+- Codebase-wide architectural analysis.
+- Regulatory compliance audits.
+- Real-time resolution of version-specific API contracts.

package/.agent/workflows/mindforge:retrospective.md

@@ -0,0 +1,29 @@
+---
+description: Facilitate a structured retrospective with objective metrics + qualitative insights.
+---
+# MindForge — Retrospective Command
+# Usage: /mindforge:retrospective [phase N|milestone M] [--template agile|4ls|starfish]
+
+Facilitate a structured retrospective with objective metrics + qualitative insights.
+
+## 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.
+
+## 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