mindforge-cc 11.3.0 → 11.3.1

package/.agent/mindforge/retro.md

@@ -0,0 +1,28 @@
+---
+description: "Facilitate sprint retrospective with pattern detection. Usage: /mindforge:retro [--format 4Ls|sailboat|timeline|starfish] [--track-patterns]"
+---
+
+<objective>
+Facilitate a structured sprint retrospective that surfaces actionable insights, ensures psychological safety, and detects recurring patterns across retrospectives to drive systemic improvement.
+</objective>
+
+<execution_context>
+@.mindforge/skills/sprint-retrospective-facilitation/SKILL.md
+</execution_context>
+
+<context>
+Arguments: $ARGUMENTS (optional --format to choose retrospective format, optional --track-patterns)
+Knowledge: Previous retro action items, sprint metrics (velocity, bugs, escaped defects), team health survey data.
+</context>
+
+<process>
+1. **Select Format**: Choose the retrospective format based on team needs. 4Ls (Liked/Learned/Lacked/Longed-for) for general use, Sailboat (wind/anchor/rocks/island) for goal-oriented, Timeline for incident-heavy sprints, Starfish (start/stop/continue/more/less) for behavioral change.
+2. **Set Psychological Safety Ground Rules**: Establish Vegas rule (what is said here stays here), no-blame language, equal airtime commitment, and facilitator neutrality. Remind team this is about the system, not individuals.
+3. **Time-Box Each Section**: Allocate strict time per section (typically 5-7 minutes for brainstorming, 3 minutes for grouping). Use silent writing first to prevent anchoring bias.
+4. **Facilitate Equal Voice**: Ensure all team members contribute. Use round-robin for quieter members, dot-voting for prioritization, and "disagree and commit" for contentious items.
+5. **Vote On Discussion Items**: Each participant gets 3 votes to identify the most impactful topics. Discuss top 3-5 voted items in depth.
+6. **Discuss Top Voted Items**: For each top item, explore root cause (5 Whys if needed), impact on the team, and potential countermeasures. Keep discussion solution-oriented.
+7. **Generate Action Items**: Produce maximum 3 action items that are SMART (Specific, Measurable, Achievable, Relevant, Time-bound). Fewer is better — completion rate drops sharply above 3.
+8. **Assign Owners**: Each action item gets a single owner (not a team) and a due date. Owner is accountable for progress update at next retro.
+9. **Check For Recurring Patterns**: Review action items from the last 3-5 retros. Flag any themes that recur (same root cause resurfacing = systemic issue needing escalation). Track pattern frequency and escalate if count > 2.
+</process>

package/.agent/mindforge/retrospective.md

@@ -0,0 +1,31 @@
+---
+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.
+6. Run `/mindforge:record-learning` to sync any new architectural "Aha!" moments or significant anti-patterns discovered during this phase/milestone.
+
+## 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/.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/review-guide.md

