mindforge-cc 2.1.1 → 2.1.2

package/docs/commands-reference.md

@@ -1,16 +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:research`        | Deep research via Context7/Gemini 1.5 Pro |
+# 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`.

package/docs/skills-authoring-guide.md

@@ -1,6 +1,7 @@
 # MindForge Skills Authoring Guide
 
 ## What is a skill?
+
 A skill is a self-contained folder containing a `SKILL.md` file that gives
 the MindForge agent domain-specific expertise for a specific type of task.
 
@@ -9,37 +10,46 @@ keywords against the task description. They inject the right knowledge at the
 right moment without cluttering the context with irrelevant information.
 
 ## When to write a skill
+
 Write a new skill when:
+
 - A specific domain requires knowledge beyond the agent's defaults
 - The same guidance needs to be applied consistently across many tasks
 - Your team has standards that aren't captured in CONVENTIONS.md
 - An existing core skill doesn't match your organisation's approach
 
 ## Automated Skill Generation (New in v2)
+
 MindForge can now generate skills automatically. Instead of writing `SKILL.md` from scratch, use the intelligent learning engine:
 
 ### 1. Learn from Documentation
+
 ```bash
 /mindforge:learn https://react.dev/learn "react-best-practices"
 ```
+
 The agent will research the URL, extract high-value engineering patterns, and generate a high-quality `SKILL.md` with examples and triggers.
 
 ### 2. Learn from Project History
+
 ```bash
 /mindforge:learn ./src/modules/auth "auth-patterns"
 ```
+
 This analyzes your codebase and session history to capture project-specific expertise.
 
 ### 3. Community Marketplace
+
 ```bash
 /mindforge:marketplace search "performance"
 /mindforge:marketplace install mindforge-skill-latency-optimizer
 ```
+
 Discover and install verified skills from the MindForge community.
 
 ## Skill file structure
 
-```
+```text
 .mindforge/skills/[skill-name]/
     SKILL.md          ← required
     examples/         ← optional: sample inputs and outputs
@@ -66,35 +76,44 @@ changelog:
 # Skill — [Human-readable skill name]
 
 ## When this skill activates
+
 [One paragraph: what task types trigger this skill, and why it helps]
 
 ## Mandatory actions when this skill is active
 
 ### Before writing any code / Before starting any task
+
 [Steps the agent MUST take before beginning — written as an ordered list]
 
 ### During [implementation / review / analysis]
+
 [Standards and patterns the agent must follow — be specific]
 
 ### After [implementation / review / analysis]
+
 [Verification steps, output requirements — be specific]
 
 ## [Domain-specific section 1]
+
 [Detailed guidance, code examples, patterns]
 
 ## [Domain-specific section 2]
+
 [Detailed guidance, code examples, patterns]
 
 ## Self-check before task completion
+
 - [ ] [Checkable item 1]
 - [ ] [Checkable item 2]
 - [ ] [Checkable item 3]
 
 ## Output
+
 [What files or artifacts this skill produces, with exact paths]
 ```
 
-## Writing good trigger keywords
+## Writing Good Trigger Keywords
+
 - Specific beats generic: `argon2` beats `hash`
 - Include common misspellings and abbreviations: `optimise, optimize`
 - Include acronyms and their expansions: `a11y, accessibility, WCAG, wcag`
@@ -102,7 +121,7 @@ changelog:
 - Aim for 10-30 triggers per skill
 - Avoid single-letter words and extremely common words (the, be, is, to)
 
-## Security notice for skill authors
+## Security Notice for Skill Authors
 
 MindForge skills are injected directly into AI agent contexts. A skill file
 with adversarial content could manipulate agent behaviour.
@@ -117,8 +136,10 @@ and Tier 3 skills — should:
 4. Restrict who can write to `.mindforge/personas/overrides/` and
    `.mindforge/org/skills/` directories
 
-## Registering your skill
+## Registering Your Skill
+
 After creating SKILL.md:
+
 ```bash
 /mindforge:skills add .mindforge/skills/[your-skill-name]
 # Choose tier: 2 (org) or 3 (project)
