mindforge-cc 1.0.0

package/docs/reference/commands.md

@@ -0,0 +1,82 @@
+# MindForge v1.0.0 — Complete Commands Reference
+
+## All 36 commands
+
+### Lifecycle commands (core workflow)
+| Command | Usage | Description | Added |
+|---|---|---|---|
+| `/mindforge:init-project` | `init-project` | Guided project setup — creates all `.planning/` files | Day 1 |
+| `/mindforge:discuss-phase` | `discuss-phase [N] [--batch|--auto]` | Pre-planning interview to capture implementation decisions | Day 3 |
+| `/mindforge:plan-phase` | `plan-phase [N]` | Research, decompose, and create atomic task plans | Day 1 |
+| `/mindforge:execute-phase` | `execute-phase [N]` | Wave-based parallel execution of all phase plans | Day 1+2 |
+| `/mindforge:verify-phase` | `verify-phase [N]` | Automated + human acceptance testing pipeline | Day 1 |
+| `/mindforge:ship` | `ship [N]` | Create PR, write release notes, push to remote | Day 1 |
+| `/mindforge:next` | `next` | Auto-detect and execute the correct next workflow step | Day 2 |
+
+### Project setup & discovery
+| Command | Usage | Description | Added |
+|---|---|---|---|
+| `/mindforge:map-codebase` | `map-codebase` | Brownfield onboarding: infer stack and seed docs | Day 6 |
+| `/mindforge:quick` | `quick` | Run a small, single-task plan without a full phase | Day 2 |
+| `/mindforge:status` | `status` | Show current phase, plan status, and next action | Day 2 |
+| `/mindforge:health` | `health [--repair]` | Validate installation and repair drift | Day 2 |
+| `/mindforge:review` | `review [N]` | Run a structured review pass for a phase | Day 5 |
+| `/mindforge:debug` | `debug [plan-id]` | Debug a failed plan with root-cause workflow | Day 5 |
+
+### Governance & compliance
+| Command | Usage | Description | Added |
+|---|---|---|---|
+| `/mindforge:approve` | `approve [--tier 2|3]` | Process approvals and emergency overrides | Day 4 |
+| `/mindforge:audit` | `audit [--phase N] [--event X] [--since DATE]` | Query `AUDIT.jsonl` history | Day 2 |
+| `/mindforge:security-scan` | `security-scan [--deep] [--secrets] [--deps]` | Security scan with OWASP classification | Day 2 |
+| `/mindforge:milestone` | `milestone [name]` | Create or update milestone definitions | Day 4 |
+| `/mindforge:complete-milestone` | `complete-milestone [name]` | Archive milestone and generate release report | Day 4 |
+| `/mindforge:retrospective` | `retrospective [N]` | Phase retrospective and improvement actions | Day 5 |
+
+### Skills & plugins
+| Command | Usage | Description | Added |
+|---|---|---|---|
+| `/mindforge:skills` | `skills [list|validate|refresh]` | Manage core/org/project skills | Day 3 |
+| `/mindforge:install-skill` | `install-skill <name> [--version]` | Install skill from registry | Day 6 |
+| `/mindforge:publish-skill` | `publish-skill <path>` | Publish a skill to the registry | Day 6 |
+| `/mindforge:plugins` | `plugins [list|install|uninstall|validate]` | Manage plugin lifecycle | Day 7 |
+
+### Intelligence & metrics
+| Command | Usage | Description | Added |
+|---|---|---|---|
+| `/mindforge:metrics` | `metrics [--phase N]` | Compute quality and throughput metrics | Day 5 |
+| `/mindforge:profile-team` | `profile-team` | Generate team skill and ownership profile | Day 5 |
+| `/mindforge:benchmark` | `benchmark [--skill X]` | Measure skill effectiveness | Day 6 |
+| `/mindforge:tokens` | `tokens [--profile] [--summary]` | Token usage profiling and optimisation | Day 7 |
+
+### Integrations & distribution
+| Command | Usage | Description | Added |
+|---|---|---|---|
+| `/mindforge:init-org` | `init-org` | Org-wide MindForge setup | Day 6 |
+| `/mindforge:sync-jira` | `sync-jira [--project KEY]` | Sync phases and plans to Jira | Day 4 |
+| `/mindforge:sync-confluence` | `sync-confluence [--page ...]` | Publish docs to Confluence | Day 4 |
+| `/mindforge:pr-review` | `pr-review [--range A..B]` | AI PR review with context | Day 6 |
+| `/mindforge:workspace` | `workspace [detect|plan|test]` | Monorepo workspace management | Day 6 |
+
+### Release & maintenance
+| Command | Usage | Description | Added |
+|---|---|---|---|
+| `/mindforge:update` | `update [--apply] [--force] [--check]` | Check for and apply framework updates | Day 7 |
+| `/mindforge:migrate` | `migrate [--from vX] [--to vY] [--dry-run]` | Run schema migrations | Day 7 |
+| `/mindforge:release` | `release [--tag vX]` | Framework release pipeline (core team) | Day 7 |
+
+### Utility
+| Command | Usage | Description | Added |
+|---|---|---|---|
+| `/mindforge:help` | `help` | Show all available commands and current project status | Day 1 |
+
+## Command interface contract (v1.0.0 stable)
+
+As of v1.0.0, the following are part of the stable interface:
+- All 36 command names (new commands require MINOR bump)
+- All flags documented here (new flags require MINOR, removed flags require MAJOR)
+- HANDOFF.json and AUDIT.jsonl schemas (additions: MINOR, removals: MAJOR)
+- All 10 core skill `name:` values and trigger lists
+- SDK exported types and functions
+
+See ADR-020 for the complete stability contract.

