@xcraftmind/mastermind 0.25.0 → 0.27.0

package/README.md

@@ -30,7 +30,7 @@ mastermind init                      # scaffold .mastermind/, build the index, d
 echo ".mastermind/" >> .gitignore    # index + local specs are local state
 ```
 
-`init` builds the index and drafts `CONTEXT.md` from your code via `claude -p` (pass `--no-claude` or `--no-index` to skip). It also installs the workflow subagents + skills into `~/.claude/` so the full pipeline (planner / critic / executor / auditor) is available, not just the codegraph (`--no-global` to skip). Re-run `mastermind index .` to refresh, or `mastermind watch` to keep it live.
+`init` builds the index and drafts `CONTEXT.md` from your code via `claude -p` (pass `--no-claude` or `--no-index` to skip). It also installs the workflow subagents, skills, and slash commands into `~/.claude/` so the full pipeline (planner / critic / executor / auditor) is available, not just the codegraph (`--no-global` to skip). Re-run `mastermind index .` to refresh, or `mastermind watch` to keep it live.
 
 **3. Register with Claude Code** — once, globally:
 
@@ -53,11 +53,11 @@ Three pieces — the split is the part that trips people up:
 | | Scope | Lives in | How often |
 |---|---|---|---|
 | **Index** — `init` + `index` | **per project** | `.mastermind/mmcg.db` in each repo | once per repo, refresh with `index` / `watch` |
-| **Workflow** — subagents + skills | global | `~/.claude/{agents,skills}/` | installed + refreshed by `init` |
+| **Workflow** — subagents, skills, commands | global | `~/.claude/{agents,skills,commands}/` | installed + refreshed by `init` |
 | **MCP registration** — `setup claude` | once | `~/.claude/.mcp.json` | once for all projects |
 
 - **The index is always per-project.** Run `mastermind init` in *every* repo you want indexed. `doctor` reporting `index database not found` just means you haven't done this in the current directory yet (the exact situation if you run `doctor` from `/tmp` or a fresh shell).
-- **The workflow installs globally on `init`** — subagents + skills land in `~/.claude/{agents,skills}/`, overwriting Mastermind's own files to keep them current (`--no-global` to skip). Ships with the npm package; cargo installs use the plugin marketplace instead.
+- **The workflow installs globally on `init`** — subagents, skills + slash commands land in `~/.claude/{agents,skills,commands}/`, overwriting Mastermind's own files to keep them current (`--no-global` to skip). Ships with the npm package; cargo installs use the plugin marketplace instead.
 - **The MCP registration is usually once, globally.** The global entry launches `mastermind serve` from whichever project you open in Claude Code, so it picks up *that* project's `.mastermind/mmcg.db` automatically. You do **not** re-run `setup claude` per repo.
 - Use **per-project registration** only if you want the MCP config committed with the repo and version-pinned: `mastermind setup claude --project . --write-mcp` writes `./.mcp.json` with `command: "./node_modules/.bin/mastermind"` (pair it with a project-local install — see below).
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xcraftmind/mastermind",
-  "version": "0.25.0",
+  "version": "0.27.0",
   "description": "Mastermind workflow CLI + mmcg codegraph for AI coding agents — verify-spec / audit-spec gates, MCP server, multi-language tree-sitter indexer (Python, TypeScript, JavaScript, Rust, C#, Go, Java, PHP, C/C++). Prebuilt native binaries via optional platform packages — no Rust toolchain required.",
   "license": "MIT",
   "author": "xcraftmind",
@@ -38,12 +38,12 @@
     "mastermind"
   ],
   "optionalDependencies": {
-    "@xcraftmind/mmcg-darwin-arm64": "0.25.0",
-    "@xcraftmind/mmcg-darwin-x64": "0.25.0",
-    "@xcraftmind/mmcg-linux-x64-gnu": "0.25.0",
-    "@xcraftmind/mmcg-linux-arm64-gnu": "0.25.0",
-    "@xcraftmind/mmcg-linux-x64-musl": "0.25.0",
-    "@xcraftmind/mmcg-linux-arm64-musl": "0.25.0",
-    "@xcraftmind/mmcg-win32-x64-msvc": "0.25.0"
+    "@xcraftmind/mmcg-darwin-arm64": "0.27.0",
+    "@xcraftmind/mmcg-darwin-x64": "0.27.0",
+    "@xcraftmind/mmcg-linux-x64-gnu": "0.27.0",
+    "@xcraftmind/mmcg-linux-arm64-gnu": "0.27.0",
+    "@xcraftmind/mmcg-linux-x64-musl": "0.27.0",
+    "@xcraftmind/mmcg-linux-arm64-musl": "0.27.0",
+    "@xcraftmind/mmcg-win32-x64-msvc": "0.27.0"
   }
 }

package/share/agents/mastermind-auditor.md

@@ -46,7 +46,7 @@ You do NOT:
 ## Inputs
 
 The spawner passes:
-- **Spec path** — `.mastermind/tasks/XXX-*.md` that was supposed to be implemented
+- **Spec path** — `.mastermind/tasks/<NNN>-<name>/spec.md` that was supposed to be implemented
 - **Execution report** — the markdown the executor produced
 - **Optional: baseline ref** — a git ref representing state BEFORE the executor ran. Defaults to the most recent commit on the current branch's parent (or `HEAD` minus the executor's commits, if discoverable).
 
@@ -120,7 +120,7 @@ A markdown audit report:
 ```markdown
 ## Audit verdict: ✅ contract held | ⚠️ partial drift | ❌ contract broken
 
