mindforge-cc 2.1.0 → 2.1.2

package/docs/Templates/System/CONTEXT.md

@@ -0,0 +1,352 @@
+# Phase Context Template
+
+Template for `.planning/phases/XX-name/{phase_num}-CONTEXT.md` - captures implementation decisions for a phase.
+
+**Purpose:** Document decisions that downstream agents need. Researcher uses this to know WHAT to investigate. Planner uses this to know WHAT choices are locked vs flexible.
+
+**Key principle:** Categories are NOT predefined. They emerge from what was actually discussed for THIS phase. A CLI phase has CLI-relevant sections, a UI phase has UI-relevant sections.
+
+**Downstream consumers:**
+- `mindforge-phase-researcher` — Reads decisions to focus research (e.g., "card layout" → research card component patterns)
+- `mindforge-planner` — Reads decisions to create specific tasks (e.g., "infinite scroll" → task includes virtualization)
+
+---
+
+## File Template
+
+```markdown
+# Phase [X]: [Name] - Context
+
+**Gathered:** [date]
+**Status:** Ready for planning
+
+<domain>
+## Phase Boundary
+
+[Clear statement of what this phase delivers — the scope anchor. This comes from ROADMAP.md and is fixed. Discussion clarifies implementation within this boundary.]
+
+</domain>
+
+<decisions>
+## Implementation Decisions
+
+### [Area 1 that was discussed]
+- **D-01:** [Specific decision made]
+- **D-02:** [Another decision if applicable]
+
+### [Area 2 that was discussed]
+- **D-03:** [Specific decision made]
+
+### [Area 3 that was discussed]
+- **D-04:** [Specific decision made]
+
+### the agent's Discretion
+[Areas where user explicitly said "you decide" — the agent has flexibility here during planning/implementation]
+
+</decisions>
+
+<specifics>
+## Specific Ideas
+
+[Any particular references, examples, or "I want it like X" moments from discussion. Product references, specific behaviors, interaction patterns.]
+
+[If none: "No specific requirements — open to standard approaches"]
+
+</specifics>
+
+<canonical_refs>
+## Canonical References
+
+**Downstream agents MUST read these before planning or implementing.**
+
+[List every spec, ADR, feature doc, or design doc that defines requirements or constraints for this phase. Use full relative paths so agents can read them directly. Group by topic area when the phase has multiple concerns.]
+
+### [Topic area 1]
+- `path/to/spec-or-adr.md` — [What this doc decides/defines that's relevant]
+- `path/to/doc.md` §N — [Specific section and what it covers]
+
+### [Topic area 2]
+- `path/to/feature-doc.md` — [What capability this defines]
+
+[If the project has no external specs: "No external specs — requirements are fully captured in decisions above"]
+
+</canonical_refs>
+
+<code_context>
+## Existing Code Insights
+
+### Reusable Assets
+- [Component/hook/utility]: [How it could be used in this phase]
+
+### Established Patterns
+- [Pattern]: [How it constrains/enables this phase]
+
+### Integration Points
+- [Where new code connects to existing system]
+
+</code_context>
+
+<deferred>
+## Deferred Ideas
+
+[Ideas that came up during discussion but belong in other phases. Captured here so they're not lost, but explicitly out of scope for this phase.]
+
+[If none: "None — discussion stayed within phase scope"]
+
+</deferred>
+
+---
+
+*Phase: XX-name*
+*Context gathered: [date]*
+```
+
+<good_examples>
+
+**Example 1: Visual feature (Post Feed)**
+
+```markdown
+# Phase 3: Post Feed - Context
+
+**Gathered:** 2025-01-20
+**Status:** Ready for planning
+
+<domain>
+## Phase Boundary
+
+Display posts from followed users in a scrollable feed. Users can view posts and see engagement counts. Creating posts and interactions are separate phases.
+
+</domain>
+
+<decisions>
+## Implementation Decisions
+
+### Layout style
+- Card-based layout, not timeline or list
+- Each card shows: author avatar, name, timestamp, full post content, reaction counts
+- Cards have subtle shadows, rounded corners — modern feel
+
+### Loading behavior
+- Infinite scroll, not pagination
+- Pull-to-refresh on mobile
+- New posts indicator at top ("3 new posts") rather than auto-inserting
+
+### Empty state
+- Friendly illustration + "Follow people to see posts here"
+- Suggest 3-5 accounts to follow based on interests
+
+### the agent's Discretion
+- Loading skeleton design
+- Exact spacing and typography
+- Error state handling
+
+</decisions>
+
+<canonical_refs>
+## Canonical References
+
+### Feed display
+- `docs/features/social-feed.md` — Feed requirements, post card fields, engagement display rules
+- `docs/decisions/adr-012-infinite-scroll.md` — Scroll strategy decision, virtualization requirements
+
+### Empty states
+- `docs/design/empty-states.md` — Empty state patterns, illustration guidelines
+
+</canonical_refs>
+
+<specifics>
+## Specific Ideas
+
+- "I like how Twitter shows the new posts indicator without disrupting your scroll position"
+- Cards should feel like Linear's issue cards — clean, not cluttered
+
+</specifics>
+
+<deferred>
+## Deferred Ideas
+
+- Commenting on posts — Phase 5
+- Bookmarking posts — add to backlog
+
+</deferred>
+
+---
+
+*Phase: 03-post-feed*
+*Context gathered: 2025-01-20*
+```
+
+**Example 2: CLI tool (Database backup)**
+
+```markdown
+# Phase 2: Backup Command - Context
+
+**Gathered:** 2025-01-20
+**Status:** Ready for planning
+
+<domain>
+## Phase Boundary
+
+CLI command to backup database to local file or S3. Supports full and incremental backups. Restore command is a separate phase.
+
+</domain>
+
+<decisions>
+## Implementation Decisions
+
+### Output format
+- JSON for programmatic use, table format for humans
+- Default to table, --json flag for JSON
+- Verbose mode (-v) shows progress, silent by default
+
+### Flag design
+- Short flags for common options: -o (output), -v (verbose), -f (force)
+- Long flags for clarity: --incremental, --compress, --encrypt
+- Required: database connection string (positional or --db)
+
+### Error recovery
+- Retry 3 times on network failure, then fail with clear message
+- --no-retry flag to fail fast
+- Partial backups are deleted on failure (no corrupt files)
+
+### the agent's Discretion
+- Exact progress bar implementation
+- Compression algorithm choice
+- Temp file handling
+
+</decisions>
+
+<canonical_refs>
+## Canonical References
+
+### Backup CLI
+- `docs/features/backup-restore.md` — Backup requirements, supported backends, encryption spec
+- `docs/decisions/adr-007-cli-conventions.md` — Flag naming, exit codes, output format standards
+
+</canonical_refs>
+
+<specifics>
+## Specific Ideas
+
+- "I want it to feel like pg_dump — familiar to database people"
+- Should work in CI pipelines (exit codes, no interactive prompts)
+
+</specifics>
+
+<deferred>
+## Deferred Ideas
+
+- Scheduled backups — separate phase
+- Backup rotation/retention — add to backlog
+
+</deferred>
+
+---
+
+*Phase: 02-backup-command*
+*Context gathered: 2025-01-20*
+```
+
+**Example 3: Organization task (Photo library)**
+
+```markdown
+# Phase 1: Photo Organization - Context
+
+**Gathered:** 2025-01-20
+**Status:** Ready for planning
+
+<domain>
+## Phase Boundary
+
+Organize existing photo library into structured folders. Handle duplicates and apply consistent naming. Tagging and search are separate phases.
+
+</domain>
+
+<decisions>
+## Implementation Decisions
+
+### Grouping criteria
+- Primary grouping by year, then by month
+- Events detected by time clustering (photos within 2 hours = same event)
+- Event folders named by date + location if available
+
+### Duplicate handling
+- Keep highest resolution version
+- Move duplicates to _duplicates folder (don't delete)
+- Log all duplicate decisions for review
+
+### Naming convention
+- Format: YYYY-MM-DD_HH-MM-SS_originalname.ext
+- Preserve original filename as suffix for searchability
+- Handle name collisions with incrementing suffix
+
+### the agent's Discretion
+- Exact clustering algorithm
+- How to handle photos with no EXIF data
+- Folder emoji usage
+
+</decisions>
+
+<canonical_refs>
+## Canonical References
+
+### Organization rules
+- `docs/features/photo-organization.md` — Grouping rules, duplicate policy, naming spec
+- `docs/decisions/adr-003-exif-handling.md` — EXIF extraction strategy, fallback for missing metadata
+
+</canonical_refs>
+
+<specifics>
+## Specific Ideas
+
+- "I want to be able to find photos by roughly when they were taken"
+- Don't delete anything — worst case, move to a review folder
+
+</specifics>
+
+<deferred>
+## Deferred Ideas
+
+- Face detection grouping — future phase
+- Cloud sync — out of scope for now
+
+</deferred>
+
+---
+
+*Phase: 01-photo-organization*
+*Context gathered: 2025-01-20*
+```
+
+</good_examples>
+
+<guidelines>
+**This template captures DECISIONS for downstream agents.**
+
+The output should answer: "What does the researcher need to investigate? What choices are locked for the planner?"
+
+**Good content (concrete decisions):**
+- "Card-based layout, not timeline"
+- "Retry 3 times on network failure, then fail"
+- "Group by year, then by month"
+- "JSON for programmatic use, table for humans"
+
+**Bad content (too vague):**
+- "Should feel modern and clean"
+- "Good user experience"
+- "Fast and responsive"
+- "Easy to use"
+
+**After creation:**
+- File lives in phase directory: `.planning/phases/XX-name/{phase_num}-CONTEXT.md`
+- `mindforge-phase-researcher` uses decisions to focus investigation AND reads canonical_refs to know WHAT docs to study
+- `mindforge-planner` uses decisions + research to create executable tasks AND reads canonical_refs to verify alignment
+- Downstream agents should NOT need to ask the user again about captured decisions
+
+**CRITICAL — Canonical references:**
+- The `<canonical_refs>` section is MANDATORY. Every CONTEXT.md must have one.
+- If your project has external specs, ADRs, or design docs, list them with full relative paths grouped by topic
+- If ROADMAP.md lists `Canonical refs:` per phase, extract and expand those
+- Inline mentions like "see ADR-019" scattered in decisions are useless to downstream agents — they need full paths and section references in a dedicated section they can find
+- If no external specs exist, say so explicitly — don't silently omit the section
+</guidelines>

