mindforge-cc 2.0.0 → 2.1.0

package/.claude/commands/mindforge/publish-skill.md

@@ -1,19 +1,30 @@
-# MindForge — Publish Skill Command
-# Usage: /mindforge:publish-skill [skill-dir] [--registry URL] [--dry-run]
+---
+name: mindforge:publish-skill
+description: Validate and publish a skill to a registry
+argument-hint: [skill-dir] [--registry URL] [--dry-run]
+allowed-tools:
+  - run_command
+  - view_file
+---
 
-Publish a skill to the npm registry (or private registry).
+<objective>
+Facilitate code reuse and community contribution by verifying, packaging, and uploading local skills to an npm or private registry after passing rigorous quality checks.
+</objective>
 
-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"
+<execution_context>
+.claude/commands/mindforge/publish-skill.md
+</execution_context>
+
+<context>
+Auditors: Level 1, 2, and 3 validation from skill-validator.md.
+Format: Standard npm package with `mindforge` fields.
+</context>
+
+<process>
+1. **Audit**: Run full multi-level validation. Fail on structural or security issues.
+2. **Metadata Check**: Ensure `package.json`, `SKILL.md`, and `CHANGELOG.md` are in sync and complete.
+3. **Preview**: Run `npm pack --dry-run` and list files for user confirmation.
+4. **Publish**: Upload the package (public by default) to the resolved registry.
+5. **Verify**: Query the registry to confirm the version is live.
+6. **Audit**: Log `skill_published` with package name and version.
+</process>

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

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

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

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

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

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

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

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

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

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

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

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

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

@@ -0,0 +1,34 @@
+---
+name: mindforge:review-backlog
+description: Review and promote backlog items to the active phase sequence
+argument-hint: [optional filters]
+allowed-tools:
+  - view_file
+  - write_to_file
+  - replace_file_content
+  - multi_replace_file_content
+---
+
+<objective>
+Review items currently parked in the ROADMAP.md backlog and facilitate their promotion to the active development plan.
+</objective>
+
+<execution_context>
+.claude/commands/mindforge/review-backlog.md
+</execution_context>
+
+<context>
+Target File: ROADMAP.md, STATE.md
+State: Resolves the next available phase number from STATE.md for promotion.
+</context>
+
+<process>
+1. **Read ROADMAP.md**: Extract all items under the `## Backlog` section (999.x).
+2. **Present to User**: List the backlog items and ask which one(s) should be promoted.
+3. **Determine Promotion Slot**: Read STATE.md to find the next sequential phase number.
+4. **Promote Item**:
+    - Move the item from the backlog to the active milestone list.
+    - Renumber the item to the next available phase number.
+5. **Update STATE.md**: Add the new phase to STATE.md in `unplanned` or `planned` status as appropriate.
+6. **Confirm**: Summarize the promotion to the user.
+</process>