-**Spec:** `.mastermind/tasks/XXX-*.md`
+**Spec:** `.mastermind/tasks/<NNN>-<name>/spec.md`
 **Report audited:** <one-line identifier>
 **Baseline ref:** <git ref or "HEAD~N">
 
@@ -159,7 +159,11 @@ If verdict is anything other than `contract held`, the planner must address each
 
 ## Capture the lesson (institutional memory)
 
-When the verdict is `⚠️ partial drift` or `❌ contract broken`, append a **one-line lesson** to `.mastermind/tasks/_lessons.md` so the next planner can learn from this audit. Skip on clean `✅ contract held` verdicts — that's just normal operation, not a lesson.
+When the verdict is `⚠️ partial drift` or `❌ contract broken`, append a **one-line lesson** to `.mastermind/tasks/_lessons.md` (shared file at the top of `tasks/`, not inside any task folder) so the next planner can learn from this audit. Skip on clean `✅ contract held` verdicts — that's just normal operation, not a lesson.
+
+**Note on the `[auto]` entries already in the file.** As of mmcg 0.7.0, `mmcg audit-spec` and `mmcg run-task`'s post-phase deterministically append a `[auto]`-prefixed line summarizing the mechanical findings (counts of scope creep / caller drift / etc.) whenever they encounter a drift or broken verdict. Your job is to add a richer, root-cause-level lesson on top — what *caused* the drift, not just what the finding type was. Do not skip writing because an `[auto]` line already exists; the auto line is signal, your line is judgment.
+
+You may also drop the full audit report itself as `audit.md` inside the task folder (alongside `spec.md`) when it's worth preserving for later reference. The lesson is the one-line takeaway across all tasks; the audit report is the per-task record.
 
 Create the file if it doesn't exist with a header:
 
@@ -178,8 +182,8 @@ Each entry:
 
 Examples of good lessons (root cause, actionable):
 
-- `- 2026-05-12 042-session-refactor.md — partial drift — pre-edit snapshot was stale; planner had not re-indexed mmcg after a rebase, so caller counts were already wrong before the executor ran.`
-- `- 2026-05-19 058-rate-limiter.md — contract broken — tests passed locally but failed under concurrent load; Tests Plan didn't include a concurrency case and the critic didn't flag it.`
+- `- 2026-05-12 042-session-refactor — partial drift — pre-edit snapshot was stale; planner had not re-indexed mmcg after a rebase, so caller counts were already wrong before the executor ran.`
+- `- 2026-05-19 058-rate-limiter — contract broken — tests passed locally but failed under concurrent load; Tests Plan didn't include a concurrency case and the critic didn't flag it.`
 
 Bad lessons (symptom, not actionable):
 
@@ -193,7 +197,7 @@ The lessons file is plain markdown and intentionally NOT indexed by `mmcg_tasks`
 ## What you do NOT do
 
 - Run commands that modify state (no `git commit`, no `git push`, no destructive ops)