package/docs/architecture/README.md

@@ -1,44 +1,56 @@
 # MindForge Architecture Overview
 
-## Architectural style
-MindForge is a modular, file-driven framework. Behavior is defined by
-Markdown protocols and JSON schemas, with a small Node.js CLI runtime.
-
-## Core layers
-1. **Command layer** — Markdown commands in `.claude/commands/mindforge/`
-2. **Engine layer** — Execution protocols under `.mindforge/engine/`
-3. **Governance layer** — Approvals, audit, compliance gates in `.mindforge/governance/`
-4. **Intelligence Layer** — Health, difficulty, anti-patterns in `.mindforge/intelligence/`
-5. **Knowledge Layer** — Long-term memory, capture, and sync in `.mindforge/memory/`
-6. **Distribution Layer** — Installer, registry, CI, SDK, plugins
-7. **Observability Layer (v2)** — Real-time dashboard, SSE bridge, metrics aggregator
-
-## Key data artifacts
-- `.planning/PROJECT.md` — project brief
-- `.planning/STATE.md` — current execution state
-- `.planning/HANDOFF.json` — machine-readable session handoff
-- `.mindforge/memory/knowledge-base.jsonl` — local project memory
-- `.planning/AUDIT.jsonl` — append-only audit log
-
-## Runtime flow (high level)
-1. `/mindforge:plan-phase` generates atomic plans with dependencies
-2. `/mindforge:execute-phase` runs plans in waves
-3. `/mindforge:verify-phase` runs automated + human gates
-4. `/mindforge:ship` generates release artifacts and PR metadata
-5. `/mindforge:dashboard` provides real-time observability and governance
-
-## Installation targets
-- Claude Code: `~/.claude/` or `.claude/`
-- Antigravity: `~/.gemini/antigravity/` or `.agent/`
-- Cursor: `.cursor/rules/`
-- Gemini CLI: `.gemini/`
-- GitHub Copilot: `.github/copilot-instructions.md`
-- OpenCode: `.opencode/`
-
-## SDK integration
-`@mindforge/sdk` provides programmatic access to health checks, audit log
-streaming, and command builders.
-
-## Stability contract
-See ADR-020: command interfaces, schemas, and SDK exports are stable in v2.x.x.
-See ADR-041: runtime interfaces are stabilized for community extension.
+MindForge v2.1.1 is built on a unified "Agentic OS" architecture, designed to provide a consistent execution environment across all major AI IDEs and CLI tools.
+
+---
+
+## 1. Core Architectural Pillars
+
+The framework is organized into four logical pillars that map directly to the development lifecycle:
+
+1. **PLAN**: Multi-agent task decomposition using the `PLANNER_MODEL`. Resulting in atomic `.planning/` artifacts.
+2. **EXECUTE**: Parallel, wave-based implementation using the `EXECUTOR_MODEL`.
+3. **VERIFY**: Multi-stage validation (Automated Tests + UAT + Integrity Checks) using the `VERIFIER_MODEL`.
+4. **SHIP**: Release orchestration, PR generation, and audit finalization.
+
+---
+
+## 2. Directory Hierarchy
+
+MindForge uses a "Tiered Configuration" model allowing for global, organizational, and project-specific rules.
+
+| Directory | Scope | Purpose |
+| :--- | :--- | :--- |
+| `.mindforge/` | System/Global | Core personas, core skills, and engine protocols. |
+| `.mindforge/org/` | Organizational | Shared company standards and private skill registries. |
+| `.agent/` | Project/Local | Project-specific configuration, hooks, and local skill overrides. |
+| `.planning/` | Session/State | Ephemeral state, task blocks, and session handoffs. |
+
+---
+
+## 3. The Unified Registry (`file-manifest.json`)
+
+The `file-manifest.json` file in `.agent/` is the single source of truth for the framework's file system mapping. It allows MindForge to resolve command paths, skills, and templates regardless of whether it's running in Claude Code, Antigravity, or Cursor.
+
+---
+
+## 4. Runtime Execution Flow
+
+1.  **Context Loading**: Load `MINDFORGE.md` and `file-manifest.json` to configure the environment.
+2.  **Skill Discovery**: Match task intent against the 3-tier skill registry (Core → Org → Project).
+3.  **Persona Spawning**: Instantiate the required persona from the 32-persona ecosystem.
+4.  **Action Loop**: Execute the 4-pillar workflow, persisting state to `.planning/STATE.md` at every step.
+5.  **Audit Persistence**: All non-trivial actions are appended to the encrypted `.planning/AUDIT.jsonl`.
+
+---
+
+## 5. Stability & Extension
+
+MindForge provides stable interfaces for extension:
+
+- **Skills**: Domain expertise via `SKILL.md`.
+- **Workflows**: Sequence automation via `WORKFLOW.md`.
+- **Hooks**: Lifecycle interception via `.agent/hooks/`.
+- **SDK**: Programmatic access via `@mindforge/sdk`.
+
+See [ADR-041](../adr/ADR-041-runtime-interfaces.md) for the stabilization contract.

