mindforge-cc 9.0.0 → 10.0.0

package/.agent/workflows/forge:init-project.md

@@ -1,35 +0,0 @@
----
-description: Initialize a new project under the FORGE framework.
----
-Initialize a new project under the FORGE framework.
-
-Follow these steps in order:
-
-1. Ask the user these questions one at a time (wait for each answer before asking the next):
-   - What is this project? (1-2 sentence description)
-   - Who is the target user?
-   - What is the core problem it solves?
-   - What tech stack do you want to use? (or "help me decide")
-   - What is absolutely NOT in scope for v1?
-   - What does success look like at the end of v1?
-
-2. If the user said "help me decide" on tech stack, ask 3 clarifying questions then recommend a stack with brief reasoning.
-
-3. Create `.planning/PROJECT.md` with:
-   - Project name and one-line description
-   - Problem statement
-   - Target user
-   - Tech stack (with brief rationale for each choice)
-   - v1 scope (what's in)
-   - Out of scope (what's explicitly not in v1)
-   - Success criteria
-
-4. Create `.planning/STATE.md` with:
-   - Status: Project initialized
-   - Current phase: None (not started)
-   - Last action: Project initialization
-   - Next step: Run /forge:plan-phase 1
-
-5. Create `.planning/REQUIREMENTS.md` (blank template with sections)
-
-6. Tell the user: "Project initialized. Run /forge:plan-phase 1 to begin planning your first phase."

package/.agent/workflows/forge:plan-phase.md

@@ -1,33 +0,0 @@
----
-description: Plan a phase of the project. Usage: /forge:plan-phase [N]
----
-Plan a phase of the project. Usage: /forge:plan-phase [N]
-
-If N is not provided, check STATE.md for the current phase and use that.
-
-Steps:
-1. Read PROJECT.md, REQUIREMENTS.md, and STATE.md.
-2. Ask the user: "Describe what phase [N] should accomplish in 2-3 sentences."
-3. Ask: "Are there any specific implementation decisions you've already made for this phase?"
-4. Spawn a research subagent: Read the project's tech stack from PROJECT.md and research the best patterns, libraries, and pitfalls for implementing this phase. Write findings to `.planning/phases/phase-[N]/RESEARCH.md`.
-5. Create 3-6 atomic task plans in `.planning/phases/phase-[N]/`. Each PLAN file must use this XML format:
-```xml
-<plan>
-  <task>Task name</task>
-  <files>
-    specific/file/paths/to/touch.ts
-  </files>
-  <instructions>
-    Precise implementation instructions. Include:
-    - Which library to use and why (mention specific version if relevant)
-    - Any gotchas or anti-patterns to avoid
-    - The exact approach, not just "implement X"
-  </instructions>
-  <verify>Specific command or check that confirms this task is done</verify>
-  <done>One sentence definition of done for this task</done>
-</plan>
-```
-
-6. Check each plan against REQUIREMENTS.md. If a plan implements something out of scope, revise it.
-7. Update STATE.md: current phase = N, status = "Phase [N] planned, ready to execute"
-8. Tell the user: "Phase [N] has [X] task plans ready. Run /forge:execute-phase [N] to begin execution."

package/.agent/workflows/mindforge-add-phase.md

@@ -1,112 +0,0 @@
-<purpose>
-Add a new integer phase to the end of the current milestone in the roadmap. Automatically calculates next phase number, creates phase directory, and updates roadmap structure.
-</purpose>
-
-<required_reading>
-Read all files referenced by the invoking prompt's execution_context before starting.
-</required_reading>
-
-<process>
-
-<step name="parse_arguments">
-Parse the command arguments:
-- All arguments become the phase description
-- Example: `/mindforge-add-phase Add authentication` → description = "Add authentication"
-- Example: `/mindforge-add-phase Fix critical performance issues` → description = "Fix critical performance issues"
-
-If no arguments provided:
-
-```
-ERROR: Phase description required
-Usage: /mindforge-add-phase <description>
-Example: /mindforge-add-phase Add authentication system
-```
-
-Exit.
-</step>
-
-<step name="init_context">
-Load phase operation context:
-
-```bash
-INIT=$(node ".agent/bin/mindforge-tools.cjs" init phase-op "0")
-if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
-```
-
-Check `roadmap_exists` from init JSON. If false:
-```
-ERROR: No roadmap found (.planning/ROADMAP.md)
-Run /mindforge-new-project to initialize.
-```
-Exit.
-</step>
-
-<step name="add_phase">
-**Delegate the phase addition to mindforge-tools:**
-
-```bash
-RESULT=$(node ".agent/bin/mindforge-tools.cjs" phase add "${description}")
-```
-
-The CLI handles:
-- Finding the highest existing integer phase number
-- Calculating next phase number (max + 1)
-- Generating slug from description
-- Creating the phase directory (`.planning/phases/{NN}-{slug}/`)
-- Inserting the phase entry into ROADMAP.md with Goal, Depends on, and Plans sections
-
-Extract from result: `phase_number`, `padded`, `name`, `slug`, `directory`.
-</step>
-
-<step name="update_project_state">
-Update STATE.md to reflect the new phase:
-
-1. Read `.planning/STATE.md`
-2. Under "## Accumulated Context" → "### Roadmap Evolution" add entry:
-   ```
-   - Phase {N} added: {description}
-   ```
-
-If "Roadmap Evolution" section doesn't exist, create it.
-</step>
-
-<step name="completion">
-Present completion summary:
-
-```
-Phase {N} added to current milestone:
-- Description: {description}
-- Directory: .planning/phases/{phase-num}-{slug}/
-- Status: Not planned yet
-
-Roadmap updated: .planning/ROADMAP.md
-
----
-
-## ▶ Next Up
-
-**Phase {N}: {description}**
-
-`/mindforge-plan-phase {N}`
-
-<sub>`/clear` first → fresh context window</sub>
-
----
-
-**Also available:**
-- `/mindforge-add-phase <description>` — add another phase
-- Review roadmap
-
----
-```
-</step>
-
-</process>
-
-<success_criteria>
-- [ ] `mindforge-tools phase add` executed successfully
-- [ ] Phase directory created
-- [ ] Roadmap updated with new phase entry
-- [ ] STATE.md updated with roadmap evolution note
-- [ ] User informed of next steps
-</success_criteria>

package/.agent/workflows/mindforge-add-tests.md

@@ -1,351 +0,0 @@
-<purpose>
-Generate unit and E2E tests for a completed phase based on its SUMMARY.md, CONTEXT.md, and implementation. Classifies each changed file into TDD (unit), E2E (browser), or Skip categories, presents a test plan for user approval, then generates tests following RED-GREEN conventions.
-
-Users currently hand-craft `/mindforge-quick` prompts for test generation after each phase. This workflow standardizes the process with proper classification, quality gates, and gap reporting.
-</purpose>
-
-<required_reading>
-Read all files referenced by the invoking prompt's execution_context before starting.
-</required_reading>
-
-<process>
-
-<step name="parse_arguments">
-Parse `$ARGUMENTS` for:
-- Phase number (integer, decimal, or letter-suffix) → store as `$PHASE_ARG`
-- Remaining text after phase number → store as `$EXTRA_INSTRUCTIONS` (optional)
-
-Example: `/mindforge-add-tests 12 focus on edge cases` → `$PHASE_ARG=12`, `$EXTRA_INSTRUCTIONS="focus on edge cases"`
-
-If no phase argument provided:
-
-```
-ERROR: Phase number required
-Usage: /mindforge-add-tests <phase> [additional instructions]
-Example: /mindforge-add-tests 12
-Example: /mindforge-add-tests 12 focus on edge cases in the pricing module
-```
-
-Exit.
-</step>
-
-<step name="init_context">
-Load phase operation context:
-
-```bash
-INIT=$(node ".agent/bin/mindforge-tools.cjs" init phase-op "${PHASE_ARG}")
-if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
-```
-
-Extract from init JSON: `phase_dir`, `phase_number`, `phase_name`.
-
-Verify the phase directory exists. If not:
-```
-ERROR: Phase directory not found for phase ${PHASE_ARG}
-Ensure the phase exists in .planning/phases/
-```
-Exit.
-
-Read the phase artifacts (in order of priority):
-1. `${phase_dir}/*-SUMMARY.md` — what was implemented, files changed
-2. `${phase_dir}/CONTEXT.md` — acceptance criteria, decisions
-3. `${phase_dir}/*-VERIFICATION.md` — user-verified scenarios (if UAT was done)
-
-If no SUMMARY.md exists:
-```
-ERROR: No SUMMARY.md found for phase ${PHASE_ARG}
-This command works on completed phases. Run /mindforge-execute-phase first.
-```
-Exit.
-
-Present banner:
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- MindForge ► ADD TESTS — Phase ${phase_number}: ${phase_name}
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-```
-</step>
-
-<step name="analyze_implementation">
-Extract the list of files modified by the phase from SUMMARY.md ("Files Changed" or equivalent section).
-
-For each file, classify into one of three categories:
-
-| Category | Criteria | Test Type |
-|----------|----------|-----------|
-| **TDD** | Pure functions where `expect(fn(input)).toBe(output)` is writable | Unit tests |
-| **E2E** | UI behavior verifiable by browser automation | Playwright/E2E tests |
-| **Skip** | Not meaningfully testable or already covered | None |
-
-**TDD classification — apply when:**
-- Business logic: calculations, pricing, tax rules, validation
-- Data transformations: mapping, filtering, aggregation, formatting
-- Parsers: CSV, JSON, XML, custom format parsing
-- Validators: input validation, schema validation, business rules
-- State machines: status transitions, workflow steps
-- Utilities: string manipulation, date handling, number formatting
-
-**E2E classification — apply when:**
-- Keyboard shortcuts: key bindings, modifier keys, chord sequences
-- Navigation: page transitions, routing, breadcrumbs, back/forward
-- Form interactions: submit, validation errors, field focus, autocomplete
-- Selection: row selection, multi-select, shift-click ranges
-- Drag and drop: reordering, moving between containers
-- Modal dialogs: open, close, confirm, cancel
-- Data grids: sorting, filtering, inline editing, column resize
-
-**Skip classification — apply when:**
-- UI layout/styling: CSS classes, visual appearance, responsive breakpoints
-- Configuration: config files, environment variables, feature flags
-- Glue code: dependency injection setup, middleware registration, routing tables
-- Migrations: database migrations, schema changes
-- Simple CRUD: basic create/read/update/delete with no business logic
-- Type definitions: records, DTOs, interfaces with no logic
-
-Read each file to verify classification. Don't classify based on filename alone.
-</step>
-
-<step name="present_classification">
-Present the classification to the user for confirmation before proceeding:
-
-```
-AskUserQuestion(
-  header: "Test Classification",
-  question: |
-    ## Files classified for testing
-
-    ### TDD (Unit Tests) — {N} files
-    {list of files with brief reason}
-
-    ### E2E (Browser Tests) — {M} files
-    {list of files with brief reason}
-
-    ### Skip — {K} files
-    {list of files with brief reason}
-
-    {if $EXTRA_INSTRUCTIONS: "Additional instructions: ${EXTRA_INSTRUCTIONS}"}
-
-    How would you like to proceed?
-  options:
-    - "Approve and generate test plan"
-    - "Adjust classification (I'll specify changes)"
-    - "Cancel"
-)
-```
-
-If user selects "Adjust classification": apply their changes and re-present.
-If user selects "Cancel": exit gracefully.
-</step>
-
-<step name="discover_test_structure">
-Before generating the test plan, discover the project's existing test structure:
-
-```bash
-# Find existing test directories
-find . -type d -name "*test*" -o -name "*spec*" -o -name "*__tests__*" 2>/dev/null | head -20
-# Find existing test files for convention matching
-find . -type f \( -name "*.test.*" -o -name "*.spec.*" -o -name "*Tests.fs" -o -name "*Test.fs" \) 2>/dev/null | head -20
-# Check for test runners
-ls package.json *.sln 2>/dev/null
-```
-
-Identify:
-- Test directory structure (where unit tests live, where E2E tests live)
-- Naming conventions (`.test.ts`, `.spec.ts`, `*Tests.fs`, etc.)
-- Test runner commands (how to execute unit tests, how to execute E2E tests)
-- Test framework (xUnit, NUnit, Jest, Playwright, etc.)
-
-If test structure is ambiguous, ask the user:
-```
-AskUserQuestion(
-  header: "Test Structure",
-  question: "I found multiple test locations. Where should I create tests?",
-  options: [list discovered locations]
-)
-```
-</step>
-
-<step name="generate_test_plan">
-For each approved file, create a detailed test plan.
-
-**For TDD files**, plan tests following RED-GREEN-REFACTOR:
-1. Identify testable functions/methods in the file
-2. For each function: list input scenarios, expected outputs, edge cases
-3. Note: since code already exists, tests may pass immediately — that's OK, but verify they test the RIGHT behavior
-
-**For E2E files**, plan tests following RED-GREEN gates:
-1. Identify user scenarios from CONTEXT.md/VERIFICATION.md
-2. For each scenario: describe the user action, expected outcome, assertions
-3. Note: RED gate means confirming the test would fail if the feature were broken
-
-Present the complete test plan:
-
-```
-AskUserQuestion(
-  header: "Test Plan",
-  question: |
-    ## Test Generation Plan
-
-    ### Unit Tests ({N} tests across {M} files)
-    {for each file: test file path, list of test cases}
-
-    ### E2E Tests ({P} tests across {Q} files)
-    {for each file: test file path, list of test scenarios}
-
-    ### Test Commands
-    - Unit: {discovered test command}
-    - E2E: {discovered e2e command}
-
-    Ready to generate?
-  options:
-    - "Generate all"
-    - "Cherry-pick (I'll specify which)"
-    - "Adjust plan"
-)
-```
-
-If "Cherry-pick": ask user which tests to include.
-If "Adjust plan": apply changes and re-present.
-</step>
-
-<step name="execute_tdd_generation">
-For each approved TDD test:
-
-1. **Create test file** following discovered project conventions (directory, naming, imports)
-
-2. **Write test** with clear arrange/act/assert structure:
-   ```
-   // Arrange — set up inputs and expected outputs
-   // Act — call the function under test
-   // Assert — verify the output matches expectations
-   ```
-
-3. **Run the test**:
-   ```bash
-   {discovered test command}
-   ```
-
-4. **Evaluate result:**
-   - **Test passes**: Good — the implementation satisfies the test. Verify the test checks meaningful behavior (not just that it compiles).
-   - **Test fails with assertion error**: This may be a genuine bug discovered by the test. Flag it:
-     ```
-     ⚠️ Potential bug found: {test name}
-     Expected: {expected}
-     Actual: {actual}
-     File: {implementation file}
-     ```
-     Do NOT fix the implementation — this is a test-generation command, not a fix command. Record the finding.
-   - **Test fails with error (import, syntax, etc.)**: This is a test error. Fix the test and re-run.
-</step>
-
-<step name="execute_e2e_generation">
-For each approved E2E test:
-
-1. **Check for existing tests** covering the same scenario:
-   ```bash
-   grep -r "{scenario keyword}" {e2e test directory} 2>/dev/null
-   ```
-   If found, extend rather than duplicate.
-
-2. **Create test file** targeting the user scenario from CONTEXT.md/VERIFICATION.md
-
-3. **Run the E2E test**:
-   ```bash
-   {discovered e2e command}
-   ```
-
-4. **Evaluate result:**
-   - **GREEN (passes)**: Record success
-   - **RED (fails)**: Determine if it's a test issue or a genuine application bug. Flag bugs:
-     ```
-     ⚠️ E2E failure: {test name}
-     Scenario: {description}
-     Error: {error message}
-     ```
-   - **Cannot run**: Report blocker. Do NOT mark as complete.
-     ```
-     🛑 E2E blocker: {reason tests cannot run}
-     ```
-
-**No-skip rule:** If E2E tests cannot execute (missing dependencies, environment issues), report the blocker and mark the test as incomplete. Never mark success without actually running the test.
-</step>
-
-<step name="summary_and_commit">
-Create a test coverage report and present to user:
-
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- MindForge ► TEST GENERATION COMPLETE
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-## Results
-
-| Category | Generated | Passing | Failing | Blocked |
-|----------|-----------|---------|---------|---------|
-| Unit     | {N}       | {n1}    | {n2}    | {n3}    |
-| E2E      | {M}       | {m1}    | {m2}    | {m3}    |
-
-## Files Created/Modified
-{list of test files with paths}
-
-## Coverage Gaps
-{areas that couldn't be tested and why}
-
-## Bugs Discovered
-{any assertion failures that indicate implementation bugs}
-```
-
-Record test generation in project state:
-```bash
-node ".agent/bin/mindforge-tools.cjs" state-snapshot
-```
-
-If there are passing tests to commit:
-
-```bash
-git add {test files}
-git commit -m "test(phase-${phase_number}): add unit and E2E tests from add-tests command"
-```
-
-Present next steps:
-
-```
----
-
-## ▶ Next Up
-
-{if bugs discovered:}
-**Fix discovered bugs:** `/mindforge-quick fix the {N} test failures discovered in phase ${phase_number}`
-
-{if blocked tests:}
-**Resolve test blockers:** {description of what's needed}
-
-{otherwise:}
-**All tests passing!** Phase ${phase_number} is fully tested.
-
----
-
-**Also available:**
-- `/mindforge-add-tests {next_phase}` — test another phase
-- `/mindforge-verify-work {phase_number}` — run UAT verification
-
----
-```
-</step>
-
-</process>
-
-<success_criteria>
-- [ ] Phase artifacts loaded (SUMMARY.md, CONTEXT.md, optionally VERIFICATION.md)
-- [ ] All changed files classified into TDD/E2E/Skip categories
-- [ ] Classification presented to user and approved
-- [ ] Project test structure discovered (directories, conventions, runners)
-- [ ] Test plan presented to user and approved
-- [ ] TDD tests generated with arrange/act/assert structure
-- [ ] E2E tests generated targeting user scenarios
-- [ ] All tests executed — no untested tests marked as passing
-- [ ] Bugs discovered by tests flagged (not fixed)
-- [ ] Test files committed with proper message
-- [ ] Coverage gaps documented
-- [ ] Next steps presented to user
-</success_criteria>

package/.agent/workflows/mindforge-add-todo.md

@@ -1,158 +0,0 @@
-<purpose>
-Capture an idea, task, or issue that surfaces during a MindForge session as a structured todo for later work. Enables "thought → capture → continue" flow without losing context.
-</purpose>
-
-<required_reading>
-Read all files referenced by the invoking prompt's execution_context before starting.
-</required_reading>
-
-<process>
-
-<step name="init_context">
-Load todo context:
-
-```bash
-INIT=$(node ".agent/bin/mindforge-tools.cjs" init todos)
-if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
-```
-
-Extract from init JSON: `commit_docs`, `date`, `timestamp`, `todo_count`, `todos`, `pending_dir`, `todos_dir_exists`.
-
-Ensure directories exist:
-```bash
-mkdir -p .planning/todos/pending .planning/todos/done
-```
-
-Note existing areas from the todos array for consistency in infer_area step.
-</step>
-
-<step name="extract_content">
-**With arguments:** Use as the title/focus.
-- `/mindforge-add-todo Add auth token refresh` → title = "Add auth token refresh"
-
-**Without arguments:** Analyze recent conversation to extract:
-- The specific problem, idea, or task discussed
-- Relevant file paths mentioned
-- Technical details (error messages, line numbers, constraints)
-
-Formulate:
-- `title`: 3-10 word descriptive title (action verb preferred)
-- `problem`: What's wrong or why this is needed
-- `solution`: Approach hints or "TBD" if just an idea
-- `files`: Relevant paths with line numbers from conversation
-</step>
-
-<step name="infer_area">
-Infer area from file paths:
-
-| Path pattern | Area |
-|--------------|------|
-| `src/api/*`, `api/*` | `api` |
-| `src/components/*`, `src/ui/*` | `ui` |
-| `src/auth/*`, `auth/*` | `auth` |
-| `src/db/*`, `database/*` | `database` |
-| `tests/*`, `__tests__/*` | `testing` |
-| `docs/*` | `docs` |
-| `.planning/*` | `planning` |
-| `scripts/*`, `bin/*` | `tooling` |
-| No files or unclear | `general` |
-
-Use existing area from step 2 if similar match exists.
-</step>
-
-<step name="check_duplicates">
-```bash
-# Search for key words from title in existing todos
-grep -l -i "[key words from title]" .planning/todos/pending/*.md 2>/dev/null
-```
-
-If potential duplicate found:
-1. Read the existing todo
-2. Compare scope
-
-If overlapping, use AskUserQuestion:
-- header: "Duplicate?"
-- question: "Similar todo exists: [title]. What would you like to do?"
-- options:
-  - "Skip" — keep existing todo
-  - "Replace" — update existing with new context
-  - "Add anyway" — create as separate todo
-</step>
-
-<step name="create_file">
-Use values from init context: `timestamp` and `date` are already available.
-
-Generate slug for the title:
-```bash
-slug=$(node ".agent/bin/mindforge-tools.cjs" generate-slug "$title" --raw)
-```
-
-Write to `.planning/todos/pending/${date}-${slug}.md`:
-
-```markdown
----
-created: [timestamp]
-title: [title]
-area: [area]
-files:
-  - [file:lines]
----
-
-## Problem
-
-[problem description - enough context for future the agent to understand weeks later]
-
-## Solution
-
-[approach hints or "TBD"]
-```
-</step>
-
-<step name="update_state">
-If `.planning/STATE.md` exists:
-
-1. Use `todo_count` from init context (or re-run `init todos` if count changed)
-2. Update "### Pending Todos" under "## Accumulated Context"
-</step>
-
-<step name="git_commit">
-Commit the todo and any updated state:
-
-```bash
-node ".agent/bin/mindforge-tools.cjs" commit "docs: capture todo - [title]" --files .planning/todos/pending/[filename] .planning/STATE.md
-```
-
-Tool respects `commit_docs` config and gitignore automatically.
-
-Confirm: "Committed: docs: capture todo - [title]"
-</step>
-
-<step name="confirm">
-```
-Todo saved: .planning/todos/pending/[filename]
-
-  [title]
-  Area: [area]
-  Files: [count] referenced
-
----
-
-Would you like to:
-
-1. Continue with current work
-2. Add another todo
-3. View all todos (/mindforge-check-todos)
-```
-</step>
-
-</process>
-
-<success_criteria>
-- [ ] Directory structure exists
-- [ ] Todo file created with valid frontmatter
-- [ ] Problem section has enough context for future the agent
-- [ ] No duplicates (checked and resolved)
-- [ ] Area consistent with existing todos
-- [ ] STATE.md updated if exists
-- [ ] Todo and state committed to git
-</success_criteria>