-- Open files in editors — only `Read` and `Write`/`Edit` for `_lessons.md` appends
+- Open files in editors — only `Read` and `Write`/`Edit` for `_lessons.md` appends (and optionally the task folder's `audit.md`)
 - Make recommendations about how to fix discrepancies — the planner decides
 - Apologize for finding problems — your job is to find them
 

package/share/agents/mastermind-critic.md

@@ -19,7 +19,7 @@ metadata:
 
 # Critic — design-time challenger
 
-Independent subagent that stress-tests a proposed design **before** it becomes a `.mastermind/tasks/*.md` spec. Spawned with no prior conversation context so the critique isn't anchored on the spawner's reasoning.
+Independent subagent that stress-tests a proposed design **before** it becomes a `.mastermind/tasks/<NNN>-<name>/spec.md` file. Spawned with no prior conversation context so the critique isn't anchored on the spawner's reasoning.
 
 **Output is structured by 7 engineering dimensions** — not a free-form list of weaknesses. Each dimension gets a verdict + concrete evidence. The planner can disagree but the disagreement must be logged in the spec's Notes section.
 

package/share/agents/mastermind-release.md

@@ -60,7 +60,7 @@ You translate completed work into a clean release artifact. You do not embellish
 ## Inputs
 
 The spawner passes:
-- **Spec path(s)** — `.mastermind/tasks/XXX-*.md` for the work being shipped (one or more if bundled).
+- **Spec path(s)** — `.mastermind/tasks/<NNN>-<name>/spec.md` for the work being shipped (one or more if bundled).
 - **Auditor report** — the markdown verdict from `mastermind-auditor`. You will quote the verdict and propagate any `concern` items as caveats in the PR body.
 - **Critic verdict (optional)** — if any dimension was `ship with caveats`, propagate the caveat into a "Known caveats" section in the PR.
 - **Base branch** — typically `main`; defaults from `git symbolic-ref refs/remotes/origin/HEAD` if unset.
@@ -113,13 +113,13 @@ If a Tests Plan / Docs Plan item from the spec is NOT in the diff, surface it as
   - Paragraph 1: **why** — the user-visible motivation or problem.
   - Paragraph 2: **what** — at a high level (one line per real change).
   - Paragraph 3: **how to verify** — the specific commands or checks a reviewer can run.
-  - Optional final line: spec reference `Spec: .mastermind/tasks/XXX-name.md`.
+  - Optional final line: spec reference `Spec: .mastermind/tasks/<NNN>-name/spec.md`.
 
 ### 6. Draft the PR description
 Structured sections (see the example in "Output" below for the shape):
 - **Why** — motivation, 1-3 sentences.
 - **What changed** — bullets, one per coherent change. Cite file paths.
-- **Spec** — link to `.mastermind/tasks/XXX-*.md`.
+- **Spec** — link to `.mastermind/tasks/<NNN>-<name>/spec.md`.
 - **Tests** — what tests are new / changed, cross-referenced against diff.
 - **Documentation** — what docs touched.
 - **Observability** — logs / metrics / probes added (or "n/a" with reason).
@@ -136,7 +136,7 @@ Structured sections (see the example in "Output" below for the shape):
 ```markdown
 ## Release draft
 
-**Spec(s):** `.mastermind/tasks/XXX-*.md`
+**Spec(s):** `.mastermind/tasks/<NNN>-<name>/spec.md`
 **Branch:** `<branch-name>` → `<base>`
 **Auditor verdict:** contract held
 **Style match:** Conventional Commits / plain imperative / <whatever was detected> — sample subjects from last 10 commits:
@@ -157,7 +157,7 @@ Structured sections (see the example in "Output" below for the shape):
 
 <body paragraph 3 — how to verify>
 
-Spec: .mastermind/tasks/XXX-name.md
+Spec: .mastermind/tasks/<NNN>-name/spec.md
 ```
 
 ---
@@ -176,7 +176,7 @@ Spec: .mastermind/tasks/XXX-name.md
 - `<file>` — <one line>
 
 ## Spec
-- `.mastermind/tasks/XXX-name.md`
+- `.mastermind/tasks/<NNN>-name/spec.md`
 
 ## Tests
 - <test name> — <what it covers>
@@ -226,7 +226,7 @@ git commit -m "$(cat <<'EOF'
 
 <commit body>
 
-Spec: .mastermind/tasks/XXX-name.md
+Spec: .mastermind/tasks/<NNN>-name/spec.md
 EOF
 )"
 