@@ -126,21 +147,28 @@ After creating SKILL.md:
 ```
 
 ### Quality Scoring
+
 All skills (automated or manual) are passed through the **7-Dimension Scorer**. To manually score a skill:
+
 ```bash
 /mindforge:skills validate .mindforge/skills/[your-skill]
 ```
+
 A minimum score of **60** is required for registration.
 
-## Tier guidance
+## Tier Guidance
+
+| Tier | Scope | Local Path | Description |
+| :--- | :--- | :--- | :--- |
+| **1 (Core)** | Platform | `.mindforge/skills/` | Universal engineering best practices across all stacks. |
+| **2 (Org)** | Enterprise | `.mindforge/org/skills/` | Corporate standards, security policies, and internal libraries. |
+| **3 (Project)** | Repository | `.agent/skills/` | Local project conventions, module patterns, and specific logic. |
+
+> [!NOTE]
+> Lower tiers (Project) override higher tiers (Org/Core) when skill names or triggers conflict, allowing for project-level specialization of global rules.
 
-| Tier | Use when | Location |
-|---|---|---|
-| 1 (Core) | Universal best practices — all projects | `.mindforge/skills/` |
-| 2 (Org) | Your org's standards — all projects | `.mindforge/org/skills/` or separate repo |
-| 3 (Project) | This project specifically | `.mindforge/skills/project/` |
+## Version Your Skill
 
-## Version your skill
 Every change to mandatory actions or trigger keywords = MINOR version bump.
 Every removal of triggers or outputs = MAJOR version bump.
 Typo fixes = PATCH version bump.

package/docs/tutorial.md

@@ -1,195 +1,162 @@
-# MindForge v1.0.0 — Full Tutorial (Install → Advanced Usage)
+# MindForge v2.1.1 — Full Tutorial (Install → Advanced Usage)
 
-This tutorial walks a new user from installation to advanced usage. It is
-written for engineers who want to adopt MindForge in a real codebase.
+This tutorial walks a new user from installation to advanced usage. It is written for engineers who want to adopt MindForge in a real codebase.
 
 ---
 
 ## 1. Install MindForge
 
-### Claude Code (global)
-```bash
-npx mindforge-cc@latest --claude --global
-```
-
 ### Claude Code (local, per repo)
+
 ```bash
 npx mindforge-cc@latest --claude --local
 ```
 
 ### Antigravity
+
 ```bash
-npx mindforge-cc@latest --antigravity --global
+npx mindforge-cc@latest --antigravity --local
 ```
 
----
+### Specific Runtime (Universal)
 
-## 2. Verify installation
-Open Claude Code or Antigravity in your repo and run:
+```bash
+npx mindforge-cc@latest --runtime <name>
 ```
+
+---
+
+## 2. Verify Installation
+
+Open your agentic runtime (Claude Code, Antigravity, etc.) in your repo and run:
+
+```bash
 /mindforge:health
 ```
-If anything is wrong:
-```
+
+If anything is wrong, run the repair command:
+
+```bash
 /mindforge:health --repair
 ```
 
 ---
 
-## 3. Create a new project
-```
+## 3. Create a New Project
+
+```bash
 /mindforge:init-project
 ```
-This creates:
-- `.planning/PROJECT.md`
-- `.planning/REQUIREMENTS.md`
-- `.planning/STATE.md`
-- `.planning/HANDOFF.json`
-- `.planning/AUDIT.jsonl`
 
----
+This command scaffolds the framework in `.agent/` and initializes project planning:
 
-## 4. Brownfield onboarding (existing codebase)
-```
-/mindforge:map-codebase
-```
-This generates:
-- `.planning/ARCHITECTURE.md`
-- `.mindforge/org/CONVENTIONS.md`
+- `.planning/PROJECT.md`: High-level vision and roadmap.
+- `.planning/REQUIREMENTS.md`: Functional and technical specs.
+- `.planning/STATE.md`: Real-time project health and milestone status.
 
 ---
 
-## 5. Standard workflow (Phase 1)
-```
-/mindforge:plan-phase 1
-/mindforge:execute-phase 1
-/mindforge:verify-phase 1
-/mindforge:ship 1
+## 4. Onboarding an Existing Codebase
+
+```bash
+/mindforge:map-codebase
 ```
 
-What each step does:
-- **plan**: creates atomic task plans with dependencies
-- **execute**: runs tasks in waves
-- **verify**: runs automated + human gates
-- **ship**: generates release output
+This command generates architectural insights:
+
+- `.planning/ARCHITECTURE.md`: Module relationships and data flow.
+- `.planning/CONVENTIONS.md`: Inferred coding styles and patterns.
 
 ---
 
-## 6. Using skills
-Skills load automatically by keyword triggers. You can also manage them:
-```
-/mindforge:skills list
-/mindforge:skills validate
-```
+## 5. Unified Workflow (Phase 1)
 