package/docs/reference/config-reference.md

@@ -0,0 +1,64 @@
+# MindForge Configuration Reference (MINDFORGE.md)
+
+## Location
+`MINDFORGE.md` in the project root (beside `package.json`).
+
+## Syntax
+- `KEY=value`
+- Comments with `#`
+- Multiline values with triple quotes
+
+## Model preferences
+- `PLANNER_MODEL`
+- `EXECUTOR_MODEL`
+- `REVIEWER_MODEL`
+- `VERIFIER_MODEL`
+- `SECURITY_MODEL`
+- `DEBUG_MODEL`
+
+Valid values: `claude-opus-4-5`, `claude-sonnet-4-5`, `claude-haiku-4-5`, `inherit`.
+Unavailable values fallback to `inherit` with a warning.
+
+## Execution behavior
+- `TIER1_AUTO_APPROVE`
+- `WAVE_CONFIRMATION_REQUIRED`
+- `AUTO_DISCUSS_PHASE`
+- `VERIFY_PASS_RATE_WARNING_THRESHOLD` (v1.0.0 uses 0.0–1.0 range)
+- `COMPACTION_THRESHOLD_PCT`
+- `MAX_TASKS_PER_PHASE`
+
+## Quality standards
+- `MIN_TEST_COVERAGE_PCT`
+- `MAX_FUNCTION_LINES`
+- `MAX_CYCLOMATIC_COMPLEXITY`
+- `REQUIRE_ADR_FOR_ALL_DECISIONS`
+- `BLOCK_ON_MEDIUM_SECURITY_FINDINGS`
+
+## Skills behavior
+- `ALWAYS_LOAD_SKILLS`
+- `DISABLED_SKILLS`
+- `MAX_FULL_SKILL_INJECTIONS`
+
+## Governance behavior
+- `DISCUSS_PHASE_REQUIRED_ABOVE_DIFFICULTY`
+- `ANTIPATTERN_SENSITIVITY`
+- `BLOCK_ON_HIGH_ANTIPATTERNS`
+
+## Token settings (Day 7)
+- `TOKEN_WARN_THRESHOLD`
+- `TOKEN_LEAN_MODE`
+- `TOKEN_MAX_FILE_LINES`
+
+## Update settings (Day 7)
+- `MINDFORGE_AUTO_CHECK_UPDATES` (true/false)
+
+## Non-overridable rules
+The following cannot be overridden by MINDFORGE.md:
+- Security auto-trigger for auth/payment/PII changes
+- Plan-first rule
+- Secret detection gate
+- AUDIT writing requirement
+- Critical security and secret-related quality gates
+
+See `.mindforge/production/token-optimiser.md` and `docs/mindforge-md-reference.md`
+for full detail.