@@ -278,7 +278,7 @@ If any check fails, fix the draft before returning it.
 ### Clean release — Conventional Commits style
 
 **Spawner sends:**
-- Spec: `.mastermind/tasks/042-session-count-getter.md` (add `session_count()` accessor)
+- Spec: `.mastermind/tasks/042-session-count-getter/spec.md` (add `session_count()` accessor)
 - Auditor: `contract held`. 1 file changed, 1 test added.
 - Critic prior verdict: `ship with caveats` (concern: lock contention if called in hot path; mitigation noted in spec).
 
@@ -286,7 +286,7 @@ If any check fails, fix the draft before returning it.
 ```markdown
 ## Release draft
 
-**Spec(s):** `.mastermind/tasks/042-session-count-getter.md`
+**Spec(s):** `.mastermind/tasks/042-session-count-getter/spec.md`
 **Branch:** `feat/session-count` → `main`
 **Auditor verdict:** contract held
 **Style match:** Conventional Commits — sample subjects:
@@ -309,7 +309,7 @@ matching test for empty / populated / post-removal cases.
 
 Verify: cargo test session_count_returns_current_size
 
-Spec: .mastermind/tasks/042-session-count-getter.md
+Spec: .mastermind/tasks/042-session-count-getter/spec.md
 ```
 
 ---
@@ -329,7 +329,7 @@ the map. Mirrors the existing `turn_count` pattern.
 - `sdk/edge-ai-core/src/runtime/session.rs` — unit test `session_count_returns_current_size`
 
 ## Spec
-- `.mastermind/tasks/042-session-count-getter.md`
+- `.mastermind/tasks/042-session-count-getter/spec.md`
 
 ## Tests
 - `session_count_returns_current_size` — covers empty, after-insert, after-delete
@@ -382,7 +382,7 @@ matching test for empty / populated / post-removal cases.
 
 Verify: cargo test session_count_returns_current_size
 
-Spec: .mastermind/tasks/042-session-count-getter.md
+Spec: .mastermind/tasks/042-session-count-getter/spec.md
 EOF
 )"
 git push -u origin feat/session-count

package/share/agents/mastermind-task-executor.md

@@ -1,6 +1,6 @@
 ---
 name: mastermind-task-executor
-description: Subagent that executes a `.mastermind/tasks/XXX-*.md` spec phase-by-phase — applies edits, runs verification, marks the checklist, stops on first failure. Spawn this from a planner agent (using the [[mastermind-task-planning]] skill) to implement a delegated task.
+description: Subagent that executes a `.mastermind/tasks/<NNN>-<name>/spec.md` file phase-by-phase — applies edits, runs verification, marks the checklist, stops on first failure. Spawn this from a planner agent (using the [[mastermind-task-planning]] skill) to implement a delegated task.
 metadata:
   version: 0.1.0
   authors:
@@ -20,11 +20,11 @@ metadata:
 
 # Mastermind Task Executor
 
-A subagent purpose-built to consume a task spec produced by the Mastermind planning workflow and execute it deterministically. It is invoked with a path to a spec (e.g., `.mastermind/tasks/003-add-rate-limiter.md`) and returns an execution report.
+A subagent purpose-built to consume a task spec produced by the Mastermind planning workflow and execute it deterministically. It is invoked with a path to a spec (e.g., `.mastermind/tasks/003-add-rate-limiter/spec.md`) and returns an execution report.
 
 ## Role
 
-You execute a `.mastermind/tasks/XXX-*.md` spec **exactly as written**. The spec was produced by a planner who already brainstormed alternatives, weighed tradeoffs, and committed to an approach. Your job is implementation discipline:
+You execute a `.mastermind/tasks/<NNN>-<name>/spec.md` file **exactly as written**. The spec was produced by a planner who already brainstormed alternatives, weighed tradeoffs, and committed to an approach. Your job is implementation discipline:
 
 - Read the spec end-to-end first
 - Execute phases in order
@@ -38,9 +38,11 @@ Treat the spec as a contract. If it's wrong, surface it; don't paper over it.
 ## Inputs
 
 The spawner passes:
-- **Task path** — `.mastermind/tasks/<spec-file>.md`
+- **Task path** — `.mastermind/tasks/<NNN>-<name>/spec.md` (or a folder path — resolve `spec.md` inside it)
 - **Optional**: any clarifying context the planner wants you to know before starting
 
+The task folder may contain sibling files beside `spec.md` (audit notes, screenshots, prior versions, scratchpad). Treat them as context — read only those that the spec references. The contract is `spec.md`.
+
 ## Process
 
 1. Open the spec. Read it completely before touching code.
@@ -60,7 +62,7 @@ A markdown execution report:
 ```markdown
 ## Task <XXX> — execution report
 
-**Spec:** `.mastermind/tasks/<spec-name>.md`
+**Spec:** `.mastermind/tasks/<NNN>-<name>/spec.md`
 **Status:** ✅ complete | ⚠️ partial | ❌ failed
 
 ### Phases completed

package/share/commands/api-shape-explorer.md

@@ -0,0 +1,107 @@
+---
+name: api-shape-explorer
+description: Generate three radically different API/interface shapes for the same problem so you can compare tradeoffs before committing. Use when you're about to design a new module, service boundary, or public API and want to avoid anchoring on the first idea.
+metadata:
+  version: 0.1.0
+  authors:
+    - mastermind
+  tags:
+    - workflow
+    - design
+  role: user
+  variables:
+    - name: PROBLEM
+      required: true
+      description: What the API needs to do. Concrete use cases, not abstract goals.
+    - name: CONSTRAINTS
+      required: false
+      description: Hard constraints — language, framework, latency, compatibility.
+---
+
+# API Shape Explorer
+
+A user prompt that asks the model to generate three meaningfully different interface designs for the same problem, with tradeoffs. The goal is to force a comparison before you anchor on the first shape that comes to mind.
+
+## When to use
+
+- Designing a new module's public API
+- Choosing between an SDK shape, a CLI shape, and a config-file shape
+- Service boundary discussions — "should this be one endpoint or three?"
+- Before writing a design doc, to populate the "alternatives considered" section
+- Do NOT use this for implementation — use it only at the interface-design stage
+
+## Variables
+
+| Name | Required | Description |
+|---|---|---|
+| `PROBLEM` | yes | What the API needs to do. Concrete use cases beat abstract goals. |
+| `CONSTRAINTS` | no | Hard constraints — language, framework, latency targets, compatibility requirements. |
+
+## Prompt
+
+```text
+I'm designing an API/interface for the following problem. Before I commit to one shape, I want to see three meaningfully different options.
+
+PROBLEM:
+{{PROBLEM}}
+
+{{#if CONSTRAINTS}}
+CONSTRAINTS:
+{{CONSTRAINTS}}
+{{/if}}
+
+Generate exactly three interface designs. They must be *qualitatively* different — not three variations of the same idea. Examples of "qualitatively different": object-oriented vs. functional vs. data-pipeline; sync vs. async vs. streaming; one big call vs. many small calls vs. configuration-driven.
+
+For each, give me:
+
+## Option <N>: <short name>
+
+**Shape:** A code snippet showing how a caller would actually use it. 10-20 lines, realistic.
+
+**Mental model:** One sentence describing how a user has to think about this API to use it correctly.
+
+**Strengths:**
+- <thing 1>
+- <thing 2>
+
+**Weaknesses:**
+- <thing 1>
+- <thing 2>
+
+**Best when:** <one sentence on the situation this is the right shape for>
+
+After the three options, give me a short comparison:
+
+## Comparison
+
+| Dimension | Option 1 | Option 2 | Option 3 |
+|---|---|---|---|
+| Learning curve | low / medium / high | … | … |
+| Composability | … | … | … |
+| Testability | … | … | … |
+| Extensibility | … | … | … |
+
+End with one paragraph: "If forced to pick one without more information, I'd choose Option X because…"
+
+Do not hedge. Do not say "all three have merit." Pick one and defend it.
+```
+
+## Example invocation
+
+```text
+I'm designing an API/interface for the following problem. Before I commit to one shape, I want to see three meaningfully different options.
+
+PROBLEM:
+A library that retries flaky operations. Used in Python services. Needs to support: exponential backoff, max attempts, retry only on specific exception types, callback on retry, async and sync code paths. Typical caller wraps a single function call.
+
+CONSTRAINTS:
+- Python 3.11+, no external runtime deps
+- Must work in both sync and async code (one library, not two)
+- Should be debuggable — users have to be able to see *why* a retry happened
+```
+
+## Notes
+
+- The prompt deliberately forbids "all three are good" answers. Forcing a pick exposes which dimensions matter most to the model.
+- Re-run with the same `PROBLEM` and a slightly different `CONSTRAINTS` to see how the recommendation shifts. That's often where the real insight is.
+- Works well with Opus. Sonnet tends to make the three options closer to each other than they should be.

package/share/skills/mastermind-incident-response/SKILL.md

@@ -65,7 +65,7 @@ While asking, parallel-research with `mastermind-researcher` subagent:
 ```
 git log --since='2 hours ago' --oneline    → what changed recently
 git log -10 --oneline                       → most recent commits
-ls -lt .mastermind/tasks/ | head -10                  → most recent specs
+ls -lt .mastermind/tasks/*/spec.md 2>/dev/null | head -10  → most recent specs (folder-per-task)
 mmcg_status                                → index health
 ```
 
@@ -100,7 +100,7 @@ With pressure off, find **root cause** — not just the symptom. Five-whys disci
 - **Did observability fire?** If yes, why didn't it page sooner? If no, why wasn't it instrumented?
 - **Is this a recurrence?** Grep `CONTEXT.md` for the symptom — known gotcha?
 
-If a fix is needed, **don't write it inline in this incident flow** — open a `.mastermind/tasks/<NNN>-<short-name>.md` spec via the main workflow. The fix goes through the normal critic/auditor gates. Incident response identifies the need; planner designs the response.
+If a fix is needed, **don't write it inline in this incident flow** — open a `.mastermind/tasks/<NNN>-<short-name>/spec.md` via the main workflow. The fix goes through the normal critic/auditor gates. Incident response identifies the need; planner designs the response.
 
 ### Phase 4 — Postmortem (within 24h of resolution)
 

package/share/skills/mastermind-incident-response/references/investigation-playbook.md

@@ -61,17 +61,18 @@ If the blast radius DOES include the symptom's component → strong candidate. R
 Spec for any recent change should have had Tests Plan + Observability Plan + Performance Considerations sections (per spec template).
 
 ```bash
-# Find the spec for this work (look in .mastermind/tasks/ for matching name or timestamp)
-ls -lt .mastermind/tasks/
+# Find the spec for this work (look in .mastermind/tasks/ for matching folder or timestamp)
+ls -lt .mastermind/tasks/                                  # task folders, newest first
+ls -lt .mastermind/tasks/*/spec.md 2>/dev/null             # direct list of spec files by mtime
 
 # Read its Tests Plan
-grep -A 20 "Tests Plan" .mastermind/tasks/<NNN>-<name>.md
+grep -A 20 "Tests Plan" .mastermind/tasks/<NNN>-<name>/spec.md
 
 # Read its Observability Plan
-grep -A 10 "Observability Plan" .mastermind/tasks/<NNN>-<name>.md
+grep -A 10 "Observability Plan" .mastermind/tasks/<NNN>-<name>/spec.md
 
 # Read its Performance Considerations
-grep -A 10 "Performance Considerations" .mastermind/tasks/<NNN>-<name>.md
+grep -A 10 "Performance Considerations" .mastermind/tasks/<NNN>-<name>/spec.md
 ```
 
 Then ask:

package/share/skills/mastermind-incident-response/references/postmortem-template.md

@@ -138,7 +138,7 @@ Each action item gets owned, dated, and either (a) becomes a `.mastermind/tasks/
 
 | # | Action | Type | Owner | Due | Spec / CONTEXT entry |
 |---|---|---|---|---|---|
-| 1 | <Specific change — code, config, process, doc> | <code-fix \| context-md \| workflow-improvement \| process> | <person> | <YYYY-MM-DD> | <`.mastermind/tasks/NNN-…md` or "CONTEXT.md → Known gotchas">|
+| 1 | <Specific change — code, config, process, doc> | <code-fix \| context-md \| workflow-improvement \| process> | <person> | <YYYY-MM-DD> | <`.mastermind/tasks/NNN-name/spec.md` or "CONTEXT.md → Known gotchas">|
 | 2 | <…> | <…> | <…> | <…> | <…> |
 
 **Avoid action items like:**
@@ -147,8 +147,8 @@ Each action item gets owned, dated, and either (a) becomes a `.mastermind/tasks/
 - ❌ "Train the team on X" — training without process change rarely sticks
 
 **Prefer action items like:**
-- ✓ "Add P99 latency alert on /api/messages at 200ms threshold via Datadog monitor — `.mastermind/tasks/NNN-add-messages-latency-alert.md`"
-- ✓ "Add 'capacity test' as mandatory line in Performance Considerations section of spec-template — `.mastermind/tasks/NNN-spec-template-capacity.md`"
+- ✓ "Add P99 latency alert on /api/messages at 200ms threshold via Datadog monitor — `.mastermind/tasks/NNN-add-messages-latency-alert/spec.md`"
+- ✓ "Add 'capacity test' as mandatory line in Performance Considerations section of spec-template — `.mastermind/tasks/NNN-spec-template-capacity/spec.md`"
 - ✓ "Add CONTEXT.md known-gotcha: 'Redis cluster mode silently drops MULTI on key migrations during rebalance'"
 
 ---

package/share/skills/mastermind-incident-response/references/triage-checklist.md

@@ -48,8 +48,9 @@ git log --since='2 hours ago' --oneline
 git tag --sort=-creatordate | head -5
 git log -10 --oneline
 
-# What specs were finished recently
+# What specs were finished recently (each task is a folder containing spec.md)
 ls -lt .mastermind/tasks/ | head -10
+ls -lt .mastermind/tasks/*/spec.md 2>/dev/null | head -10
 
 # Are there in-progress specs that might be related?
 git status -s

package/share/skills/mastermind-task-executor/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: mastermind-task-executor
-description: Executes a task spec from `.mastermind/tasks/XXX-*.md` phase-by-phase — applies FIND/CHANGE TO edits, runs VERIFY commands, marks the checklist, stops on first failure. Use when the user says "execute task X", "run .mastermind/tasks/NNN", or hands off a delegation spec.
+description: Executes a task spec from `.mastermind/tasks/<NNN>-<name>/spec.md` phase-by-phase — applies FIND/CHANGE TO edits, runs VERIFY commands, marks the checklist, stops on first failure. Use when the user says "execute task X", "run .mastermind/tasks/NNN", or hands off a delegation spec.
 metadata:
   version: 0.2.0
   authors:
@@ -15,12 +15,14 @@ metadata:
 
 # Mastermind - Task Executor Skill
 
-You are in Executor mode. Someone (the planner — see [[mastermind-task-planning]]) wrote a spec in `.mastermind/tasks/XXX-*.md`. Your job is to execute it exactly as written. You do not improvise, you do not add features, you do not refactor anything the spec doesn't tell you to refactor.
+You are in Executor mode. Someone (the planner — see [[mastermind-task-planning]]) wrote a spec at `.mastermind/tasks/<NNN>-<name>/spec.md`. Your job is to execute it exactly as written. You do not improvise, you do not add features, you do not refactor anything the spec doesn't tell you to refactor.
+
+The task folder may also contain related artifacts beside `spec.md` (audit notes, screenshots, prior versions, scratchpad). Treat anything other than `spec.md` as context — read it only if the spec references it explicitly. The contract is `spec.md`.
 
 ## When to Activate
 
 - User says "execute task X" or "run task X"
-- User says "execute .mastermind/tasks/NNN-...md"
+- User says "execute .mastermind/tasks/NNN-name" or hands off a path to a folder / `spec.md`
 - User hands off a task spec for implementation
 - A planner subagent spawned you with a task path
 
@@ -44,7 +46,7 @@ You are in Executor mode. Someone (the planner — see [[mastermind-task-plannin
 
 ### Step 1 — Read the whole spec first
 
-Open `.mastermind/tasks/<spec-name>.md` and read it top to bottom **before editing anything**. Pay attention to:
+Open `.mastermind/tasks/<NNN>-<name>/spec.md` and read it top to bottom **before editing anything**. Pay attention to:
 
 - **LLM Agent Directives** — the framing. What are you doing, why, with what rules?
 - **Goals** — what counts as done
@@ -90,7 +92,7 @@ Output a report in this exact shape:
 ```markdown
 ## Task <XXX> — execution report
 
-**Spec:** `.mastermind/tasks/<spec-name>.md`
+**Spec:** `.mastermind/tasks/<NNN>-<name>/spec.md`
 **Status:** ✅ complete | ⚠️ partial | ❌ failed
 
 ### Phases completed

package/share/skills/mastermind-task-planning/SKILL.md

@@ -200,7 +200,8 @@ You do not have to agree with the critic on every dimension. But if you disagree
 **Do not write the spec from scratch.** Copy the canonical template:
 
 ```bash
-cp <path-to-skill>/references/spec-template.md .mastermind/tasks/<NNN>-<kebab-feature>.md
+mkdir -p .mastermind/tasks/<NNN>-<kebab-feature>
+cp <path-to-skill>/references/spec-template.md .mastermind/tasks/<NNN>-<kebab-feature>/spec.md
 ```
 
 Then fill in every `<placeholder>` and delete sections that don't apply. See [`references/spec-template.md`](references/spec-template.md) for the full layout — it includes everything the executor and auditor expect (directives, phases with FIND/CHANGE TO/VERIFY, pre-edit mmcg checks, checklist, do-not-do, and planner-only notes for pre-flight + critic verdict).
@@ -298,7 +299,7 @@ Append to `CONTEXT.md` ONLY when the discovery is worth preserving across sessio
 | Discovery from this task | CONTEXT.md section to update |
 |---|---|
 | Non-trivial design decision the critic agreed with | **Decision log** — date, decision, why, alternatives rejected |
-| Workflow surprised by something — "almost broke X because Y" | **Known gotchas** — one-line summary + `.mastermind/tasks/NNN` reference |
+| Workflow surprised by something — "almost broke X because Y" | **Known gotchas** — one-line summary + `.mastermind/tasks/NNN-name/` reference |
 | New term that took explaining during brainstorming | **Domain glossary** — term + local meaning |
 | New external dependency added (service, API, vendor) | **External dependencies** — what for + auth mechanism |
 | Code area found to have hidden constraints | **Don't-touch list** — path + constraint |
@@ -322,15 +323,31 @@ If both audit and semantic review pass, report to the user with:
 
 The user sees what was mechanically verified, your judgment on the work, and what was added to the project's institutional memory.
 
-## Task Numbering
+## Task Layout
 
-- Check existing tasks in `.mastermind/tasks/` folder
-- Use next sequential number: 001, 002, 003...
-- Format: `XXX-kebab-case-name.md`
+Each task lives in its own folder under `.mastermind/tasks/`:
+
+```
+.mastermind/tasks/
+├── _lessons.md              # shared audit lessons (underscore-prefixed, not indexed; auditor appends to it)
+├── 001-rate-limiter/
+│   └── spec.md              # the spec itself
+├── 002-cache-eviction/
+│   ├── spec.md
+│   ├── audit.md             # auditor's verdict, kept beside the spec
+│   ├── notes.md             # ad-hoc planning notes
+│   └── screenshots/         # any related artifacts
+└── 003-…/
+```
+
+- Check existing task folders for the next sequential number: 001, 002, 003…
+- Folder name: `<NNN>-<kebab-case-name>` (e.g. `042-add-rate-limiter`)
+- Spec file inside: always `spec.md`
+- Anything else related to the task (audit notes, screenshots, critic verdicts, scratchpad) goes into the same folder
 
 ## First Time Setup
 
-If `.mastermind/tasks/` folder doesn't exist, create it and optionally create `CONTEXT.md` with project info.
+If `.mastermind/tasks/` doesn't exist, create it and optionally create `CONTEXT.md` with project info. `mmcg init` does this for you.
 
 ## Pair Skill
 

package/share/skills/mastermind-task-planning/references/spec-template.md

@@ -2,7 +2,8 @@
   Canonical Mastermind task spec template.
 
   HOW TO USE
-  - The planner ([../SKILL.md](../SKILL.md)) copies this whole file to .mastermind/tasks/XXX-kebab-feature-name.md
+  - The planner ([../SKILL.md](../SKILL.md)) creates the folder .mastermind/tasks/XXX-kebab-feature-name/
+    and copies this whole file to .mastermind/tasks/XXX-kebab-feature-name/spec.md
   - Replace every <placeholder> with concrete content
   - Delete sections that don't apply (e.g., drop the Critic Verdict block if no critic was spawned)
   - Do NOT show this file to the executor — show the filled-in spec only