mindforge-cc 8.2.0 → 10.0.0

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

@@ -1,131 +0,0 @@
----
-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. `AGENTS_LEARNING.md` (MUST READ to avoid repeating past mistakes)
-2. `.planning/PROJECT.md`
-3. `.planning/REQUIREMENTS.md`
-4. `.planning/ARCHITECTURE.md`
-5. `.planning/STATE.md`
-6. `.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. Project-specific anti-patterns from `AGENTS_LEARNING.md`
-4. Relevant architectural patterns (with tradeoffs)
-5. 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/mindforge/plant-seed.md

@@ -1,31 +0,0 @@
----
-name: mindforge:plant-seed
-description: Capture speculative ideas with triggers that surface automatically when relevant
-argument-hint: <idea>
-allowed-tools:
-  - list_dir
-  - write_to_file
-  - view_file
----
-
-<objective>
-Capture speculative or long-term ideas (seeds) and store them in a way that they can be automatically resurfaced when a relevant future milestone or phase is started.
-</objective>
-
-<execution_context>
-.claude/commands/mindforge/plant-seed.md
-</execution_context>
-
-<context>
-Arguments: $ARGUMENTS (The speculative idea)
-Storage: .planning/seeds/
-Trigger mechanism: Files in this directory are checked during `init-project` or `milestone` creation.
-</context>
-
-<process>
-1. **Ensure storage**: Verify `.planning/seeds/` exists; create if not.
-2. **Generate filename**: Create a slugified filename based on the idea or a timestamp.
-3. **Write seed**: Create a markdown file with the idea, any inferred triggers (tags/keywords), and the current timestamp.
-4. **Link to system**: Add a note to the master seed index if one exists.
-5. **Confirm**: Let the user know the seed has been planted and what might trigger its resurrection.
-</process>

package/.agent/mindforge/plugins.md

@@ -1,44 +0,0 @@
----
-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/mindforge/pr-review.md

@@ -1,45 +0,0 @@
----
-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/mindforge/profile-team.md

@@ -1,27 +0,0 @@
----
-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/mindforge/publish-skill.md

@@ -1,23 +0,0 @@
----
-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/mindforge/qa.md

@@ -1,20 +0,0 @@
----
-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/mindforge/quick.md

@@ -1,139 +0,0 @@
----
-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/mindforge/record-learning.md

@@ -1,22 +0,0 @@
----
-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/.agent/mindforge/release.md

@@ -1,14 +0,0 @@
----
-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/mindforge/remember.md

@@ -1,30 +0,0 @@
----
-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/mindforge/research.md

@@ -1,16 +0,0 @@
----
-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/mindforge/retrospective.md

@@ -1,31 +0,0 @@
----
-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

@@ -1,34 +0,0 @@
----
-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>