mindforge-cc 1.0.0

package/docs/skills-publishing-guide.md

@@ -0,0 +1,21 @@
+# MindForge Skills Publishing Guide
+
+## Overview
+Skills are distributed as npm packages with the `mindforge-skill-` prefix.
+
+## Required files
+- `SKILL.md`
+- `package.json` with `mindforge` metadata
+- `README.md`
+- `CHANGELOG.md`
+
+## Publish checklist
+1. Run `npx mindforge-cc validate-skill ./SKILL.md --quality`
+2. Verify `package.json` metadata is complete
+3. Ensure `CHANGELOG.md` includes the current version
+4. Run `npm pack --dry-run` to inspect files
+5. Publish with `npm publish --access public`
+
+## Private registries
+Set `MINDFORGE_SKILL_REGISTRY` in `.mindforge/org/integrations/INTEGRATIONS-CONFIG.md`
+for private registries (Verdaccio, Artifactory, GitHub Packages).

package/docs/team-setup-guide.md

@@ -0,0 +1,21 @@
+# MindForge Team Setup Guide
+
+## Step 1 — Configure approvers
+Set approvers in `.mindforge/org/integrations/INTEGRATIONS-CONFIG.md` and
+governance config.
+
+## Step 2 — Profile team
+Run:
+`/mindforge:profile-team --questionnaire`
+
+## Step 3 — Branch strategy
+Set branch strategy in `MINDFORGE.md`, for example:
+- `BRANCHING_STRATEGY=phase`
+- `PHASE_BRANCH_TEMPLATE=feat/phase-{N}-{slug}`
+
+## Step 4 — Coordinate ownership
+Use `HANDOFF.json` and plan files to avoid overlapping write scopes.
+
+## Ethics policy
+Per ADR-014 and TEAM-PROFILE policy, metrics are for process and system
+improvement only, not individual performance evaluation.

package/docs/troubleshooting.md

@@ -0,0 +1,119 @@
+# MindForge Troubleshooting (v1.0.0)
+
+This page lists common issues and fast fixes. If you get stuck, start with
+`/mindforge:health`.
+
+## 1. Install issues
+
+### Installer exits immediately
+**Symptom:** `npx mindforge-cc` returns without installing.
+**Fix:** Ensure Node.js 18+.
+```bash
+node -v
+```
+Upgrade if below 18.
+
+### Existing CLAUDE.md overwritten
+**Symptom:** Custom instructions seem missing.
+**Fix:** The installer creates a backup if the old file didn’t include MindForge.
+Look for `CLAUDE.md.backup-<timestamp>` and merge your content.
+
+### Commands not showing
+**Symptom:** `/mindforge:help` doesn’t list commands.
+**Fix:** Verify the install location:
+- Claude Code: `~/.claude/commands/mindforge/`
+- Antigravity: `~/.gemini/antigravity/mindforge/`
+Run `/mindforge:health --repair`.
+
+---
+
+## 2. Health check failures
+
+### CLAUDE.md drift detected
+**Fix:**
+```
+/mindforge:health --repair
+```
+This restores the canonical MindForge CLAUDE.md.
+
+### Missing .planning files
+**Fix:**
+```
+/mindforge:init-project
+```
+If you already have a project, run `/mindforge:map-codebase` instead.
+
+---
+
+## 3. Migration / update problems
+
+### Update available but fails to apply
+**Fix:** Retry with explicit scope:
+```bash
+npx mindforge-cc@latest --claude --local --force
+```
+Then run:
+```
+/mindforge:migrate --from v0.6.0 --to v1.0.0
+```
+
+### Schema mismatch warning on startup
+**Fix:**
+```
+/mindforge:migrate --dry-run
+/mindforge:migrate --from vX.Y.Z --to v1.0.0
+```
+
+### AUDIT.jsonl parse errors
+**Fix:** Migration preserves invalid lines. If a line is corrupt, archive it and
+rerun migration. See `.mindforge/audit/AUDIT-SCHEMA.md` for expected format.
+
+---
+
+## 4. CI mode issues
+
+### CI silently skips interactive steps
+**Expected:** In CI, MindForge runs non-interactive by design.
+**Fix:** Ensure `CI=true` is set only in CI. Locally, unset it.
+
+### CI pipeline fails on Tier 3 changes
+**Expected:** Tier 3 changes fail CI by design.
+**Fix:** Route Tier 3 changes through approvals.
+
+---
+
+## 5. Plugin issues
+
+### Plugin not loading
+**Fix:**
+- Run `/mindforge:plugins validate`
+- Check `plugin.json` for `mindforge_plugin_api_version: 1.0.0`
+- Ensure `min_mindforge_version` is <= your version
+
+### Command name conflicts
+**Expected:** Conflicting commands are renamed as `plugin-name-command`.
+**Fix:** Use the renamed command shown in output.
+
+---
+
+## 6. Token usage too high
+**Fix:**
+- Reduce file reads or limit to ranges
+- Keep PLAN `<action>` lean (150–400 words)
+- Limit full skill injections to 3
+- Use `/mindforge:tokens --profile`
+
+---
+
+## 7. Security scan failures
+**Fix:**
+- Review `.planning/phases/<N>/SECURITY-REVIEW-<N>.md`
+- Resolve CRITICAL/HIGH findings first
+- Re-run `/mindforge:security-scan --deep --secrets --deps`
+
+---
+
+## 8. Getting help
+If the above doesn’t resolve it:
+- Review `docs/user-guide.md`
+- Check `docs/security/SECURITY.md` for security issues