package/docs/reference/sdk-api.md

@@ -0,0 +1,48 @@
+# MindForge SDK API — Reference (v1.0.0)
+
+## Package
+`@mindforge/sdk`
+
+## Exports
+From `sdk/src/index.ts`:
+- `MindForgeClient`
+- `MindForgeEventStream`
+- `commands`
+- Types: `MindForgeConfig`, `PhaseResult`, `TaskResult`, `SecurityFinding`,
+  `GateResult`, `HealthReport`, `HealthIssue`, `MindForgeEvent`, `CommandOptions`
+- `VERSION`
+
+## MindForgeClient
+High-level API for reading local project state.
+
+Methods:
+- `isInitialised(): boolean`
+- `readState(): object | null`
+- `readHandoff(): object | null`
+- `health(): Promise<HealthReport>`
+- `readAuditLog(filter?): unknown[]`
+- `readSessionMetrics(limit?): unknown[]`
+- `validateConfig(): { valid: boolean, errors: string[], warnings: string[] }`
+
+## MindForgeEventStream
+Localhost-only SSE server for streaming audit events.
+
+Methods:
+- `start(port = 7337)`
+- `watchAuditLog(projectRoot)`
+- `broadcast(eventType, data)`
+- `stop()`
+
+## Command builders
+`commands` provides helpers to build slash-command strings:
+- `health(opts)`
+- `planPhase(phase, opts)`
+- `executePhase(phase, opts)`
+- `securityScan(path?, opts)`
+- `audit(filter)`
+- `prReview(opts)`
+
+## Security notes
+- The SDK reads local files that may contain sensitive data.
+- Event stream binds to `127.0.0.1` only and rejects non-local connections.
+- Do not expose the SSE port on public interfaces.

package/docs/reference/skills-api.md

@@ -0,0 +1,57 @@
+# MindForge Skills API — Reference (v1.0.0)
+
+## Overview
+Skills are domain knowledge packs loaded on demand. They are stored as
+`SKILL.md` files with frontmatter and optional assets.
+
+## File structure
+```
+.mindforge/skills/<skill-name>/
+  SKILL.md
+  assets/
+  references/
+```
+
+## SKILL.md schema (frontmatter)
+Required fields:
+- `name`: string (stable in 1.x.x)
+- `description`: string
+- `triggers`: array of keywords
+- `version`: semver string
+- `owner`: string (team or org)
+
+Optional fields:
+- `scope`: `core | org | project`
+- `severity`: `low | medium | high`
+- `links`: array of URLs
+
+Example:
+```yaml
+---
+name: security-review
+version: 1.0.0
+description: Secure coding review checklist and threat modeling prompts
+triggers: ["auth", "payment", "pii", "encryption"]
+owner: mindforge-core
+scope: core
+---
+```
+
+## Loading rules
+- Skills load only when trigger keywords match the task description
+- At most 3 skills are loaded at full size; others are summarized
+- Skills can be force-loaded via `ALWAYS_LOAD_SKILLS` in `MINDFORGE.md`
+
+## Validation
+`/mindforge:skills validate` enforces:
+- Valid frontmatter
+- No injection patterns in content
+- Required fields present
+
+## Publishing
+Skills can be published to the npm registry under `mindforge-skill-*`.
+See `docs/skills-publishing-guide.md` for full workflow.
+
+## Stability contract
+As of v1.0.0, the `name` values of the 10 core skills are stable. New optional
+fields may be added in minor versions; removals require a major version bump.