@@ -0,0 +1,63 @@
+---
+description: "Generate code review checklist for current PR. Usage: /mindforge:review-guide [--depth quick|standard|deep] [--focus security|perf|correctness]"
+---
+
+<objective>
+Generate a tailored code review checklist for the current PR based on scope analysis, review depth, and focus areas — defining LGTM criteria and distinguishing blocking from advisory comments.
+</objective>
+
+<execution_context>
+@.mindforge/skills/code-review-methodology/SKILL.md
+</execution_context>
+
+<context>
+Arguments: $ARGUMENTS (optional --depth quick|standard|deep, optional --focus security|perf|correctness)
+Knowledge: Current PR diff, files changed, domain context, team review standards, past review findings.
+</context>
+
+<process>
+1. **Analyze PR scope**: Understand what changed:
+   - Files changed count and total lines added/removed
+   - Domains touched (auth, payments, UI, data, infra)
+   - Type of change (feature, bugfix, refactor, config, dependency update)
+   - Risk assessment: does this touch critical paths? (auth, payments, data deletion)
+   - Blast radius: how many users/services affected if this breaks?
+   - Previous bugs in these files (git blame for recent fixes)
+
+2. **Select review depth**: Based on --depth flag or scope analysis:
+   - **Quick** (< 50 lines, config/docs): Verify correctness, check for typos, 5-minute review
+   - **Standard** (50-500 lines, feature/fix): Full checklist, test coverage, 30-minute review
+   - **Deep** (> 500 lines, architecture/security): Line-by-line analysis, threat model, 1-hour+ review
+   - Auto-escalate: any change to auth/payments/PII always gets deep review regardless of size
+
+3. **Generate checklist**: Build review items by category:
+   - **Correctness**: Does the code do what the PR description claims? Edge cases handled? Off-by-one errors? Null/undefined handling? Race conditions?
+   - **Security**: Input validation present? SQL injection possible? XSS vectors? Auth checks on new endpoints? Secrets exposed? CSRF protection?
+   - **Performance**: N+1 queries introduced? Unbounded loops? Missing indexes for new queries? Large payload without pagination? Memory leaks in event listeners?
+   - **Readability**: Clear naming? Comments where behavior is non-obvious? Functions under 50 lines? Nesting under 4 levels? Dead code removed?
+   - **Testing**: New code has tests? Edge cases tested? Mocks appropriate (not testing mocks)? Flaky test risk? Coverage meets threshold?
+   - **Architecture**: Follows established patterns? DRY (no copy-paste)? Single responsibility? Dependency direction correct? Breaking API changes versioned?
+
+4. **Define LGTM criteria**: What must be true to approve:
+   - Zero blocking findings (see below for blocking definition)
+   - All checklist items for selected depth addressed
+   - Tests pass in CI
+   - No security findings of Medium+ severity
+   - PR description accurately reflects the change
+   - Breaking changes documented and migration path provided
+
+5. **Note blocking vs suggestion comments**: Classify findings:
+   - **Blocking** (must fix): Security vulnerabilities, correctness bugs, data loss risk, missing auth check, breaking API without versioning, test failures
+   - **Suggestion** (should fix): Performance improvements, naming improvements, code organization, additional test cases, documentation gaps
+   - **Nit** (optional): Style preferences, minor rewording, alternative approaches that are equally valid
+   - Label each finding clearly: [BLOCKING], [SUGGESTION], or [NIT]
+
+6. **Output review guide**: Deliver the complete review artifact:
+   - PR summary (one paragraph: what, why, risk level)
+   - Categorized checklist tailored to this specific PR
+   - Focus areas highlighted based on --focus flag
+   - LGTM criteria specific to this PR
+   - Estimated review time
+   - Recommended reviewers (based on domain expertise in changed files)
+   - Template for review comments with severity labels
+</process>

package/.agent/mindforge/review.md

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

package/.agent/mindforge/rfc.md

@@ -0,0 +1,34 @@
+---
+description: Decompose a specification into an executable dependency DAG with parallel waves. Usage - /mindforge:rfc [spec-path] [--output DAG.json] [--worktree] [--execute]
+---
+
+<objective>
+Turn a specification document into a structured execution plan with explicit
+dependency tracking, parallel wave assignment, and optional worktree isolation.
+</objective>
+
+<execution_context>
+@.mindforge/skills/rfc-pipeline/SKILL.md
+@.mindforge/engine/dependency-parser.md
+@.mindforge/engine/wave-executor.md
+</execution_context>
+
+<context>
+$ARGUMENTS
+</context>
+
+<process>
+1. Load spec from provided path (or prompt for spec description if no path).
+2. Parse spec into atomic tasks: each must have clear [input] → [output] definition.
+3. Identify dependencies between tasks (which tasks need outputs from which other tasks).
+4. Build directed acyclic graph (DAG) from dependencies.
+5. Detect cycles — if found: ERROR with cycle description, halt.
+6. Assign tasks to waves by dependency depth (depth 0 = no deps = wave 1, etc.).
+7. Estimate effort per task (simple/medium/complex) for time projection.
+8. If --worktree: plan git worktree creation for each parallel branch.
+9. Pin each task to current HEAD commit SHA for reproducibility.
+10. Write DAG to `.planning/rfc/[name]/DAG.json` (or --output path).
+11. If --execute: write HANDOFF.json for auto-runner consumption and trigger execution.
+12. Report: total tasks, wave count, critical path length, estimated time.
+13. Log RFC decomposition in AUDIT.
+</process>

package/.agent/mindforge/santa.md

@@ -0,0 +1,33 @@
+---
+description: Run multi-angle verification by spawning 2-3 independent reviewers on current work. Usage - /mindforge:santa [scope] [--angles 2|3] [--batch-sample]
+---
+
+<objective>
+Verify current work through multiple independent reviewers with isolated context.
+Both reviewers must pass (AND gate) to approve. Eliminates author-bias.
+</objective>
+
+<execution_context>
+@.mindforge/skills/santa-method/SKILL.md
+@.mindforge/engine/verification-pipeline.md
+</execution_context>
+
+<context>
+$ARGUMENTS
+</context>
+
+<process>
+1. Parse scope from arguments (default: current uncommitted diff).
+2. Determine angle count (default: 2, max: 3 via --angles flag).
+3. Prepare isolated context for each reviewer (strip cross-references between reviewers).
+4. Define shared rubric: correctness, edge cases, security, maintainability (scored 1-5 each).
+5. Spawn Reviewer 1 with Angle A (correctness + logic focus).
+6. Spawn Reviewer 2 with Angle B (edge cases + security focus).
+7. If --angles 3: Spawn Reviewer 3 with Angle C (performance + maintainability focus).
+8. Collect independent verdicts (JSON format with pass/fail + score + findings).
+9. Apply AND gate: ALL reviewers must pass. If any fail → mark as FAILED.
+10. If disagreement (one pass, one fail): run convergence loop — narrow to specific findings, re-evaluate (max 2 rounds).
+11. If --batch-sample: select 10-15% of outputs for review (for large artifact sets).
+12. Output final verdict with per-angle scores and combined confidence.
+13. Log santa verification event in AUDIT with verdict and reviewer count.
+</process>