package/docs/commands-reference.md

@@ -1,15 +1,63 @@
-# MindForge — Commands Reference
-
-| Command                         | Description                                   |
-|---------------------------------|-----------------------------------------------|
-| `/mindforge:help`               | Show all commands and current project status  |
-| `/mindforge:init-project`       | Initialise a new project (requirements, scope, state) |
-| `/mindforge:plan-phase [N]`     | Plan a phase: discuss → research → create task plans |
-| `/mindforge:execute-phase [N]`  | Execute plans with wave-based parallelism     |
-| `/mindforge:verify-phase [N]`   | Human acceptance testing + automated checks  |
-| `/mindforge:ship [N]`           | Generate changelog, run quality gates, create PR |
-| `/mindforge:dashboard`           | Manage the real-time web observability dashboard |
-| `/mindforge:learn [SRC]`         | Automatically capture skills from Docs, Sessions, or npm |
-| `/mindforge:marketplace [SEARCH]`| Search, install, and publish community skills        |
-| `/mindforge:new-runtime`     | Scaffold custom runtime configurations for any AI agent |
+# MindForge v2.1.1 — Commands Reference
 
+MindForge commands are organized into functional pillars to support the entire software development lifecycle (SDLC).
+
+---
+
+## 1. Project Management & Setup
+
+| Command | Description |
+| :--- | :--- |
+| `/mindforge:init-project` | Scaffolds the `.agent/` framework and initializes project planning files. |
+| `/mindforge:map-codebase` | Performs deep architectural mapping of an existing codebase. |
+| `/mindforge:health` | Checks the integrity of the MindForge installation and project structure. |
+| `/mindforge:health --repair` | Automatically fixes missing files or broken configurations. |
+
+---
+
+## 2. The Unified Workflow (4 Pillars)
+
+| Command | Description |
+| :--- | :--- |
+| `/mindforge:plan-phase [N]` | Initiates strategic planning for a milestone: discuss → research → plan. |
+| `/mindforge:execute-phase [N]` | Starts autonomous execution of task plans in parallel waves. |
+| `/mindforge:verify-phase [N]` | Runs Human Acceptance Testing (UAT) and automated validation gates. |
+| `/mindforge:ship [N]` | Finalizes delivery, generates release output, and creates a Pull Request. |
+
+---
+
+## 3. Intelligence & Observability
+
+| Command | Description |
+| :--- | :--- |
+| `/mindforge:dashboard` | Starts or manages the real-time web observability dashboard. |
+| `/mindforge:browse [URL]` | Launches the browser daemon for visual verification or research. |
+| `/mindforge:personas --list` | Displays all 32+ specialized engineering personas. |
+| `/mindforge:personas --set ID` | Switches the current agent to a specific persona (e.g., `architect`, `executor`). |
+| `/mindforge:tokens` | Analyzes and profiles token usage for the current session. |
+
+---
+
+## 4. Knowledge, Skills & Marketplace
+
+| Command | Description |
+| :--- | :--- |
+| `/mindforge:note "TEXT"` | Captures an architectural decision or project preference into memory. |
+| `/mindforge:remember [TERM]` | Searches the MindForge knowledge graph for relevant context. |
+| `/mindforge:learn [URL/PATH]` | Ingests documentation or source code to build a new validated Skill. |
+| `/mindforge:skills --list` | Lists all active and available skills across the 3-tier registry. |
+| `/mindforge:skills validate [PATH]` | Passes a skill through the 7-Dimension Scorer for quality verification. |
+| `/mindforge:marketplace search [Q]`| Searches community skills from the central registry. |
+| `/mindforge:marketplace install ID` | Installs a verified community skill into the project context. |
+
+---
+
+## 5. Governance & Maintenance
+
+| Command | Description |
+| :--- | :--- |
+| `/mindforge:security-scan` | Performs deep vulnerability scanning and compliance checks. |
+| `/mindforge:update` | Checks for and applies framework updates from the central repository. |
+| `/mindforge:migrate` | Migrates project metadata between framework versions. |
+| `/mindforge:audit --export` | Generates a human-readable PDF report of the session audit log. |
+| `/mindforge:join-discord` | Join the MindForge developer community for support and collaboration. |