package/docs/tutorial.md

@@ -0,0 +1,195 @@
+# MindForge v1.0.0 — 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.
+
+---
+
+## 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
+```
+
+---
+
+## 2. Verify installation
+Open Claude Code or Antigravity in your repo and run:
+```
+/mindforge:health
+```
+If anything is wrong:
+```
+/mindforge:health --repair
+```
+
+---
+
+## 3. Create a new project
+```
+/mindforge:init-project
+```
+This creates:
+- `.planning/PROJECT.md`
+- `.planning/REQUIREMENTS.md`
+- `.planning/STATE.md`
+- `.planning/HANDOFF.json`
+- `.planning/AUDIT.jsonl`
+
+---
+
+## 4. Brownfield onboarding (existing codebase)
+```
+/mindforge:map-codebase
+```
+This generates:
+- `.planning/ARCHITECTURE.md`
+- `.mindforge/org/CONVENTIONS.md`
+
+---
+
+## 5. Standard workflow (Phase 1)
+```
+/mindforge:plan-phase 1
+/mindforge:execute-phase 1
+/mindforge:verify-phase 1
+/mindforge:ship 1
+```
+
+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
+
+---
+
+## 6. Using skills
+Skills load automatically by keyword triggers. You can also manage them:
+```
+/mindforge:skills list
+/mindforge:skills validate
+```
+
+Best practice: keep `ALWAYS_LOAD_SKILLS` minimal to avoid token bloat.
+
+---
+
+## 7. Security & governance
+MindForge enforces compliance gates by design.
+
+Run a deep security scan:
+```
+/mindforge:security-scan --deep --secrets --deps
+```
+
+If Tier 3 compliance changes appear, approvals are required.
+
+---
+
+## 8. Plugins (advanced extension)
+Plugins add commands, skills, personas, and hooks.
+
+Install a plugin:
+```
+/mindforge:plugins install mindforge-plugin-<name>
+```
+
+Validate installed plugins:
+```
+/mindforge:plugins validate
+```
+
+---
+
+## 9. Token usage profiling
+```
+/mindforge:tokens --profile
+/mindforge:tokens --summary
+```
+
+Use this to reduce wasted tokens and improve session quality.
+
+---
+
+## 10. Updates and migrations
+Check for updates:
+```
+/mindforge:update
+```
+
+Apply updates:
+```
+/mindforge:update --apply
+```
+
+Migrate schema:
+```
+/mindforge:migrate --from v0.6.0 --to v1.0.0
+```
+
+---
+
+## 11. CI integration
+In CI, MindForge is non‑interactive by default.
+
+Set environment:
+```bash
+CI=true
+MINDFORGE_CI=true
+```
+
+Run tests:
+```bash
+node tests/install.test.js
+```
+
+See `docs/ci-quickstart.md` for full pipelines.
+
+---
+
+## 12. SDK usage (advanced)
+Use the SDK in tooling or CI:
+
+```ts
+import { MindForgeClient } from '@mindforge/sdk';
+
+const client = new MindForgeClient({ projectRoot: '.' });
+const report = await client.health();
+console.log(report);
+```
+
+---
+
+## 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
+
+---
+
+## 14. Troubleshooting
+If you hit issues, see:
+- `docs/troubleshooting.md`
+- `docs/faq.md`
+- `docs/upgrade.md`
+
+---
+
+## 15. Next steps
+- Add your org defaults in `.mindforge/org/ORG.md`
+- Configure `MINDFORGE.md` for your team
+- Start Phase 2 planning

package/docs/upgrade.md

@@ -0,0 +1,44 @@
+# MindForge Upgrade Guide (v1.0.0)
+
+This guide covers upgrades from v0.6.0 to v1.0.0.
+
+## 1. Check version
+```bash
+node -e "console.log(require('./package.json').version)"
+```
+
+## 2. Update MindForge
+```
+/mindforge:update
+/mindforge:update --apply
+```
+
+If the update fails, run:
+```bash
+npx mindforge-cc@latest --claude --local --force
+```
+
+## 3. Migrate schema files
+```
+/mindforge:migrate --from v0.6.0 --to v1.0.0
+```
+
+## 4. Verify
+```
+/mindforge:health
+/mindforge:status
+```
+
+## 5. Known breaking changes
+- `VERIFY_PASS_RATE_WARNING_THRESHOLD` now uses 0.0–1.0 (was 0–100)
+- `AUDIT.jsonl` now requires `session_id` (auto-backfilled)
+- `HANDOFF.json` now requires `plugin_api_version`
+
+## 6. Rollback
+If anything goes wrong, restore the migration backup:
+```
+ls .planning/migration-backup-*
+cp .planning/migration-backup-<timestamp>/* .planning/
+```
+
+Then re-run `/mindforge:migrate --dry-run`.

package/docs/user-guide.md

@@ -0,0 +1,131 @@
+# MindForge User Guide (v1.0.0)
+
+This guide gets you from install to productive, with the minimum needed to run
+MindForge in a real project. It assumes Node.js 18+.
+
+## 1. Install
+
+### Claude Code (global)
+```bash
+npx mindforge-cc@latest --claude --global
+```
+
+### Claude Code (local, per project)
+```bash
+npx mindforge-cc@latest --claude --local
+```
+
+### Antigravity
+```bash
+npx mindforge-cc@latest --antigravity --global
+# or
+npx mindforge-cc@latest --antigravity --local
+```
+
+### Both runtimes
+```bash
+npx mindforge-cc@latest --all --global
+```
+
+## 2. Verify installation
+Open Claude Code or Antigravity in your project directory and run:
+```
+/mindforge:health
+```
+
+If health reports issues, run:
+```
+/mindforge:health --repair
+```
+
+## 3. Initialize a new project
+```
+/mindforge:init-project
+```
+This creates the core planning artifacts in `.planning/`.
+
+## 4. Brownfield onboarding (existing codebase)
+```
+/mindforge:map-codebase
+```
+This generates `.planning/ARCHITECTURE.md` and an inferred conventions file.
+
+## 5. Standard workflow
+```
+/mindforge:plan-phase 1
+/mindforge:execute-phase 1
+/mindforge:verify-phase 1
+/mindforge:ship 1
+```
+
+## 6. Update and migration
+### Check for updates
+```
+/mindforge:update
+```
+
+### Apply updates
+```
+/mindforge:update --apply
+```
+
+### Run schema migrations manually
+```
+/mindforge:migrate --from v0.6.0 --to v1.0.0
+```
+
+## 7. Plugins
+### List / validate
+```
+/mindforge:plugins list
+/mindforge:plugins validate
+```
+
+### Install
+```
+/mindforge:plugins install mindforge-plugin-<name>
+```
+
+## 8. Skills
+```
+/mindforge:skills list
+/mindforge:skills validate
+```
+
+To publish or install a skill, see `docs/skills-publishing-guide.md`.
+
+## 9. Token usage profiling
+```
+/mindforge:tokens --profile
+/mindforge:tokens --summary
+```
+
+Token optimization policies are defined in:
+- `.mindforge/production/token-optimiser.md`
+
+## 10. Configuration (MINDFORGE.md)
+Key settings live in `MINDFORGE.md`. See:
+- `docs/reference/config-reference.md`
+
+Common settings:
+- `PLANNER_MODEL`, `EXECUTOR_MODEL`, `REVIEWER_MODEL`
+- `VERIFY_PASS_RATE_WARNING_THRESHOLD`
+- `TOKEN_WARN_THRESHOLD`, `TOKEN_LEAN_MODE`
+- `MINDFORGE_AUTO_CHECK_UPDATES`
+
+## 11. Troubleshooting
+- Health issues: run `/mindforge:health --repair`
+- Schema drift: run `/mindforge:migrate --dry-run` then apply
+- Installer issues: re-run with `--force`
+- CI mode: set `CI=true` and check `.mindforge/ci/` docs
+
+## 12. Security
+MindForge never stores credentials in files. See:
+- `docs/security/SECURITY.md`
+- `docs/security/threat-model.md`
+
+## 13. Reference docs
+- Commands: `docs/reference/commands.md`
+- SDK: `docs/reference/sdk-api.md`
+- Skills: `docs/reference/skills-api.md`
+- Audit events: `docs/reference/audit-events.md`