mindforge-cc 2.1.0 → 2.1.2

package/docs/skills-authoring-guide.md

@@ -1,45 +1,55 @@
 # 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.
 
-Skills are loaded just-in-time: the agent discovers them by matching trigger
+Skills are loaded just-in-time: MindForge discovers them by matching trigger
 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`.