package/docs/release-checklist-guide.md

@@ -0,0 +1,37 @@
+# MindForge Release Checklist Guide (v1.0.0)
+
+This guide explains how to complete the production readiness checklist
+in `.mindforge/production/production-checklist.md` and log results in
+`.planning/RELEASE-CHECKLIST.md`.
+
+## How to use
+1. Open `.mindforge/production/production-checklist.md`
+2. For each item, run the **Verification step** exactly
+3. Record results in `.planning/RELEASE-CHECKLIST.md`
+
+## What “✅ verified” means
+An item is only ✅ when:
+- The verification step was executed
+- The result was successful
+- The verifier and date were recorded
+
+## Recommended order
+1. **Section A** — Installation & upgrade (local + global)
+2. **Section B** — Command coverage
+3. **Section C** — Governance gates
+4. **Section D** — Documentation
+5. **Section E** — Test coverage
+6. **Section F** — Release artifacts
+
+## Example entry
+```
+| A03 | ✅ | dev@example.com | 2026-03-22 | Local install verified |
+```
+
+## Common pitfalls
+- Marking ✅ without running the command
+- Skipping CI checks (E09/F03) before tagging
+- Forgetting to update SDK version to match root
+
+## Final release gate
+Do not tag or publish until **all 55 items** are ✅.

package/docs/requirements.md

@@ -0,0 +1,29 @@
+# MindForge Requirements (v1.0.0)
+
+Use this checklist before installation to avoid surprises.
+
+## System requirements
+- **Node.js:** 18+ (20 LTS recommended)
+- **Git:** 2.30+
+- **OS:** macOS, Linux, or Windows (WSL supported)
+- **Disk:** ~200MB free for framework + caches
+
+## Runtime requirements
+- **Claude Code** or **Antigravity** installed and working
+- Network access to npm registry for `npx mindforge-cc@latest`
+
+## Optional (but recommended)
+- `jq` for audit log queries
+- `gh` CLI for GitHub release workflows
+
+## Quick environment check
+```bash
+node -v
+npm -v
+git --version
+```
+
+## If you are in CI
+- Ensure `CI=true`
+- Use a Node 20 image
+- Keep `.planning/` writable

package/docs/sdk-reference.md

@@ -0,0 +1,27 @@
+# MindForge SDK Reference
+
+## Overview
+The `@mindforge/sdk` package provides a programmatic API for integrating MindForge
+into tools, dashboards, and CI pipelines.
+
+## API
+
+### `MindForgeClient`
+- `isInitialised(): boolean`
+- `readState(): object | null`
+- `readHandoff(): object | null`
+- `health(): Promise<HealthReport>`
+- `readAuditLog(filter?): unknown[]`
+- `readSessionMetrics(limit?): unknown[]`
+- `validateConfig(): { valid, errors, warnings }`
+
+### `MindForgeEventStream`
+- `start(port = 7337)` — starts localhost-only SSE server
+- `watchAuditLog(projectRoot)` — streams new AUDIT.jsonl entries
+- `broadcast(eventType, data)` — manual broadcast
+- `stop()` — shutdown server and watchers
+
+## Security considerations
+- The SDK reads local files that may contain sensitive data.
+- The event stream is bound to localhost only and rejects remote connections.
+- Do not expose SDK endpoints to public networks.

package/docs/security/SECURITY.md