package/.agent/mindforge/secrets-mgmt.md

@@ -0,0 +1,31 @@
+---
+name: mindforge:secrets-mgmt
+description: "Design secrets management platform. Usage: /mindforge:secrets-mgmt [scope] [--tool vault|aws-sm|doppler] [--rotation auto|manual]"
+argument-hint: "[scope] [--tool vault|aws-sm|doppler] [--rotation auto|manual]"
+allowed-tools:
+  - list_dir
+  - view_file
+---
+
+<objective>
+Design comprehensive secrets-mgmt system architecture with best practices and production-ready patterns.
+</objective>
+
+<execution_context>
+@.mindforge/skills/secrets-platform/SKILL.md
+</execution_context>
+
+<context>
+Skills Directory: `.mindforge/skills/secrets-platform/`
+State: Analyzes requirements, constraints, and scale to generate optimized secrets-mgmt architecture.
+</context>
+
+<process>
+1. **Requirement Analysis**: Analyze domain-specific requirements, performance constraints, and scalability needs.
+2. **Architecture Design**: Design system architecture with component interaction patterns and data flow.
+3. **Technology Selection**: Evaluate and select appropriate technologies, tools, and frameworks.
+4. **Integration Strategy**: Define integration patterns with existing systems and external dependencies.
+5. **Optimization Approach**: Implement performance, cost, and resource optimization strategies.
+6. **Monitoring Framework**: Design observability, alerting, and debugging mechanisms.
+7. **Deployment Planning**: Create deployment strategy with rollback procedures and disaster recovery.
+</process>

package/.agent/mindforge/secrets.md

@@ -0,0 +1,31 @@
+---
+description: Design secrets rotation strategy with zero-downtime. Usage - /mindforge:secrets [--store vault|aws-sm|gcp-sm] [--schedule 90d] [--ephemeral]
+---
+
+<objective>
+Design a secrets management and rotation strategy that achieves zero-downtime
+credential rotation, minimizes blast radius of compromise, and provides
+auditable access trails. Covers automated rotation, dual-key periods, and
+emergency procedures.
+</objective>
+
+<execution_context>
+@.mindforge/skills/secrets-rotation/SKILL.md
+</execution_context>
+
+<context>
+$ARGUMENTS
+</context>
+
+<process>
+1. Inventory all secrets across the system: database credentials, API keys, TLS certificates, encryption keys, OAuth client secrets, webhook signing keys. Classify each by type and rotation complexity.
+2. Classify secrets by sensitivity tier: Tier 1 (critical — DB root, encryption master key, 30-day rotation), Tier 2 (standard — API keys, service accounts, 90-day rotation), Tier 3 (low — webhook secrets, 180-day rotation).
+3. Design rotation schedule based on --schedule flag and tier classification. Stagger rotations to avoid cascading changes. Account for certificate lead time (renew 30 days before expiry).
+4. Implement dual-key period for zero-downtime rotation: new key is created and distributed, both old and new keys are valid simultaneously (overlap window), old key is revoked only after all consumers confirm new key works.
+5. Configure automated rotation using the secret store's native rotation (AWS SM Lambda rotator, Vault dynamic secrets, GCP SM rotation schedules). For stores without native rotation, implement a rotation controller service.
+6. Verify zero-downtime during rotation: test that services accept both old and new credentials during overlap, test that services recover gracefully when old credential is revoked, run rotation in staging before production.
+7. Set up alerting for rotation failures: rotation lambda errors, secrets approaching expiry without rotation, services still using old credentials after overlap window, and unauthorized access attempts.
+8. Document emergency rotation procedure: steps to immediately rotate a compromised secret, blast radius assessment checklist, communication template, and post-incident review process.
+9. If --ephemeral flag is set, design short-lived credentials: Vault dynamic secrets (TTL 1h), AWS STS assume-role (session tokens), or service mesh mTLS with short-lived certs (24h). Eliminates rotation entirely.
+10. Log secrets invocation in AUDIT with: store, schedule, secret count inventoried, ephemeral mode, rotation automation coverage percentage.
+</process>