package/docs/getting-started.md

@@ -4,33 +4,41 @@ This guide gets you from zero to a working MindForge project in under five minut
 
 ## Install
 
+MindForge is typically installed as a project-local dependency to ensure environment isolation.
+
 ```bash
-# Claude Code (global)
-npx mindforge-cc --claude --global
+# Antigravity (recommended for local development)
+npx mindforge-cc@latest --antigravity --local
 
-# Project-local install
-npx mindforge-cc --claude --local
+# Claude Code (alternative)
+npx mindforge-cc@latest --claude --local
 ```
 
-## Initialise your project
+## Initialise Your Project
 
-Open Claude Code in your repository and run:
+Open your agentic runtime (Antigravity or Claude Code) in your repository and run:
 
-```
-/mindforge:help
+```bash
 /mindforge:init-project
 ```
 
-The init command creates your core planning files:
-- `.planning/PROJECT.md`
-- `.planning/REQUIREMENTS.md`
-- `.planning/STATE.md`
-- `.planning/HANDOFF.json`
+The `init-project` command scaffolds the framework in `.agent/` and creates your core planning files:
+
+- `.planning/PROJECT.md`: Your roadmap and high-level vision.
+- `.planning/REQUIREMENTS.md`: Detailed functional and technical specs.
+- `.planning/STATE.md`: Real-time tracking of project health and milestones.
+
+## The Standard Workflow
+
+MindForge operates on a high-velocity 4-pillar lifecycle:
 
-## Next steps
+1. **Plan**: `/mindforge:plan-phase 1` (Strategic planning and task breakdown)
+2. **Execute**: `/mindforge:execute-phase 1` (Autonomous execution in parallel waves)
+3. **Verify**: `/mindforge:verify-phase 1` (Automated tests + Human-in-the-loop validation)
+4. **Ship**: `/mindforge:ship 1` (Final delivery, PR generation, and release output)
 
-1. Plan Phase 1: `/mindforge:plan-phase 1`
-2. Execute Phase 1: `/mindforge:execute-phase 1`
-3. Verify Phase 1: `/mindforge:verify-phase 1`
-4. Ship Phase 1: `/mindforge:ship 1`
+## Next Steps
 
+- Explore the [User Guide](user-guide.md) for advanced features.
+- Switch to a specialized [Persona](PERSONAS.md) for target tasks.
+- Join the community: `/mindforge:join-discord`.