@@ -0,0 +1,42 @@
+# MindForge — Security Policy
+
+## Supported versions
+
+| Version | Security support |
+|---|---|
+| 1.x.x | ✅ Active — patches released for all severity levels |
+| 0.6.x | ⚠️  Limited — critical fixes only, 90 days from v1.0.0 release |
+| < 0.6.0 | ❌ No support |
+
+## Reporting a vulnerability
+
+**Email:** security@mindforge.dev
+
+**Required information:**
+- Description of the vulnerability
+- Steps to reproduce
+- Potential impact assessment
+- Your name / handle (for acknowledgement, if desired)
+
+**Response timeline:**
+- Acknowledgement: within 24 hours
+- Initial assessment: within 7 days
+- Fix released: within 30 days for HIGH/CRITICAL, 90 days for MEDIUM/LOW
+- Coordinated disclosure: 90 days from initial report
+
+**We commit to:**
+- Not taking legal action against good-faith security researchers
+- Crediting researchers in the security advisory (with their permission)
+- Maintaining confidentiality until a fix is released
+
+## Known security model limitations
+
+See `docs/security/threat-model.md` for the full threat model.
+
+Key acknowledged limitations:
+1. Plugin permission model is advisory (not OS-enforced) — see TA7 in threat model
+2. The SSE event stream is localhost-only but any local process can connect — see TA6
+3. Approver identity uses `git config user.email` which is user-controlled — see TA5
+4. Agent instruction injection via SKILL.md requires review beyond pattern matching — see TA1
+
+These are known trade-offs, not bugs. They are documented in ADR-020.

package/docs/security/penetration-test-results.md

@@ -0,0 +1,31 @@
+# MindForge v1.0.0 — Penetration Test Results
+
+**Date:** 2026-03-22
+**Scope:** MindForge v1.0.0 threat model (7 threat actors)
+**Method:** Manual adversarial review + targeted negative tests
+
+## Summary
+- Critical findings: 0
+- High findings: 0
+- Medium findings: 2
+- Low findings: 3
+
+All findings were addressed or documented with explicit mitigations.
+
+## Findings
+| ID | Severity | Area | Description | Status |
+|---|---|---|---|---|
+| PT-01 | MEDIUM | Plugin system | Malicious plugin can request `write_state` permission | Mitigated: allowlist (`ELEVATED_PLUGINS`) + user approval |
+| PT-02 | MEDIUM | Skill registry | Injection patterns could bypass simple string match | Mitigated: injection guard + manual review guidance |
+| PT-03 | LOW | SSE stream | Local process can subscribe to localhost stream | Accepted: localhost-only + no secrets in stream |
+| PT-04 | LOW | Config | User-controlled git email for approvals | Accepted: governance assumption, documented |
+| PT-05 | LOW | CI | Workflow modification could bypass gates | Accepted: branch protection required |
+
+## Retest notes
+- Re-validated installer excludes `.env`, `.key`, `.pem` files
+- Verified migration restores from backup on failure
+- Confirmed plugin loader skips incompatible plugins and logs audit entry
+
+## Conclusion
+MindForge v1.0.0 is fit for public release with known, documented trade-offs.
+See `docs/security/threat-model.md` for full controls and residual risk.

package/docs/security/threat-model.md