-Best practice: keep `ALWAYS_LOAD_SKILLS` minimal to avoid token bloat.
+MindForge uses a 4-pillar iterative cycle:
+
+```bash
+/mindforge:plan-phase 1     # discuss → research → plan
+/mindforge:execute-phase 1  # parallel execution of task plans
+/mindforge:verify-phase 1   # UAT + automated validation
+/mindforge:ship 1           # generate release output + PR
+```
 
 ---
 
-## 7. Security & governance
-MindForge enforces compliance gates by design.
+## 6. High-Performance Personas
 
-Run a deep security scan:
-```
-/mindforge:security-scan --deep --secrets --deps
-```
+MindForge v2.1.1 provides 32+ specialized personas. Each is a "digital twin" of a senior role.
 
-If Tier 3 compliance changes appear, approvals are required.
+- To list all personas: `/mindforge:personas --list`
+- To switch persona: `/mindforge:personas --set executor`
 
 ---
 
-## 8. Plugins (advanced extension)
-Plugins add commands, skills, personas, and hooks.
+## 7. Real-time Dashboard
 
-Install a plugin:
-```
-/mindforge:plugins install mindforge-plugin-<name>
-```
+Observable engineering is core to MindForge. Start the dashboard to see live agent activity:
 
-Validate installed plugins:
-```
-/mindforge:plugins validate
+```bash
+/mindforge:dashboard --start --open
 ```
 
+Visit `http://localhost:7339` for the premium web interface.
+
 ---
 
-## 9. Token usage profiling
-```
-/mindforge:tokens --profile
-/mindforge:tokens --summary
-```
+## 8. Knowledge & Memory Management
+
+MindForge records architectural decisions to prevent regression.
 
-Use this to reduce wasted tokens and improve session quality.
+- Capture a note: `/mindforge:note "Preference: Use absolute imports for shared libs"`
+- Search memory: `/mindforge:remember --search "api patterns"`
 
 ---
 
-## 10. Updates and migrations
-Check for updates:
-```
-/mindforge:update
-```
+## 9. Self-Building Skills
 
-Apply updates:
-```
-/mindforge:update --apply
-```
+Learn new capabilities from documentation URL or local files:
 
-Migrate schema:
-```
-/mindforge:migrate --from v0.6.0 --to v1.0.0
+```bash
+/mindforge:learn https://docs.nextjs.org "nextjs-best-practices"
 ```
 
 ---
 
-## 11. CI integration
-In CI, MindForge is non‑interactive by default.
+## 10. Security & Governance
 
-Set environment:
-```bash
-CI=true
-MINDFORGE_CI=true
-```
+MindForge enforces strict compliance gates.
 
-Run tests:
 ```bash
-node tests/install.test.js
+/mindforge:security-scan --deep
 ```
 
-See `docs/ci-quickstart.md` for full pipelines.
+This checks for secrets, dependency vulnerabilities, and architectural drift.
 
 ---
 
-## 12. SDK usage (advanced)
-Use the SDK in tooling or CI:
+## 11. CI/CD Integration
 
-```ts
-import { MindForgeClient } from '@mindforge/sdk';
+MindForge is designed for non-interactive execution in CI environments.
 
-const client = new MindForgeClient({ projectRoot: '.' });
-const report = await client.health();
-console.log(report);
-```
+- Set `CI=true` in your environment.
+- Use `/mindforge:ship --auto-pr` for automated delivery.
+
+See `docs/ci-cd-integration.md` for full pipeline examples.
 
 ---
 
-## 13. Best practices checklist
-- Run `/mindforge:health` after install and upgrades
-- Keep PLAN `<action>` fields lean (150–400 words)
-- Use local install per repo for isolation
-- Pin plugin versions in production workflows
-- Review `.planning/AUDIT.jsonl` for traceability
+## 12. Troubleshooting
 
----
+If you hit issues, consult these specialized guides:
 
-## 14. Troubleshooting
-If you hit issues, see:
-- `docs/troubleshooting.md`
-- `docs/faq.md`
-- `docs/upgrade.md`
+- `docs/troubleshooting.md`: Common technical fixes.
+- `docs/faq.md`: Frequent questions and architectural patterns.
+- `docs/upgrade.md`: Migration guides between versions.
 
 ---
 
-## 15. Next steps
-- Add your org defaults in `.mindforge/org/ORG.md`
-- Configure `MINDFORGE.md` for your team
-- Start Phase 2 planning
+## 13. Next Steps
+
+1. Configure your team preferences in `docs/Templates/Profile/user-profile.md`.
+2. Start your first Phase 1 planning.
+3. Join our community: `/mindforge:join-discord`.