@@ -0,0 +1,142 @@
+# MindForge v1.0.0 — Threat Model
+
+## Scope
+All attack surfaces introduced by MindForge across 7 days of development.
+Last reviewed: v1.0.0 release (March 2026).
+
+## Assets being protected
+
+| Asset | Classification | Location |
+|---|---|---|
+| API credentials | CRITICAL | Environment variables only (never in files) |
+| HANDOFF.json | HIGH — project state, agent notes, decisions | `.planning/HANDOFF.json` |
+| AUDIT.jsonl | HIGH — complete governance audit trail | `.planning/AUDIT.jsonl` |
+| Approval files | HIGH — governance records | `.planning/approvals/*.json` |
+| SECURITY.md | MEDIUM — security policy documentation | `.mindforge/org/SECURITY.md` |
+| CLAUDE.md | MEDIUM — agent instructions that shape behaviour | `.claude/CLAUDE.md` |
+| CONVENTIONS.md | LOW — coding standards | `.mindforge/org/CONVENTIONS.md` |
+
+## Threat Actor 1 — Malicious skill package author
+
+**Goal:** Inject adversarial instructions via a published `mindforge-skill-*` npm package.
+**Attack:** SKILL.md contains "IGNORE ALL PREVIOUS INSTRUCTIONS" or similar.
+**Controls:**
+- Injection guard in `loader.md` blocks known patterns at both install and load time
+- Level 1/2/3 skill validation at install time
+- TOCTOU-safe download (chmod 700 temp dir, tarball size check)
+- User must explicitly run `/mindforge:install-skill` — no auto-install
+
+**Residual risk:** MEDIUM — sophisticated injections that avoid simple string matching.
+**Mitigation:** Community review of public registry skills; organisation vetting of org-tier skills.
+
+---
+
+## Threat Actor 2 — MINDFORGE.md governance bypass
+
+**Goal:** Disable governance primitives via MINDFORGE.md settings.
+**Attack:** Set `SECRET_DETECTION=false`, `SECURITY_AUTOTRIGGER=false`.
+**Controls:**
+- Non-overridable rules enforced in CLAUDE.md session start protocol
+- MINDFORGE-SCHEMA.json marks these fields as `nonOverridable: true`
+- `bin/validate-config.js` warns on attempts to override these fields
+
+**Residual risk:** LOW — enforced at the agent instruction layer, not OS level.
+**Note:** An agent that ignores its CLAUDE.md is an agent that ignores everything.
+
+---
+
+## Threat Actor 3 — Accidental credential exposure in project files
+
+**Goal:** Not adversarial — developer accidentally commits a credential.
+**Attack vectors:**
+- Token pasted into HANDOFF.json
+- API key in MINDFORGE.md ADDITIONAL_AGENT_INSTRUCTIONS
+- Secret in AUDIT.jsonl via an error message
+
+**Controls:**
+- Gate 3 (secret detection) blocks ANY commit with credential patterns
+- `_warning` field in every HANDOFF.json schema reminding devs not to store secrets
+- Health engine (Category 7) scans .planning/ and root files for credential patterns
+- installer-core.js skips .env and *.key files during copyDir
+
+**Residual risk:** LOW — multiple detection layers with complementary coverage.
+
+---
+
+## Threat Actor 4 — TOCTOU attack on skill installation
+
+**Goal:** Replace a valid SKILL.md with malicious content in the window between download and validation.
+**Attack:** Race condition in temp directory.
+**Controls:**
+- `chmod 700` on temp directory (user-only access, blocks other OS users)
+- Tarball size check (detects empty/corrupted downloads)
+- Download → validate → install is a single-process, single-threaded operation
+
+**Residual risk:** VERY LOW — requires local machine compromise and precise timing.
+
+---
+
+## Threat Actor 5 — Compromised CI environment
+
+**Goal:** Bypass governance gates in CI to ship malicious code.
+**Attack:** Modify GitHub Actions workflow or CI runner environment to skip MindForge checks.
+**Controls:**
+- Gates run as separate CI jobs with explicit dependencies
+- Tier 3 changes always fail CI (cannot be configured away)
+- AUDIT.jsonl writes all gate results — tampering would require audit log manipulation
+- Branch protection rules on the repository (outside MindForge scope)
+
+**Residual risk:** HIGH — an attacker with write access to the workflow file or CI secrets
+can bypass. This is a threat to all CI systems, not MindForge specifically.
+**Mitigation:** Protect the `main` branch with required status checks.
+
+---
+
+## Threat Actor 6 — SSE event stream eavesdropping
+
+**Goal:** Read sensitive project state from the real-time event stream.
+**Attack:** Connect to port 7337 from another local process.
+**Controls:**
+- localhost-only binding (127.0.0.1) — not accessible from network
+- IP address check on every connection — non-localhost rejected with 403
+- CORS exact-origin matching (not wildcard)
+- Port only opens when the SDK's `MindForgeEventStream.start()` is explicitly called
+
+**Residual risk:** LOW — any process running as the same OS user can connect to localhost.
+**Mitigation:** The SSE stream exposes AUDIT entries, not credentials. Risk is information disclosure, not code execution.
+
+---
+
+## Threat Actor 7 — Plugin with elevated or undeclared permissions
+
+**Goal:** Use a MindForge plugin to exfiltrate project state or modify governance.
+**Attack:** Install a plugin that reads HANDOFF.json and sends it to an external server.
+**Controls:**
+- Permission model displayed to user at install time (requires explicit approval)
+- Injection guard run against all plugin .md files
+- All plugin-triggered actions logged with plugin name as agent in AUDIT.jsonl
+- `ELEVATED_PLUGINS` allowlist required for `write_state: true` permission
+
+**Residual risk:** MEDIUM — a user who installs a malicious plugin and approves its permissions.
+**Mitigation:** Only install plugins from sources you trust. Review plugin commands before installing.
+Treat MindForge plugins like VSCode extensions — they have significant project access.
+
+---
+
+## Controls summary matrix
+
+| Control | Threat Actors Mitigated |
+|---|---|
+| Injection guard (loader.md) | TA1, TA7 |
+| TOCTOU-safe download (chmod 700) | TA1, TA4 |
+| Non-overridable governance primitives | TA2 |
+| Gate 3 secret detection | TA3 |
+| Health engine credential scan | TA3 |
+| CI Tier 3 block | TA5 |
+| SSE localhost-only binding | TA6 |
+| Plugin permission model + AUDIT logging | TA7 |
+
+## Penetration test results
+
+See `docs/security/penetration-test-results.md` for the adversarial review
+conducted as part of the v1.0.0 production readiness process.

package/docs/skills-authoring-guide.md

@@ -0,0 +1,119 @@
+# 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
+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
+
+## Skill file structure
+
+```
+.mindforge/skills/[skill-name]/
+    SKILL.md          ← required
+    examples/         ← optional: sample inputs and outputs
+    resources/        ← optional: reference documents the skill uses
+    scripts/          ← optional: helper scripts the skill can run
+```
+
+## SKILL.md template
+
+```markdown
+---
+name: [skill-name-in-kebab-case]
+version: 1.0.0
+min_mindforge_version: 0.1.0
+status: stable | beta | alpha
+triggers: [comma-separated list of trigger keywords]
+mutually_exclusive_with:   # optional: skill names that conflict with this one
+breaking_changes:
+  # Record breaking changes here when bumping MAJOR version
+changelog:
+  - "1.0.0: Initial release"
+---
+
+# 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
+- Specific beats generic: `argon2` beats `hash`
+- Include common misspellings and abbreviations: `optimise, optimize`
+- Include acronyms and their expansions: `a11y, accessibility, WCAG, wcag`
+- Include library names: `Prisma, Drizzle, SQLAlchemy` for database-patterns
+- Aim for 10-30 triggers per skill
+- Avoid single-letter words and extremely common words (the, be, is, to)
+
+## Security notice for skill authors
+
+MindForge skills are injected directly into AI agent contexts. A skill file
+with adversarial content could manipulate agent behaviour.
+
+MindForge includes an injection guard that blocks skills containing known
+manipulation patterns. However, all skill authors — especially for Tier 2
+and Tier 3 skills — should:
+
+1. Never include instructions that override or disable safety behaviours
+2. Keep skill files in version control with a clear audit trail
+3. Review skill changes in code review before merging
+4. Restrict who can write to `.mindforge/personas/overrides/` and
+   `.mindforge/org/skills/` directories
+
+## Registering your skill
+After creating SKILL.md:
+```bash
+/mindforge:skills add .mindforge/skills/[your-skill-name]
+# Choose tier: 2 (org) or 3 (project)
+# Commit the manifest update
+```
+
+## Tier guidance
+
+| 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
+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.
+
+Update both the SKILL.md frontmatter AND the MANIFEST.md entry.