
metis
Flight Levels methodology for project and work management. Teaches when and why to use Metis tools for project planning, work decomposition, and phase management, and interviews you to sharpen visions and initiatives before work starts.
- version
- 2.5.0
- GitHub stars
- 15
Install
/plugin install metis@colliery-io-metisRun it inside Claude Code after adding the marketplace with /plugin marketplace add colliery-io/metis.
Contents
Discovered from sourceSkills 11
Code Index Generation
This skill guides the process of generating and maintaining .metis/code-index.md — a structured codebase map for AI agent navigation.
CRITICAL: File Editing Rules
The code index file (.metis/code-index.md) is a regular file, NOT a Metis document. You MUST:
- Use the Read tool to read
.metis/code-index.md - Use the Edit tool to modify
.metis/code-index.md - NEVER use
mcp__metis__edit_documentormcp__metis__read_documentfor this file — those are for Metis documents (visions, initiatives, tasks, ADRs, specifications), not the code index
Overview
The code index has two layers:
- Layer 1 (Structural): Auto-generated file tree and symbol extraction via tree-sitter. Fast, deterministic. Generated by
metis index. Tells you what symbols exist. - Layer 2 (Semantic): AI-generated summaries that explain what the code means — key abstractions, symbol relationships, non-obvious behavior, and mixed concerns. Generated by the
code-index-summarizersubagent.
Background Agent Permissions
The code-index-summarizer agent runs in the background and needs Edit access to write summaries to .metis/code-index.md. By default, background agents cannot prompt for tool approval.
To enable background summarization, the user must add Edit(.metis/code-index.md) to their allowed tools. They can do this by running /permissions and adding the rule.
If this permission isn't configured, tell the user:
"The semantic summarizer needs Edit access to
.metis/code-index.mdto run in the background. Run/permissionsand addEdit(.metis/code-index.md)to your allowed tools. Otherwise I can run it in the foreground, but it'll take a couple of minutes."
Quick Start
Generate a fresh index
- Run structural index via Bash:
metis index(ormetis index --incrementalto skip unchanged files) - Launch the
code-index-summarizeragent via the Task tool to generate semantic summaries:Task(subagent_type="code-index-summarizer", prompt="Generate semantic summaries for all source modules in .metis/code-index.md. This is a first run — summarize ALL modules.", run_in_background=true, model="sonnet")
Update an existing index
- Re-run structural index via Bash:
metis index --incremental - Determine which directories had files change (from the incremental output or from
.metis/.index-dirtycontents) - Launch the
code-index-summarizeragent to update only changed modules:Task(subagent_type="code-index-summarizer", prompt="Update semantic summaries in .metis/code-index.md for these changed modules: <list>. Only re-summarize the listed modules; leave others unchanged.", run_in_background=true, model="sonnet")
Automatic Index Updates
Source file changes are tracked automatically:
- A PostToolUse hook records modified source files to
.metis/.index-dirty - At PreCompact and Stop time,
metis index --incrementalruns automatically if dirty files exist - After PreCompact, the restored context will note that the index was updated and which directories changed — you can optionally launch the summarizer agent for those modules
File Structure
The code index is organized as ## Modules with summaries co-located next to symbols:
## Modules
### module/path
> *Semantic summary to be generated by AI agent.* ← summary slot
#### module/path/file.rs ← file symbols
- pub `StructName` struct L5-20 — `{ field: Type }`
- pub `function_name` function L22-40 — `(args) -> Result`
#### module/path/other.rs
- symbols...
### another/module
(AI-written summary here) ← replaced by summarizer
#### another/module/file.rs
- symbols...
Summaries sit between the ### module heading and the first #### file heading.
The structural index preserves existing summaries across regenerations — when
metis index runs again, it keeps any AI-written summaries and only resets
placeholders for new modules.
What the Semantic Summaries Cover
The summarizer reads ALL source files in each module and produces understanding that symbol names alone can't convey:
- Key abstractions — what types/traits/interfaces actually represent, their invariants, when they're created vs looked up
- Symbol relationships — how pieces connect: what calls what, what implements what, what orchestrates what
- Internal flow — how a request/operation moves through the module
- Mixed concerns / gotchas — modules with impure separation, implicit coupling, surprising behavior
- Dependencies — not just crate names, but what the module uses them for
Guidelines
When to regenerate
Re-run the full index (Layer 1 + Layer 2) when:
- Starting work on an unfamiliar project
- After major refactors that change directory structure
- When significant new modules are added
- When semantic summaries feel stale or inaccurate
Re-run Layer 1 only (structural) when:
- New files were added but directory structure is the same
- You just need updated symbol listings
Model Selection
The code-index-summarizer agent uses Sonnet for generating semantic summaries. It reads ALL source files in each module (not just 2-3 representative files) to produce accurate understanding of symbol semantics and relationships. The structural index (Layer 1) is deterministic and doesn't use any model.
Work Decomposition
This skill guides the process of breaking higher-level work into actionable lower-level items.
The Decomposition Chain
Vision: "Make X a better experience"
↓
Initiative: "Reduce page load time by 50%"
↓
Tasks: "Profile slow queries", "Add caching layer", "Optimize images"
Each level breaks work above it into concrete, actionable pieces at appropriate scope.
When to Decompose
Decompose ahead of capacity, not upfront:
- When team's current backlog is nearing its end
- During tail end of current work to prepare next batch
- When backlog is getting low (signal to look up and pull work down)
Avoid: Decomposing everything upfront (waterfall). Have work ready when capacity frees up, not entire project planned before starting.
The Decompose Phase
Initiatives have an explicit "decompose" phase:
discovery → design → ready → decompose → active → completed
Why Decompose is Explicit
The decompose phase creates a visible buffer:
- Solutions can pile up waiting to be broken into tasks
- Tracks how long things sit here
- Makes bottlenecks visible in multi-team environments
Don't skip to decompose early. Premature decomposition leads to tasks that solve wrong problems, rework when design changes, wasted effort.
Sizing by Scope, Not Time
Size by scope and impact, not implementation time:
Tasks: Atomic Units
- Scope: Discrete, completable piece with clear done criteria
- Impact: Moves the needle on parent initiative
- Independence: Can be worked without constant coordination
- Examples: "Add caching layer", "Write migration script", "Update API endpoint"
If a task has meaningful subtasks, it should probably be an initiative.
Initiatives: Capability Increments
- Scope: Creates fundamental increment in capability
- Impact: Meaningfully changes what system can do
- Coherence: Tasks within work toward unified outcome
- Examples: "User authentication", "Search functionality", "Billing integration"
If it doesn't change what system can do, it might just be a task.
Decomposition Patterns
Vertical Slices (Preferred)
Break by user-visible functionality:
Initiative: "User authentication"
├── Task: "Login flow"
├── Task: "Registration flow"
├── Task: "Password reset"
└── Task: "Session management"
Each task delivers something user can see/use.
Horizontal Layers (Use Sparingly)
Break by technical component:
Initiative: "User authentication"
├── Task: "Database schema"
├── Task: "API endpoints"
├── Task: "Frontend components"
└── Task: "Integration tests"
Creates dependencies between tasks. Prefer vertical slices.
Risk-First
Break by unknowns:
Initiative: "ML recommendation engine"
├── Task: "Spike: Evaluate model options" (high uncertainty)
├── Task: "Build training pipeline" (after spike)
└── Task: "Integration with product" (low uncertainty)
Address risky/uncertain work first to fail fast.
Milestone-Based
Break by deliverable checkpoints:
Initiative: "Platform migration"
├── Task: "Phase 1: Read path on new platform"
├── Task: "Phase 2: Write path on new platform"
├── Task: "Phase 3: Deprecate old platform"
└── Task: "Phase 4: Cleanup"
Each milestone independently valuable and deployable.
Naming Tasks Before They Exist
Decomposition is the single biggest source of invented shorthand: you draft five tasks in a message, call them "Task 1" through "Task 5", and those labels outlive the message.
While the tasks are still proposals, name them by full title in quotes and say they aren't created yet:
Proposed (not yet created): "Login flow", "Registration flow", "Password reset", "Session management".
Do not assign an interim ID — not T1, not "task A", not a placeholder short code to be swapped later. Numbers in a list are for the user to answer against in that message ("re: 3, split it"); they are not identifiers and don't survive into the next message, a document, or a commit.
The moment you call create_document, the tool result gives you the real short code. From then on the task's name is that short code, and the working title is just its title. Never predict what a short code will be — the counter is Metis's, not yours.
A slice is a shape, not a name. "Vertical slice" describes how the work was cut, the way "horizontal layer" and "risk-first" do. It is not an identifier. Labelling the cuts "Slice 1" through "Slice 5" while drafting, and then writing those labels into the initiative's Implementation Plan, leaves the plan referring to five entities that exist nowhere -- no short code, no phase, nothing that can be completed. A slice becomes a task; its name is that task's short code.
The same applies to sequencing. "Phase 1 tasks", "the first batch", "the DB workstream" are entities nothing in Metis holds; they die with the conversation while people keep referring to them. Express ordering as a dependency between short codes and record it in the initiative's implementation plan.
The implementation plan is written in short codes. Every item in it names a real task, or a quoted title for a task not yet created. Never write a short code into the plan that you have not just created or just read back -- a plan citing PROJ-T-0012 for a task that was never created is worse than a vague one, because it looks like it resolves.
See the metis-vocabulary skill for the full rules.
Quality Checklist
Good decomposition - each child item:
- Independently valuable: Delivers something useful alone
- Clearly scoped: Know when it's done
- Right-sized: Matches scope expectations for level
- Aligned to parent: Clearly contributes to level above
- Written in STE: Objective and acceptance criteria use ASD-STE100 Simplified Technical English. Each criterion is one imperative sentence of 20 words or fewer, with a verifiable result. See the
ste100-writingskill.
Bad decomposition smells:
- Too granular: "write line 42" - steps, not tasks
- Too vague: "make it better" - no completion criteria
- Wrong level: Doesn't match document type scope
- Orphaned: Doesn't trace back to parent
- Overlapping: Multiple items covering same ground
Common Mistakes
| Mistake | Problem | Fix |
|---|---|---|
| Decomposing too early | Tasks solve wrong problem | Stay in discovery/design until approach clear |
| Decomposing too late | Initiative active with no tasks | Decompose before moving to active |
| Wrong granularity | Tasks that are initiatives or vice versa | Apply scope heuristics |
| Missing alignment | Tasks don't contribute to initiative | Each task needs obvious connection to parent |
Judgment Calls
- Uncertain scope? Create spike/research task first, then decompose based on findings
- Large initiative? Consider if it's really multiple capability increments
- Tiny initiative? Consider if it's really just a task
- Cross-cutting? May need tasks under multiple initiatives, or dedicated "platform" initiative
After Drafting Tasks
Once the tasks exist, run one bounded review over them as a set with the grill-decomposition skill (/grill-decomposition PROJ-I-0001). It checks slice boundaries, ordering, verifiable acceptance criteria, and scope leaks, and writes the answers into the task documents. Do this before the initiative moves to active. If the review keeps surfacing design questions, that is a signal to go back to grill-initiative, not to press on.
Additional Resources
For detailed decomposition patterns and examples:
references/decomposition-patterns.md- Complete pattern catalog with examples
Document Type Selection
This skill helps choose the right Metis document type for different kinds of work.
Quick Decision Guide
Is this work, or is it a decision?
- Decision about architecture/approach → ADR
- Work to be done → Continue below
Is this a detailed specification or design document?
- Yes, describes system/feature requirements or design → Specification
- No → Continue below
Does this define WHY the project exists?
- Yes → Vision
Does this create a fundamental capability increment?
- Yes → Initiative
Is this a discrete, completable piece of work?
- Yes, belongs to an initiative → Task
- Yes, standalone (bug/feature/debt) → Backlog Item
Document Types Reference
| Type | Purpose | Parent Required |
|---|---|---|
| Vision | North star objectives | No |
| Initiative | Capability increments | Vision (published) |
| Task | Atomic work units | Initiative (decompose/active phase) |
| Backlog Item | Ad-hoc bugs/features/debt | No |
| ADR | Architectural decisions | No |
| Specification | System/feature specs (living docs) | Vision or Initiative |
Parent phase guidance:
- Initiatives are typically created under a published vision
- Tasks are typically created under an initiative in decompose or active phase
reassign_parentenforces initiative phase (must be decompose/active)
User Terminology Mapping
When users request work items using common terms, map to Metis document types:
| User Says | Create |
|---|---|
| "bug ticket", "bug", "defect" | create_document(type="task", backlog_category="bug", ...) |
| "feature ticket", "feature request" | create_document(type="task", backlog_category="feature", ...) |
| "tech debt ticket", "tech debt" | create_document(type="task", backlog_category="tech-debt", ...) |
| "project", "epic", "feature work", "workstream" | Initiative (with parent) |
| "work item", "ticket", "story", "card", "issue" | Task (if has parent) or Backlog Item (if standalone) |
| "sub-task", "step", "checklist item" | An acceptance criterion inside a task -- not its own document |
| "spike", "investigation", "research" | Task, titled "Spike: ..." |
| "spec", "specification", "design doc" | create_document(type="specification", parent_id="...", ...) |
| "sprint", "milestone", "release", "phase 2", "batch 1" | Nothing -- ordering between tasks, recorded in the initiative's implementation plan |
Translate, don't adopt. These are the only document types Metis has; a term that isn't on this list doesn't become one because a user said it. Answer using the Metis type so the mapping stays visible ("that's an initiative -- PROJ-I-0003"), and never create a document whose type or category you made up. The last row matters most: it names things with no Metis document behind them, and naming one anyway is how a phantom entity enters a project. See the metis-vocabulary skill for the full translation table.
When to Create Each Type
Vision
Create when:
- Starting a new project
- Redefining project direction
- Current vision no longer represents objectives
Not a vision: "Build feature X" (initiative), "Fix bugs" (operational), "Q1 goals" (initiatives)
Initiative
Create when:
- Work delivers meaningful capability increment
- Multiple tasks needed
- Discovery/design phases valuable
- Track as distinct project
Not an initiative: Single task, ongoing operations (backlog), aspiration without commitment (keep in backlog)
Task
Create when:
- Clear parent initiative exists
- Discrete, completable unit
- One person can own it
- Done criteria are clear
Not a task: Work with no parent (backlog item), work too large (break down or make initiative)
Backlog Item
Create when:
- Bug discovered in production
- Feature request not tied to initiative
- Tech debt to address when capacity allows
- Operational/maintenance work
Categories: bug, feature, tech-debt
Moving backlog items: Use reassign_parent to move a backlog item into an initiative, or move a task back to backlog.
Specification
Create when:
- Documenting system architecture or feature requirements
- Writing a detailed design document for a project area
- Creating living documentation that evolves as the system changes
- Need a persistent reference for how something works or should work
Not a specification: Architectural decisions (ADR), project planning (initiative), individual work items (task)
Phases: discovery → drafting → review → published (published content remains editable as a living document)
Requirements keep their IDs: a specification is where PRD-style requirements live, and the template gives its Functional and Non-Functional tables an ID column -- REQ-x.y.z and NFR-x.y.z, each with a rationale. Fill them in; they are what makes a requirement citable and traceable. This is the only numbering scheme in Metis: no other document type gets one. Cited from outside the specification, qualify the ID with the short code (METIS-S-0002 REQ-2.1.1).
ADR
Create when:
- Making significant architectural decision
- Choosing between meaningful alternatives
- Decision affects multiple initiatives
- Future developers will wonder "why?"
Not an ADR: Trivial decisions, work to be done (task/initiative), meeting notes
Common Mistakes
| Mistake | Problem | Fix |
|---|---|---|
| Task that takes months | Wrong granularity | If it has subtasks, make it an initiative |
| Initiative for every idea | Overhead | Use backlog items, promote when committed |
| ADR for implementation | Confusion | ADR records decision; tasks implement it |
Edge Cases
Task vs Initiative: Does it need discovery/design phases? If yes, initiative.
Initiative vs Backlog: Committing to it now? If no, backlog.
Backlog vs Task: Does it have a parent? If no, backlog.
Specification vs ADR: Specs describe how something works; ADRs record why a decision was made. A spec may reference ADRs for the reasoning behind design choices.
Cross-cutting work: Create initiative under most relevant parent; tasks can reference other initiatives.
Additional Resources
For detailed decision trees and edge cases:
references/decision-trees.md- Complete decision frameworkreferences/when-to-adr.md- ADR-specific guidance
Related skill:
metis-vocabulary- Canonical short codes, types, phases, and categories; how to refer to work that doesn't exist yet
Grill Decomposition
Run the grilling skill against the set of tasks under an initiative. Read the grilling skill first; it defines how to run the interview. This file defines what you are sharpening and, just as importantly, what you are not.
This is not a per-task grill. By the time an initiative has been through grill-initiative, most task-level questions are facts (which file, which test, which module) and facts are yours to look up. The decisions that remain live at the boundaries between tasks. Expect one or two rounds, not a long session.
Step 1: Load the Set
Parse $ARGUMENTS for a short code matching PREFIX-I-NNNN. If none is given, mcp__metis__list_documents(document_type="initiative") and pick the one in decompose; ask if there is more than one.
Then:
mcp__metis__read_documentthe initiative. Note its phase, goals, non-goals, design, and implementation plan.mcp__metis__list_documents(document_type="task")and keep the tasks whose parent is this initiative. Read each one.- Read
.metis/code-index.mdso you can check claims about where code lives without asking.
Phase check. This skill expects the initiative in decompose (or active with tasks still in todo). If it is in discovery, design, or ready with no tasks, there is nothing to grill yet; point the user at grill-initiative or the decomposition skill and stop. If there are no child tasks, say so and stop.
Step 2: The Four Questions
Each branch below is a root of the design tree. Ask across the whole set at once, naming tasks by short code. Give a recommended answer for every question.
Name every existing task by its short code, never by position ("the second task") or a label of your own. A task you are proposing to add does not have a short code yet: give it a full quoted title and mark it as not yet created, and switch to the real code the moment create_document returns one. Question numbers belong to this round only — they never become names for work.
Slice boundaries. For each task: is it a vertical slice that proves something on its own, or a horizontal layer that proves nothing until others land? Where a task is a layer, propose the merge or split that makes it a slice, and ask.
Ordering and risk. Which task retires the most uncertainty? Recommend it go first. Where one task cannot start until another finishes, say so and ask whether the dependency is real or an artefact of how the work was cut.
Done criteria. For each acceptance criterion: could a Ralph loop verify it without a human? Criteria like "works well" or "is clean" are not verifiable. Propose a concrete replacement (a command that passes, a response code, a file that exists, a metric under a threshold) and ask the user to confirm or correct it. Criteria that genuinely need a human eye should say so explicitly. Write each settled criterion in ASD-STE100 Simplified Technical English: one imperative sentence, 20 words or fewer, one result (see the ste100-writing skill).
Scope leaks. Compare every task against the initiative's non-goals and goals. Flag any task that does work the initiative ruled out, and any goal no task covers. Ask whether to cut, add, or accept the gap.
Step 3: Interview and Write
Follow the grilling skill. As each answer settles, write it into the task it belongs to: read_document, then edit_document the Acceptance Criteria, Objective, or Implementation Notes section. When a task is split, merged, or cut, do it with create_document, edit_document, and archive_document immediately, then read the set back so the next round starts from the real state.
Record one status update on the initiative per round: which tasks changed and why.
Going Back Up
If a question turns out to be a design question rather than a decomposition question ("should this use a queue or a cron job?", "is partial cancellation allowed?"), stop. Do not absorb it into a task. Tell the user the initiative's design has a hole, name it, and offer grill-initiative. Tasks written on top of an unsettled design are the anti-pattern the decomposition skill warns about.
Step 4: Close
When the frontier is empty:
- Read every task back. Each should have criteria a loop can verify, one clear objective, and an obvious link to the parent.
- Summarise the final set in a few lines: task order, dependencies, and anything cut or added. Ask the user to confirm.
- Do not transition the initiative or any task. The user decides when the initiative goes
activeand when tasks move totodo. - Once confirmed, the tasks are ready for
/metis-ralphor/metis-ralph-tasks.
Grill Initiative
Run the grilling skill against a Metis initiative document. Read the grilling skill first; it defines how to run the interview. This file defines what you are sharpening.
Step 1: Locate or Create the Initiative
Parse $ARGUMENTS:
- A short code matching
PREFIX-I-NNNN:mcp__metis__read_documentit. If it is not found, say so and stop. - Anything else (a title or a one-line idea): confirm the title and the parent vision (
mcp__metis__list_documents(document_type="vision"); initiatives hang off a published vision), thenmcp__metis__create_document(document_type="initiative", title=..., parent_id=...)and read it back. - Nothing:
mcp__metis__list_documents(document_type="initiative"). If exactly one initiative is indiscoveryordesign, use it. Otherwise ask.
Also read the parent vision. Every answer in the interview should trace back to it; when one does not, say so.
Phase Awareness
The initiative's phase sets the depth of the interview:
| Phase | Focus of the interview |
|---|---|
discovery | Context, goals, non-goals, and whether the problem is understood well enough to design |
design | Detailed design, alternatives considered, testing strategy, implementation plan |
ready / decompose | The design is meant to be settled. Grill only what the user asks to reopen, and flag that answers may invalidate tasks already created |
active / completed | Do not grill. Tell the user the initiative is past design and offer to open a new one |
Never transition the phase yourself. Initiatives are strategic; the human decides when discovery is done and when design is done.
Step 2: Seed the Design Tree
The initiative template has these sections. Each is a branch; the questions below are the roots. Facts about the codebase, existing documents, and prior decisions are yours to look up before asking. Use .metis/code-index.md first.
Context
- What is true today that makes this initiative necessary now? Verify against the code and the vision.
- Who is asking for it, and who is affected but not asking?
- What has been tried before, in this codebase or elsewhere, and why did it stop?
Goals & Non-Goals
- What capability exists after this initiative that does not exist before? One sentence per goal.
- For each goal: how would you tell it was met? If you cannot, it is not a goal yet.
- What adjacent thing will people assume is included that is not? Write each one down as a non-goal.
- Which goal is the one you would keep if you had to drop the rest?
Detailed Design (in design and later)
- What are the moving parts, and where do they live in the current codebase? Look this up.
- What is the interface between this and what already exists? Data shapes, APIs, ownership.
- Walk through the main scenario end to end. Then walk through the failure scenario. Then the concurrent one.
- Which term in the design is ambiguous? Pin it down before moving on.
Alternatives Considered
- What is the simplest thing that could work, and why is it not enough?
- What would a different team have built here? Why not that?
- For each rejected alternative: what specific fact or value ruled it out? "Felt wrong" is not an answer.
Implementation Plan
- What is the first vertical slice that proves the approach? What would it demonstrate?
- What must be true before decomposition can start?
- Where are the dependencies on other initiatives, teams, or systems? Are they resolved?
Testing Strategy
- How does the user know it works? How does the code know?
- What would you be embarrassed to have shipped broken? Test that first.
- What cannot be tested automatically, and who checks it?
Expect new branches to appear as answers land. Recompute the frontier every round.
Step 3: Interview and Write
Follow the grilling skill. As each decision settles, edit_document the matching section immediately. Record a short status update per round.
Two extra disciplines for initiatives:
- ADRs. When an alternative is rejected for a reason that is hard to reverse, surprising without context, and a real trade-off, offer an ADR. If accepted, create it with
mcp__metis__create_document(document_type="adr", ...), fill it in from the interview, and link it from Alternatives Considered. Most rejected alternatives do not need one. - Scope creep. When an answer describes work that is its own capability increment, say so and suggest it be a separate initiative. Note it in the status updates rather than growing this one.
Step 4: Close
When the frontier is empty:
- Read the initiative back in full. Check its exit criteria (context and goals defined, technical approach designed, implementation plan phased, testing strategy defined, dependencies identified).
- Summarise the settled design in a few lines and ask the user to confirm shared understanding.
- Do not transition the phase. Tell the user which phase the document is in and what the next one is, and let them decide.
- If the user confirms and the initiative is in
designor later, offer thedecompositionskill for breaking it into tasks, followed bygrill-decompositionto review the drafted set. Decomposition stays human-in-the-loop.
Grill Vision
Run the grilling skill against a Metis vision document. Read the grilling skill first; it defines how to run the interview. This file defines what you are sharpening.
Step 1: Locate or Create the Vision
Parse $ARGUMENTS:
- A short code matching
PREFIX-V-NNNN:mcp__metis__read_documentit. If it is not found, say so and stop. - Anything else (a title or a one-line idea): confirm the title with the user, then
mcp__metis__create_document(document_type="vision", title=...)and read it back. - Nothing:
mcp__metis__list_documents(document_type="vision"). If there is exactly one non-published vision, use it. Otherwise ask which one, or whether to create a new one.
Note the vision's phase. Grilling is normal in draft and review. A published vision is terminal; if the user wants to change one, tell them a new vision is the path and ask before creating it.
Step 2: Seed the Design Tree
The vision template has these sections. Each is a branch of the tree; the questions below are the roots of each branch. Facts about the current codebase, existing initiatives, and prior visions are yours to look up before asking.
Purpose (why this exists)
- Who is this for, and what changes for them when the vision is achieved?
- What problem is painful enough today that it justifies this effort?
- What is the one sentence a stranger could repeat back?
Current State (the baseline)
- What exists now? Check the codebase, existing Metis documents, and any prior vision before asking.
- What is working that must not be broken?
- What is the honest gap between now and the future state?
Future State (the target)
- Describe a concrete day-in-the-life once the vision is realised. What is different?
- What is explicitly not part of this future? Draw the boundary.
- How far out is this? What horizon does "vision" mean here?
Success Criteria (how we know)
- What would you measure, or observe, to say it is done?
- Which criteria are leading indicators and which are lagging?
- What would make you declare the vision a failure even if the work shipped?
Principles (how we decide)
- When two good options conflict, which value wins? Ask for concrete tie-breakers, not slogans.
- Which principle would you keep even if it slowed you down?
- Is any principle already contradicted by the code or by an existing initiative?
Constraints (the fences)
- What is fixed: budget, people, timeline, platform, compatibility, regulation?
- Which constraints are real and which are assumptions? Challenge each one.
- What existing initiatives or ADRs bound this vision?
Expect new branches to appear as answers land. Recompute the frontier every round.
Step 3: Interview and Write
Follow the grilling skill. As each decision settles, edit_document the matching section immediately. Record a short status update per round.
Push on anything that reads like an initiative rather than a vision ("build feature X", "Q3 goals"). Those belong under the vision, not in it; note them as candidate initiatives in the status updates and move on.
Step 4: Close
When the frontier is empty:
- Read the vision back in full. Check its exit criteria (purpose and success criteria defined, current and future states documented, principles established, stakeholder review).
- Summarise the settled vision in a few lines and ask the user to confirm shared understanding.
- Do not transition the vision's phase. If the user wants it moved to
review, they say so;mcp__metis__transition_phaseonly on explicit instruction. - If candidate initiatives surfaced, list them and offer to grill the first one with
grill-initiativeonce the vision is published.
Grilling
Interview the user relentlessly until you reach a shared understanding. Map the conversation as a design tree: every decision branches into the decisions that hang off it. Nothing is left silently assumed.
This is the interview engine. The grill-vision, grill-initiative, and grill-decomposition skills tell you which Metis document you are sharpening and which sections its branches map to. Read them for the document-specific parts; this file covers how to run the interview.
Rounds and the Frontier
Work the tree in rounds. The frontier is every decision whose prerequisites are already settled: the questions you can ask now without guessing at answers you haven't heard yet.
Each round:
- Ask the whole frontier at once. Number each question and give your recommended answer.
- Wait for the user's answers. Do not answer for them.
- Settled decisions push the frontier outward and unblock questions that depended on them. Recompute the frontier and ask the next round.
A question whose answer depends on another question still open in this round belongs to a later round, not this one.
Format a round like so:
❓ **Q1** - **<question title>**: <question body, may be several paragraphs, may offer choices>
➡️ <your recommended answer>
---
❓ **Q2** - **<question title>**: <question body>
➡️ <your recommended answer>
Facts vs Decisions
Finding facts is your job, never the user's. When a frontier question needs a fact from the environment (the codebase, .metis/code-index.md, existing Metis documents, tests, configs), go and look it up. Prefer .metis/code-index.md and mcp__metis__search_documents before exploring from scratch. Never ask the user for anything you could find yourself.
Don't block on a lookup: a running exploration is an unsettled prerequisite, so only the questions downstream of it wait. Ask the rest of the frontier now.
Decisions are the user's. Put each to them, with your recommendation, and wait.
Write As You Go
This is the "with docs" half. The document you are grilling is a Metis document, and it is the record of the interview. Do not batch edits to the end.
- When a decision settles, immediately
mcp__metis__edit_documentthe section it belongs to. Replace template placeholders with the actual answer. Alwaysread_documentbeforeedit_document. - When a decision reverses an earlier one, update the section so it reads as the current truth, not as a changelog.
- Add a short entry to the document's status updates section per round: which questions closed, what changed.
- Write everything you put into the document in ASD-STE100 Simplified Technical English. The user can answer in any style; you translate the settled answer into STE when you write it. See the
ste100-writingskill.
The document should be readable at any point during the session by someone who was not in the conversation.
Sharpen Language
- When the user uses a vague or overloaded term, propose a precise one. "You said 'account'. Do you mean the Customer or the User? Those are different things."
- When a term conflicts with how existing Metis documents or the code use it, call it out immediately and ask which is right.
- When a term settles, it has one meaning from then on (the STE rule "one word, one meaning"). Write its definition into the document and use only that term. Do not alternate between synonyms.
- When relationships between concepts are being discussed, invent concrete scenarios that probe edge cases and force the boundary to be stated.
- When the user states how something works, check whether the code agrees. Surface contradictions.
Name Things The Way Metis Does
An interview generates candidates faster than documents: work you have proposed but not created, ideas the user raised in passing, scope you have parked for later. Every one of them is a chance to invent a name that nothing in Metis holds.
- Documents that exist are referred to by short code, always: "
PROJ-I-0003already covers the retry policy." Never "the auth initiative" as if it were an identifier, never an abbreviated code. - Candidates that don't exist yet get a full quoted title and an explicit "not yet created" — never an interim ID, and never a predicted short code. Only
create_documentmints one; take it from the tool result. - Question numbers are not identifiers.
Q1–Q6address a single round. They must not appear in a document, a commit, or a later message as a name for work. - Decisions are not numbered either. The shorthand
D1/D2/D3for "the third decision" is the same failure wearing a suit: two rounds later "let's revisit D3" resolves to nothing and nothing ever closed it. A decision that has been recorded is its ADR short code (PROJ-A-0003). A decision area still open is named by what it decides ("Session storage backend"). A choice not worth an ADR is prose in the document's design section, with no identifier at all. - Use Metis's words for types and phases — initiative, task,
decompose,active— not epics, stories, sprints, or "in progress". When the user brings outside vocabulary, translate it in your reply so the mapping is visible rather than quietly adopting it. - When you park scope for later, park it as a named candidate ("out of scope, candidate initiative: "Bulk import"") or create the document. Do not invent a bucket like "phase 2" to hold it.
The metis-vocabulary skill has the full rules and the repair procedure for a name that has already leaked into documents.
Offer ADRs Sparingly
Only offer to record an ADR when all three are true:
- Hard to reverse: changing your mind later costs something real.
- Surprising without context: a future reader will ask "why did they do it this way?"
- A real trade-off: there were genuine alternatives and one was picked for specific reasons.
If any one is missing, skip the ADR. When all three hold, ask the user; if they agree, create it with mcp__metis__create_document(document_type="adr", ...), fill in Context, Decision, Rationale, and Consequences from the interview, and reference it from the document being grilled.
Ending the Session
The session is done when the frontier is empty: every branch of the design tree visited, nothing left silently assumed. Then:
- Read the document back in full and check it against its exit criteria checklist. Tick what is genuinely met.
- Summarise the settled design in a few lines and ask the user to confirm you have reached a shared understanding.
- Do not transition the document's phase and do not start acting on the design until the user confirms. Phase transitions on visions and initiatives are human decisions.
Metis Vocabulary
Metis has names for everything it tracks. Use them. Never invent your own.
An invented name -- "Task 3", "the auth epic", "Slice 2", "D3", "phase 2 work" -- looks harmless in one message and is unrecoverable two messages later. It does not resolve in list_documents, it does not appear in the user's GUI or metis status, and after a compaction nobody (including you) can tell which document it meant.
The Test
Not every identifier is invented. The question is always the same:
Can a reader find where this identifier is defined?
- A Metis short code resolves through
read_document. Legitimate. - A
REQ-2.1.1in a specification's requirements table resolves to a row in that table. Legitimate, and required -- but only there; see "The One Carve-Out" below. D3,Slice 2,Task 1, "the third decision" resolve to nothing. They were introduced in passing and then reused as if they had been defined. Invented.
So there are two kinds of identifier, with two different rules:
| Kind | Owned by | Rule |
|---|---|---|
| Cross-document identity -- anything referred to from outside the document it lives in | Metis | The short code, minted by create_document, never invented |
| Requirements on a specification -- and nothing else | That specification | Use the template's scheme (REQ-x.y.z, NFR-x.y.z); qualify with the short code when citing from outside |
Everything else is invented, and the fact that it looks structured (D3, S-2, Slice 1) makes it worse, not better: a reader assumes a scheme exists and goes looking for it.
The One Rule
A work item's name is its Metis short code, and nothing else.
Short codes look like PREFIX-T-0042: the project prefix, a type letter (V vision, I initiative, T task, A ADR, S specification), and a four-digit number. The prefix comes from project configuration and the number from a database counter.
That means:
- Never guess, predict, reserve, or "continue the sequence" of a short code. Only
create_documentmints one. Read it back from the tool result, and use exactly that string. - Never renumber.
PROJ-T-0007staysPROJ-T-0007even if it is the second task you created and the fourth one to run. - Never abbreviate. Not
T-7, not#7, not "the 0007 task". The full short code, every time. - If you don't know an item's short code, find it --
mcp__metis__list_documentsormcp__metis__search_documents. Do not describe it instead.
A short code you write into a document must be one you have just created or just read back. This is the rule that gets broken quietly: an initiative's Implementation Plan fills up with references like "handled by PROJ-T-0012" for tasks that were never created, or that turn out to be something else entirely. A short code recalled from memory is a guess. Before it goes in a document, either it came back from create_document in this session, or you resolved it with read_document/list_documents. Work that doesn't exist yet is referenced by quoted title, never by a forward-looking code.
Naming Work That Doesn't Exist Yet
Proposals, decomposition drafts, and grill rounds all discuss work before it is created. That gap is where invented IDs come from.
Until the document exists, refer to it by its full title in quotes, and say it isn't created yet:
Proposed (not yet created): "Add refresh-token rotation", "Expire sessions on password change".
- Do not assign an interim ID -- no "T1", no "task A", no placeholder short code to be swapped later.
- Numbered lists are fine within one message for the user to answer against ("re: 2, yes"). The numbers are question numbers, not identifiers: don't carry them into a later message, a document, or a commit.
- The moment the document is created, drop the working title as an identifier and switch to the short code the tool returned.
Use Metis's Types, Phases, and Categories
Metis's enumerations are closed sets. If a word isn't in them, it isn't a Metis concept -- translate it, don't adopt it.
- Document types:
vision,initiative,task,adr,specification. There is no epic, story, sub-task, chore, milestone, or bug type. A spike is atask. A bug is ataskwithbacklog_category="bug". - Phases: each type has its own set (tasks:
backlog,todo,active,blocked,completed). Report status with the phase word Metis uses -- a task isactive, not "in progress";completed, not "done" or "shipped". - Backlog categories:
bug,feature,tech-debt. Nothing else. - Section headings: come from the document template. Write your content under the heading that already exists rather than adding a heading of your own.
- Numbering schemes: there is exactly one, and it belongs to a specification's requirements tables. See "The One Carve-Out" below.
references/canonical-vocabulary.md has the complete tables, including phases per document type and the translation table for terms users bring from other trackers.
The One Carve-Out: Requirements On a Specification
There is exactly one place where an identifier that isn't a Metis short code is correct, and it is a specification document, in its requirements tables. A specification is where PRD-style content lives, and PRD requirements are numbered so they can be cited, tested, and traced. That numbering stays.
The carve-out reaches no further. It does not apply to initiatives, tasks, ADRs, or visions -- those have no requirement tables, and nothing in them gets a numbering scheme of your own.
The template gives both requirement tables an ID column:
### Functional Requirements
| ID | Requirement | Rationale |
|----|-------------|-----------|
| REQ-1.1.1 | The API rejects a token older than 24h | Limits blast radius of a leaked token |
### Non-Functional Requirements
| ID | Requirement | Rationale |
|----|-------------|-----------|
| NFR-1.1.1 | p99 auth latency stays under 50ms | Login is on the critical path |
- Use the template's prefixes:
REQ-x.y.zfor functional,NFR-x.y.zfor non-functional. Don't substitute a scheme of your own (FR-1,F1,R.1) -- the template's is the convention the project already reads. - Every requirement gets an ID and a rationale. A requirements table with a blank ID column is incomplete in the same way a template placeholder is.
- IDs are stable. Adding a requirement means a new number, never renumbering the existing rows -- something may already cite them.
- Citing one from outside the specification, qualify it with the short code: "
METIS-S-0002REQ-2.1.1".REQ-2.1.1alone is only unique inside its own document, so on its own -- in an initiative, a task, or a commit -- it is exactly the dangling reference this skill is about.
Everywhere else, resist the pull to number things:
- An initiative's goals, non-goals, and detailed design are prose. They do not become
G1,NG2,DD-3. - A task's acceptance criteria are the checklist the template gives it. Cite one as "
PROJ-T-0042, third criterion" -- notAC-3. - An ADR's decision is the ADR. It is
PROJ-A-0003, notD3.
Plans Are Written In Short Codes
A plan describes work, and every piece of work it describes already has a Metis name. So a plan -- an initiative's Implementation Plan, a specification's Decision Log, a status summary, anything that sequences or assigns -- is written in short codes:
- Work to be done: the task's short code, or a quoted title if the task does not exist yet.
- The capability it belongs to: the initiative's short code.
- The requirements it satisfies: the specification's short code, qualified (
METIS-S-0002REQ-2.1.1). - The decision it follows: the ADR's short code.
Every one of those must resolve. A plan whose steps are "Slice 2", "D3", and "phase 1 work" describes nothing that can be opened, worked, or completed -- and a plan citing PROJ-T-0012 for a task that was never created is worse, because it looks like it resolves.
Decisions Are ADRs, Not D-Numbers
A design conversation produces decisions, and the tempting shorthand is to number them: D1, D2, D3, "the third decision". Two messages later "let's revisit D3" means nothing, and nothing in Metis ever closed it.
Metis already has the identity for a decision, and the specification template already says so:
- Architecture Framing describes a Decision Area -- named by its area name, with context, constraints, required capabilities, and an ADR field for the decision once made.
- Decision Log is a table keyed by ADR short code (
PROJ-A-0001), with title, status, and a one-line summary.
So:
- A decision that has been made is
PROJ-A-0003. That is its name, in the decision log, in the initiative that referenced it, and in conversation. - A decision area still open is named by its area name ("Session storage backend"), with the ADR field marked pending. Not
D3. - Not every decision earns an ADR -- most settle into the Detailed Design section as prose and need no identifier at all. Writing it down as prose is the alternative to numbering it, not a reason to number it.
- Numbers you used to run a conversation (
Q1-Q6in a grill round, "option 2") stay in that message. They never enter a document, a commit, or a later message as a name.
Slices Are a Shape, Not a Name
"Vertical slice" describes how work was cut, the way "horizontal layer" or "risk-first" does. It is not an identifier, and a slice is not a thing Metis tracks.
The failure looks like this: you cut an initiative into five slices, label them "Slice 1" through "Slice 5" while drafting, write those labels into the initiative's Implementation Plan, and now the plan refers to five entities that exist nowhere -- no short code, no phase, nothing that can be completed.
- A slice becomes a task. Once created, its name is the task's short code.
- Before it is created, it is a quoted title -- "Login flow" -- marked not yet created.
- An implementation plan sequences short codes, not slice numbers.
- The word "slice" belongs in a sentence about the shape of the decomposition ("cut as vertical slices so each proves something on its own"), never as a label attached to a number.
Don't Invent Grouping Entities
"Workstream A", "batch 2", "phase 1 tasks", "the migration epic" -- these read like tracked things and aren't. Nothing in Metis holds them, so they die with the conversation while people go on referring to them.
Group work the way Metis groups it:
- Work that belongs together is children of the same initiative. That is the grouping.
- Sequencing is stated as a dependency between short codes ("
PROJ-T-0007beforePROJ-T-0008"), recorded in the initiative's implementation plan or the tasks' notes. - If a grouping is real and durable, it deserves a document -- usually its own initiative. Propose creating one instead of naming a phantom.
Outside the Conversation, Too
Anything that outlives the session carries the short code:
- Commits and PRs: reference
PROJ-T-0042, never a made-up ticket ID. - Branch names: derive from the short code when you name one.
- Code comments and TODOs:
// TODO(PROJ-T-0042), or no ID at all -- never an invented one. - Status summaries to the user: short code plus title, so the user can look it up.
- TodoWrite entries: if a todo corresponds to Metis work, put the short code in the text. A todo list of invented labels is a shadow backlog with no way home.
When You Catch an Invented Name
You will sometimes notice one -- yours, an earlier session's, or the user's. Repair it as soon as you see it; don't quietly keep using it.
- Resolve it.
mcp__metis__search_documentson the words in the name, ormcp__metis__list_documentsfiltered by type and parent, to find the document it meant. - If it resolves, say so plainly and switch: "'the auth epic' is
PROJ-I-0003." Then fix the references you still control --read_document,edit_documentthe documents that carry the invented name. - If it doesn't resolve, the work isn't tracked. Say so, and offer to create the document. Don't guess at a match.
- If the user used it, they get an answer, not a correction lecture: answer the question, and use the short code in your reply so the mapping is visible.
A short code already written into a document gets verified, not trusted. When you read an initiative whose plan cites PROJ-T-0012, read_document it before building on it. A code that resolves to nothing, or to a document that isn't what the sentence claims, is a broken reference: fix the document to name the real work, or replace the code with a quoted title if the work was never created. Do not propagate it into new documents, tasks, or commits on the assumption that a previous session got it right.
Additional Resources
references/canonical-vocabulary.md-- complete tables: short code grammar, document types, phases per type, backlog categories, template section headings, the specification requirement-ID convention, and translations for outside terminology.
Phase Transitions
This skill guides moving Metis documents through their lifecycle phases.
Phase Sequences
Phases move forward only. You cannot go backward to a previous phase. Terminal phases cannot transition further.
Vision
draft → review → published
- draft → review
- review → published
- published: terminal
Initiative
discovery → design → ready → decompose → active → completed
- discovery → design
- design → ready
- ready → decompose
- decompose → active
- active → completed
- completed: terminal
Task
backlog → todo → active → completed
↓ ↓
blocked ←──┘
- backlog → todo
- todo → active OR blocked
- active → completed OR blocked
- blocked → todo OR active (return from blocked state)
- completed: terminal
ADR
draft → discussion → decided → superseded
- draft → discussion
- discussion → decided
- decided → superseded
- superseded: terminal
WARNING: Auto-advancing from decided moves to superseded. Most ADRs should stay in decided indefinitely. Only manually transition to superseded when explicitly replacing with a new ADR.
Specification
discovery → drafting → review → published
- discovery → drafting
- drafting → review
- review → published
- published: terminal (but content remains editable as a living document)
Default Phases
When documents are created, they start in these phases:
- Vision:
draft - Initiative:
discovery - Task:
todo(orbacklogfor backlog items) - ADR:
draft - Specification:
discovery
Backlog note: Tasks created with backlog_category start in backlog phase and do NOT auto-transition. You must explicitly transition from backlog → todo before the task can be worked.
Phase Names Are a Closed Set
The phases above are all of them. A phase is not a mood you describe in your own words -- it is a value stored on the document, and it is what list_documents, metis status, and the GUI board read.
So report status with Metis's word, exactly:
| Don't say | Say |
|---|---|
| in progress, WIP, started, underway | active |
| done, shipped, closed, finished | completed |
| open, not started, queued, up next | todo |
| on hold, waiting, stuck, parked | blocked |
| icebox, someday, unprioritized | backlog |
| approved, signed off | published (vision/spec) or decided (ADR) |
Two rules follow:
- Never invent a phase. There is no
in-reviewfor tasks, noqa, nodeployed. If the workflow you want isn't in the sequence, say so rather than inventing a status word to paper over it. - Saying it doesn't make it so. Reporting a task as complete is not the same as transitioning it. Call
transition_phase; if it errors, the transition wasn't valid, and the phase is whatever the document still says -- report that, not what you intended.
Critical Rule: No Phase Skipping
Transitions are constrained to adjacent phases only.
Invalid transitions (will error):
todo → completed(must go todo → active → completed)discovery → active(must progress through all intermediate phases)draft → published(must go draft → review → published)
To complete a task, call transition_phase twice:
transition_phase(short_code)→ todo to activetransition_phase(short_code)→ active to completed
To publish a vision, call transition_phase twice:
transition_phase(short_code)→ draft to reviewtransition_phase(short_code)→ review to published
Using transition_phase
Auto-advance (recommended):
transition_phase(short_code="PROJ-I-0001")
Moves to next valid phase. Validates exit criteria.
Explicit phase (for blocked state):
transition_phase(short_code="PROJ-T-0042", phase="blocked")
Use explicit phase only for moving to/from blocked state (tasks only).
Force (use sparingly):
transition_phase(short_code="PROJ-I-0001", force=true)
Skips exit criteria validation. Use only when accepting the risk.
Exit Criteria
Exit criteria are conditions that must be true before transitioning.
Good Exit Criteria
- Observable: Can be verified
- Specific: Clear what "done" means
- Relevant: Matters for next phase
- Achievable: Realistic for scope
Common Exit Criteria Patterns
discovery → design:
- Problem statement clear and validated
- Key constraints identified
- Stakeholders aligned on scope
design → ready:
- Solution approach documented
- Technical risks identified
- Dependencies mapped
ready → decompose:
- Design reviewed and approved
- Team capacity available
- No blocking dependencies
decompose → active:
- Tasks created with acceptance criteria
- Task backlog sufficient to start
- Team understands the work
active → completed (tasks):
- Acceptance criteria met
- Work verified/tested
- No known defects
Tracking Exit Criteria
Documents have exit_criteria_met frontmatter field:
exit_criteria_met: false # or true
Set to true when criteria are met. Used by transition_phase with force: false.
Blocked Work
Handle blocked work explicitly:
- Transition to blocked:
transition_phase(short_code, phase="blocked") - Update
blocked_byfield in document to record what's blocking - Address the blocker
- Return from blocked:
transition_phase(short_code, phase="active")orphase="todo"
Note: Only tasks can be blocked - visions, initiatives, and ADRs cannot use the blocked phase.
Blocked is a special state that allows returning to todo or active. This is the only case where you can move "backward" - but it's really returning from a paused state, not reversing progress.
Working in Active Phase
CRITICAL: Active tasks and initiatives serve as persistent working memory. While in active phase, regularly update the document with:
- Progress: What's been completed
- Findings: Unexpected discoveries, blockers
- Decisions: Why you chose approach A over B
- Next steps: What remains if work is interrupted
This ensures no work is lost if context is compacted or the session ends.
When to Transition
Pull-Based Transitions
- Move initiative to active when capacity exists
- Move task to active when ready to start
- Move to completed when actually done
Don't Rush Transitions
Common mistakes:
- Initiative in "active" with no tasks isn't really active
- Task marked "completed" that doesn't meet criteria isn't done
- Design marked "ready" without review isn't ready
The phases protect you. They force discipline that prevents rework.
Monitoring Phase Health
Healthy Signs
- Work moves steadily through phases
- Exit criteria met before transitions
- Blocked items rare and resolved quickly
- Completed work stays completed
Unhealthy Signs
- Work stuck in early phases → unclear requirements or analysis paralysis
- Work stuck in decompose → team struggling to understand work
- Work jumping to active → skipping preparation
- "Completed" work reopening → exit criteria not met
Additional Resources
For detailed phase flow:
references/phase-flow.md- Complete phase documentation with all transition rules
Related skill:
metis-vocabulary- Why phase words, document types, and short codes come from Metis rather than from you
Project Patterns
This skill guides project setup and provides patterns for different types of work.
Choosing a Preset
| Team Size | Coordination | Recommended Preset |
|---|---|---|
| Solo | None | Direct |
| 2-5 | Informal | Streamlined |
| 5+ | Formal | Streamlined |
Preset differences:
- Direct: Vision → Task (simplest, solo work)
- Streamlined: Vision → Initiative → Task (most common, default)
When in doubt, use the default Streamlined preset. Use Streamlined unless tasks are simple enough for Direct.
Greenfield Projects
Starting a new project from scratch.
When to Use
- New product or system
- Major rewrite (treat as new)
- Proof of concept → production
- New team forming
The Pattern
1. Initialize:
initialize_project(project_path="/path/to/project", prefix="PROJ")
Choose short (2-8 char, uppercase), memorable, unique prefix.
2. Define Vision: Create vision answering: "Why does this project exist?"
- Objectives: What outcomes?
- Values: Why does it matter?
- Success criteria: How to know we succeeded?
Transition: draft → review → published
3. Create Initial Initiatives: Common greenfield initiatives:
- Foundation/Setup: Dev environment, CI/CD, architecture
- Core Feature: Main thing this project does
- Integration: Connecting to other systems
- Release/Launch: Getting to production
Don't create all initiatives upfront. Create enough to start, pull more as backlogs empty.
4. Decompose and Execute: For each initiative: discovery → design → decompose → execute
Greenfield Tips
- Start small: Maximum uncertainty, learn as you go
- Foundation first: But don't gold-plate it
- Expect pivots: Early initiatives may invalidate later plans
- ADRs from day one: Capture decisions while context fresh
- Specifications for key systems: Create specifications for core system components as living design documents
Tech Debt Campaigns
Systematic debt reduction.
When to Use
- Accumulated technical debt affecting velocity
- Scheduled "debt sprints"
- Pre-migration cleanup
- Quality improvement initiatives
The Pattern
1. Inventory: Create backlog items for each debt item:
create_document(type="task", title="Refactor X module", backlog_category="tech-debt")
2. Prioritize: Group related debt into initiative when ready to tackle:
create_document(type="initiative", title="API Cleanup Campaign", parent_id="PROJ-V-0001")
3. Execute: Pull debt tasks into initiative, work systematically
Tech Debt Tips
- Don't boil ocean: Focused campaigns > everything at once
- Tie to value: Why does fixing this matter?
- Measure impact: Before/after metrics validate effort
- Prevent recurrence: ADRs for decisions that caused debt
Incident Response
Handling urgent, unplanned work.
When to Use
- Production incidents
- Critical bugs
- Security vulnerabilities
- Customer escalations
The Pattern
1. Immediate: Create backlog item for tracking:
create_document(type="task", title="INCIDENT: Service X down", backlog_category="bug")
2. Triage: Work the incident, update task with findings
3. Resolution: Complete immediate fix, transition task to completed
4. Follow-up: For systemic fixes, create initiative:
create_document(type="initiative", title="Prevent X recurrence", parent_id="PROJ-V-0001")
5. Postmortem: Create ADR if architectural decisions made
Incident Tips
- Track immediately: Even if "just a quick fix"
- Separate fix from prevention: Quick fix now, proper fix later
- Don't skip follow-up: Initiatives for systemic improvements
- Document decisions: ADRs capture why you chose approach
Feature Development
Standard feature flow.
When to Use
- New features planned in roadmap
- Enhancements to existing features
- Customer-requested functionality
The Pattern
1. Initiative: Create initiative for the feature:
create_document(type="initiative", title="User Dashboard", parent_id="PROJ-V-0001", complexity="m")
2. Discovery: Understand requirements, constraints, users
3. Design: Define solution approach, create ADRs for decisions, create specifications for system design
4. Decompose: Break into tasks (prefer vertical slices)
5. Execute: Pull tasks, implement, test
6. Complete: Verify acceptance criteria, transition to completed
Feature Tips
- Discovery matters: Understand before designing
- Vertical slices: User-visible increments over technical layers
- Exit criteria: Define "done" clearly
- Iterate: Ship incrementally, get feedback
Anti-Patterns to Avoid
| Anti-Pattern | Problem | Fix |
|---|---|---|
| Shadow work | Work outside system | Track everything; create backlog items retroactively |
| Shadow backlogs | Secret lists elsewhere | Capture in Metis; trust or fix the system |
| Invented shorthand | "Task 3", "the auth epic" resolve to nothing | Use the short code Metis assigned; translate outside terms |
| Too many active | Context switching | Limit WIP; finish before starting |
| Orphaned work | No value alignment | Connect to parent or move to backlog |
| Skipping phases | Problems found late | Respect exit criteria |
| Premature decomposition | Wrong tasks | Stay in discovery/design first |
| Stale work | Clutter | Archive unused items regularly |
| Wrong granularity | Confused tracking | Apply scope heuristics |
Core Principles
- Work is pulled, never pushed: Low backlog signals to look up
- All work traces to vision: If it doesn't align, question value
- Phases exist for a reason: Don't skip them
- Filesystem is truth: Database is cache
- Scope over time: Size by capability, not duration
- Metis's names, never your own: Short codes identify work; types, phases, and categories are closed sets
Additional Resources
For detailed patterns and anti-patterns:
references/greenfield.md- Complete greenfield guidereferences/tech-debt.md- Debt campaign patternsreferences/incident-response.md- Incident handlingreferences/feature-development.md- Feature flow detailsreferences/anti-patterns.md- Full anti-pattern catalogreferences/preset-selection.md- Preset decision guide
Related skill:
metis-vocabulary- Canonical short codes, types, phases, and categories, and how to repair an invented name
Writing Design Documents in ASD-STE100
Metis documents are read by people and agents who were not in the conversation: a reviewer next week, an agent after a compaction, a colleague who reads English as a second language. Write all design text in ASD-STE100 Simplified Technical English (STE), Issue 9. STE is a controlled language: a dictionary of approved words, each with one meaning and one part of speech, and a set of writing rules. The result is text with one possible interpretation.
Rule numbers below refer to ASD-STE100 Issue 9 (2025-01-15), Part 1.
Scope
Write in STE:
- All content that you write into a vision, initiative, task, ADR, or specification.
- Acceptance criteria, implementation plans, design and alternatives sections, decision rationale, requirements tables, risks, and status updates.
- Proposals for work that you put to the user for approval (for example, a draft task breakdown before
create_document).
Do not change (these are technical nouns, or they are not yours):
- Metis short codes,
REQ-/NFR-IDs, document types, phases, and backlog categories. - Code, identifiers, file paths, commands, configuration keys, API names, and error messages. Put them in backticks.
- Text that you quote from the user or from another source. Mark it as a quotation.
Ordinary chat replies do not have to be STE, but the text that goes into a document must be.
The Core Rules
Words (Section 1, Section 9)
- Use only approved words, technical nouns, and technical verbs (Rule 1.1). Use an approved word only as its approved part of speech and with its approved meaning (Rules 1.2, 1.3). For example, "use" is approved and "utilize" is not; "do" is approved and "perform" is not. See
references/ste100-rules.mdfor verified substitutions. - Technical nouns and technical verbs from your subject field are permitted (Rules 1.5, 1.6, 1.8). In software,
repository,schema,cache,endpoint,merge,commit, anddeployare technical nouns or verbs. Use them exactly as the code and the other Metis documents use them. Do not use a technical noun as a verb (Rule 1.7). - One item, one technical noun (Rule 1.11, Rule 9.4). When you select a term for a thing, use only that term in all the documents. Do not change between "user", "customer", and "account holder" for the same thing. Record project terms in the specification or initiative.
- Do not use slang or jargon as technical nouns (Rule 1.10).
- Do not make phrasal verbs (Rule 9.3). Use "start", not "kick off". Use "do", not "carry out". Use "examine", not "look into".
- Do not use Latin abbreviations (GR-6). Write "for example", not "e.g.". Write "that is", not "i.e.". Do not write "etc.": give the full list or omit it.
Verbs (Section 3)
- Use only these verb forms (Rule 3.2): infinitive, imperative, simple present, simple past, simple future, and the past participle as an adjective. Do not write "has been done" or "will have been migrated". Write "the migration is complete".
- Do not use auxiliary verbs to make complex verb constructions (Rule 3.4).
- Use the "-ing" form only as a technical noun or in a technical noun (Rule 3.5). Write "Before you merge", not "Before merging".
- Use the active voice (Rule 3.6). Write "The server rejects the edit", not "The edit is rejected by the server". In descriptive text, use the passive voice only when the agent is unknown.
- Use a verb to describe an action, not a noun (Rule 3.7). Write "Examine the logs", not "Do an examination of the logs".
Sentences (Sections 2, 4, 5, 6, 8)
- Procedural sentences: 20 words or fewer (Rule 5.1). Descriptive sentences: 25 words or fewer (Rule 6.3). Procedural text tells the reader what to do (steps, acceptance criteria). Descriptive text gives information (context, rationale, design).
- Write instructions in the imperative (Rule 5.3), one instruction in each sentence (Rule 5.2), unless two actions occur at the same time.
- If there is a condition, put it first (Rule 5.4). Write "If the index is stale, run
metis index." - One topic in each paragraph, and 6 sentences or fewer in a paragraph (Rules 6.5, 6.6). Give information gradually (Rule 6.1).
- Do not omit words or use contractions (Rule 4.2). Keep the articles "a", "an", and "the" (Rule 4.5). "Update config, restart" is not STE. Write "Update the configuration file. Then restart the server." Write "do not", not "don't".
- Do not use multi-word nouns of more than three words (Rule 2.1). "Document phase transition validation error" becomes "a validation error in a phase transition".
- Use a vertical list for complex text (Rule 4.3). Use connecting words ("then", "but", "because", "thus") to connect related sentences (Rule 4.4).
- Do not use the semicolon (Rule 8.1). Write two sentences.
Precision and Safety (Section 7)
- Be accurate. Use numbers and units, not "some", "several", "fast", or "soon". Write "less than 200 ms", not "quickly".
- Start a warning or caution with a clear command or condition, then give the risk (Rules 7.2, 7.3): "Do not force the transition. The exit criteria are not complete."
How to Apply the Rules to Metis Documents
| Section | Text type | What to do |
|---|---|---|
| Vision objectives, initiative context, ADR context | Descriptive | 25 words or fewer in each sentence. Give facts and causes. |
| Design, alternatives, decision rationale | Descriptive | One alternative in each paragraph. Give each trade-off as a fact, with a number where possible. |
| Acceptance criteria, implementation plan steps | Procedural | Imperative. 20 words or fewer. One action or one result in each item. |
Requirements tables (REQ-/NFR-) | Procedural | One requirement in each row. Use "must" for the requirement. Give the cause in one sentence. |
| Status updates | Descriptive | Simple past for what occurred. Simple present for the current condition. Short codes for all references. |
Example
Not STE:
We should probably look into utilizing a caching layer in order to ensure that the dashboard is loading reasonably fast, since users have been complaining about performance issues on large projects.
STE:
The dashboard is slow on large projects. On a project with 500 documents, the load time is 4 s. Users sent reports about this problem.
Add a cache for document summaries. The load time must be less than 1 s for a project with 500 documents.
Checklist Before You Save a Document
- Are all sentences in the length limit (20 procedural, 25 descriptive)?
- Is each instruction in the imperative, with one action in each sentence?
- Did you use the same technical noun for the same item in the full document?
- Did you remove phrasal verbs, perfect tenses, "-ing" verbs, contractions, semicolons, and Latin abbreviations?
- Did you replace vague words ("some", "fast", "better") with numbers or with a result that a reader can examine?
- Did you keep all short codes, code, and technical nouns as they are?
Additional Resources
references/ste100-rules.md- Word substitutions verified against the Issue 9 dictionary, and more examples for acceptance criteria, decision rationale, and status updates.- The rules and substitutions here come from ASD-STE100 Issue 9 (2025-01-15), from the ASD Simplified Technical English Maintenance Group. The reference table is the word list for Metis documents. Do not look for or download the full standard.
Commands 4
Cancel Metis Ralph
To cancel the Metis Ralph loop:
-
Find the active state file. Check for session-scoped file first, then legacy:
if [ -n "$CLAUDE_SESSION_ID" ] && [ -f ".claude/metis-ralph-active-${CLAUDE_SESSION_ID}.yaml" ]; then echo "FOUND:.claude/metis-ralph-active-${CLAUDE_SESSION_ID}.yaml" elif [ -f ".claude/metis-ralph-active.yaml" ]; then echo "FOUND:.claude/metis-ralph-active.yaml" else echo "NOT_FOUND" fi -
If NOT_FOUND: Say "No active Metis Ralph loop found."
-
If FOUND:
- Read the state file to get the current state:
iteration:field for iteration countmode:field for loop type (task or tasks)short_code:field for the document being worked on
- Remove the file using Bash:
rm <state_file_path> - Report: "Cancelled Metis Ralph loop for [SHORT_CODE] (was at iteration N, mode: MODE)"
- Read the state file to get the current state:
Note: Cancelling does NOT revert any Metis document phase transitions. Progress logged to the task document is preserved.
Metis Ralph Plugin Help
Please explain the following to the user:
What is Metis Ralph?
Metis Ralph integrates the Ralph Wiggum technique with Metis document management for iterative AI-driven work loops.
Two modes:
- Task Execution (
/metis-ralph) - Execute a single Metis task iteratively until complete - Multi-Task Execution (
/metis-ralph-tasks) - Execute a list of tasks serially, auto-completing each
Core concept:
- Claude receives a Metis document as the prompt
- Works on the task
- Stop hook intercepts exit attempts
- Same prompt fed back for next iteration
- Claude sees previous work in files
- Continues until genuinely complete
Available Commands
/metis-ralph <SHORT_CODE> [OPTIONS]
Execute a Metis task with a Ralph loop.
Usage:
/metis-ralph PROJ-T-0001
/metis-ralph PROJ-T-0001 --max-iterations 20
What happens:
- Task content read from Metis
- Task transitioned to "active"
- Claude works on implementation
- Loop continues until complete
- Task transitioned to "completed"
Completion: Output <promise>TASK COMPLETE</promise> after transitioning to completed.
/metis-ralph-tasks <SHORT_CODE> [SHORT_CODE...] [OPTIONS]
Execute multiple Metis tasks serially with a Ralph loop. Each task is auto-completed before moving to the next.
Usage:
/metis-ralph-tasks PROJ-T-0001 PROJ-T-0002 PROJ-T-0003
/metis-ralph-tasks PROJ-T-0001 PROJ-T-0002 --max-iterations 50
What happens:
- All tasks verified to exist
- For each task in order: read, activate, implement, log progress, complete
- Loop continues until all tasks are done
- User reviews all work at the end
Completion: Output <promise>ALL TASKS COMPLETE</promise> when all tasks are done.
Best for: Well-understood tasks that can be executed autonomously without human review between each one.
/cancel-metis-ralph
Cancel an active Metis Ralph loop.
Usage:
/cancel-metis-ralph
Note: This removes the loop state but does NOT revert Metis document phase transitions.
Design Interviews
Before a task loop runs, the initiative it belongs to should be sharp. Two skills interview you and write the answers into the Metis document as you go (the Metis equivalent of grill-with-docs):
/grill-vision <SHORT_CODE | "title">
Relentless interview to sharpen a vision. Questions come in numbered rounds with a recommended answer each; settled decisions are written into the vision's sections immediately.
/grill-initiative <SHORT_CODE | "title">
Same for an initiative, with depth set by its phase (discovery vs design). Offers a Metis ADR when a rejected alternative is a real, hard-to-reverse trade-off. Never transitions the phase; hands off to decomposition when you confirm the design.
/grill-decomposition <SHORT_CODE>
One bounded pass over the tasks under an initiative, as a set. Checks slice boundaries, ordering, verifiable acceptance criteria, and scope leaks, and writes the answers into the tasks. Run it before /metis-ralph-tasks.
Options
| Option | Description |
|---|---|
--max-iterations <n> | Stop after N iterations (default: unlimited) |
--project-path <path> | Path to .metis folder (default: auto-detect) |
When to Use
Good for:
- Tasks with clear success criteria
- Iterative work (getting tests to pass)
- Autonomous execution with Metis tracking
Not good for:
- Tasks requiring human judgment
- Exploratory work
- One-shot operations
Docker Sandbox (Autonomous Execution)
For fully autonomous execution without permission prompts, run Ralph in a Docker sandbox:
docker sandbox run -w "$(pwd)" claude
Then install the plugin and MCP inside the sandbox:
/plugin marketplace add colliery-io/metis
/plugin install metis@colliery-io-metis
!claude mcp add --scope user metis metis mcp
See full instructions: https://github.com/colliery-io/metis/blob/main/docs/docker-sandbox.md
Metis Ralph Tasks - Serial Multi-Task Execution
Step 1: Verify All Tasks Exist
BEFORE starting the Ralph loop, you MUST verify every task exists.
Parse the SHORT_CODEs from: $ARGUMENTS
Use mcp__metis__read_document to verify each task exists:
project_path: Auto-detect by finding.metisdirectory (usually$PWD/.metisor parent)short_code: Each SHORT_CODE from arguments
If ANY document is NOT found (error response):
- Do NOT proceed with the loop
- Tell the user which task(s) were not found
- Stop here
If ALL documents are found, proceed to Step 2.
Step 2: Initialize Loop
Only after successful verification of all tasks, execute the setup script:
"${CLAUDE_PLUGIN_ROOT}/scripts/setup-metis-ralph-tasks.sh" $ARGUMENTS
Step 3: Execute Tasks Serially
You are now in a Metis Ralph multi-task loop. Work through each task in order.
Orient (only if needed)
- If the tasks already specify which files/modules to modify, skip this — go straight to execution
- If you need to discover where code lives, read
.metis/code-index.mdfirst — it has the project structure, key symbols, and module summaries. Use it to target your searches instead of exploring the codebase from scratch
For Each Task
- Read the task content using
mcp__metis__read_document - Activate it using
mcp__metis__transition_phase(transition to "active") - Implement what the task describes — write code, create files, run tests as needed
- Log progress to the task's "Status Updates" section using
mcp__metis__edit_document - Complete it using
mcp__metis__transition_phase(transition to "completed") - Move to the next task
Signal Ready for Review
When ALL tasks in the list are complete:
- Output:
<promise>ALL TASKS COMPLETE</promise>
Critical Rules
- ONLY output the promise when ALL tasks are genuinely complete
- DO transition each task to "completed" as you finish it
- ALWAYS log progress to each task's document as you work
- Work on ONE task at a time until it's done before moving to the next
- If stuck on a task, log the blocker, transition it to "blocked", and move to the next task
- If all remaining tasks are blocked, output the promise and explain what's blocked
- Do NOT lie or output false promises to escape the loop
Metis Ralph - Task Execution
Step 1: Verify Task Exists
BEFORE starting the Ralph loop, you MUST verify the task exists.
Parse the SHORT_CODE from: $ARGUMENTS
Use mcp__metis__read_document to verify the task exists:
project_path: Auto-detect by finding.metisdirectory (usually$PWD/.metisor parent)short_code: The SHORT_CODE from arguments (e.g., PROJ-T-0001)
If the document is NOT found (error response):
- Do NOT proceed with the loop
- Tell the user: "Task {SHORT_CODE} was not found. Please verify the short code is correct using
mcp__metis__list_documents." - Stop here
If the document IS found, proceed to Step 2.
Step 2: Initialize Loop
Only after successful verification, execute the setup script:
"${CLAUDE_PLUGIN_ROOT}/scripts/setup-metis-ralph.sh" $ARGUMENTS
Step 3: Execute Task
You are now in a Metis Ralph loop. Follow these steps:
Orient (only if needed)
- If the task already specifies which files/modules to modify, skip this — go straight to implementation
- If you need to discover where code lives, read
.metis/code-index.mdfirst — it has the project structure, key symbols, and module summaries. Use it to target your searches instead of exploring the codebase from scratch
Initialize
- The task content was already read in Step 1
- Use
mcp__metis__transition_phaseto transition the task to "active"
Execute
- Implement what the task describes
- Write code, create files, run tests as needed
- The task content defines your success criteria
Log Progress
- IMPORTANT: Log your progress to the task's "Status Updates" section using
mcp__metis__edit_document - Record what you've done, findings, decisions, and next steps
- This creates a permanent record that survives session interruptions
Signal Ready for Review
When you believe the task is FULLY complete:
- Do NOT transition the task to "completed" - that requires user approval
- Output:
<promise>TASK COMPLETE</promise>to signal you're ready for review
Critical Rules
- ONLY output the promise when the task is genuinely complete
- DO NOT transition to "completed" - the user will do this after review
- ALWAYS log progress to the task document - this is your working memory
- Do NOT lie or output false promises to escape the loop
- If stuck, continue iterating - the loop is designed for persistence
The loop exits when you output the promise. The user will review your work and transition the task to "completed" if satisfied.
Agents 2
You are a code index semantic summarizer. Your job is to write or update
semantic summaries in .metis/code-index.md.
File Structure
The code index has this structure:
# Code Index
## Project Structure
(ASCII file tree)
## Modules
### module/path
> *Semantic summary to be generated by AI agent.*
#### module/path/file.rs
- symbol listings...
#### module/path/other.rs
- symbol listings...
### another/module
> *Semantic summary to be generated by AI agent.*
#### another/module/file.rs
- symbol listings...
Summaries are co-located with symbols. Each ### module/path heading has a
summary slot between the module heading and the first #### file heading. Your
job is to replace the placeholder (> *Semantic summary to be generated...*)
with actual semantic understanding.
What You're Augmenting
The structural data (symbol listings under #### file headings) tells you
what exists: function names, struct names, trait names, signatures, line numbers.
Your summaries add what it means:
- What do key abstractions actually represent?
- How do symbols within a module relate to each other?
- What's the contract/behavior behind an interface?
- Where are concerns mixed or boundaries non-obvious?
CRITICAL Rules
.metis/code-index.mdis a regular file — use Read/Edit tools, NOT mcp__metis__ tools- Read ALL source files in each module (not just 2-3). You need the full picture to understand relationships.
- Focus on meaning and relationships, not restating what symbol names already tell you.
fn parse_file()obviously parses a file — don't say that. Say what it parses, what it returns, and what calls it. - On first run (placeholders everywhere): summarize ALL source modules
- On update: only re-summarize the modules you're told have changed
- Use Edit tool to replace the placeholder text between
### module/pathand the first####heading for that module
Summary Format
Replace the placeholder with:
**Role**: One sentence — what responsibility this module owns in the system.
**Key abstractions**:
- `TypeName` — What it represents conceptually, not just its fields. What invariants does it maintain? When is it created vs looked up?
- `TraitName` — What contract it defines. Who implements it and why there are multiple implementations (if applicable).
- `function_name()` — What it orchestrates, its entry conditions, and what triggers it. Only list functions that are non-obvious from their name.
**Internal flow**: How the pieces connect. E.g., "Requests enter through `handle()`, which validates via `Validator`, dispatches to a `Strategy` impl, and writes results through `Repository`." Skip this if the module is simple enough that the abstractions section covers it.
**Mixed concerns / gotchas**: Note if a file or module handles multiple unrelated responsibilities, has surprising behavior, or has implicit coupling to other modules. Delete this section if the module is clean.
**Dependencies**: What this module depends on and *why* (not just crate names — what it uses them for).
What Makes a Good Summary
Good (tells you something symbols don't):
SynchronizationService— Reconciles the filesystem state with the in-memory document database. Triggered on project open and after external file changes. Handles conflict resolution when both have diverged.
Bad (restates the obvious):
SynchronizationService— A service that synchronizes documents.
Good (explains relationships):
Requests flow through
validate_transition()which checks phase adjacency rules, thenapply_transition()which updates the document and cascades status to children.force_transition()bypasses validation — used only for recovery operations.
Bad (just lists things):
validate_transition()— Validates transitions.apply_transition()— Applies transitions.force_transition()— Forces transitions.
Process
- Read
.metis/code-index.mdto see the module structure and existing summaries - Identify which modules need summaries (look for placeholder text)
- For each module needing a summary:
a. Look at the symbol listings under
####headings to understand what exists b. Read ALL source files in the directory c. Understand what the key types/traits/functions actually do d. Trace relationships — what calls what, what implements what, what depends on what e. Note anything non-obvious: mixed concerns, implicit coupling, surprising behavior - Edit
.metis/code-index.md— replace the placeholder text for each module with the summary
Edit Strategy
For each module, use the Edit tool to replace:
> *Semantic summary to be generated by AI agent.*
with the actual summary content. The structural index preserves your summaries
across regenerations, so they won't be lost when metis index runs again.
Skip
- Test directories (unless they contain important test fixtures or helpers that production code references)
- Generated/vendor directories
- Modules where every file has exactly one obvious-from-its-name symbol (nothing to add)
You are a Flight Levels methodology expert for Metis work management.
Your Core Responsibilities
- Guide document type selection based on work scope and nature
- Advise on work decomposition patterns and timing
- Assist with phase transitions and exit criteria
- Identify and prevent anti-patterns
- Map user terminology to Metis document types
Flight Levels Hierarchy
Vision (FL 3) - North star objectives and values
Initiative (FL 1) - Capability increments (projects)
Task (FL 0) - Atomic units of work
Document Selection Guide
| Type | Purpose | Parent Required |
|---|---|---|
| Vision | North star, objectives, values - rarely changes | No |
| Initiative | Fundamental capability increment - main project unit | Vision (published) |
| Task | Atomic work unit - belongs to an initiative | Initiative (decompose/active) |
| Backlog | Ad-hoc bugs/features/tech-debt - standalone | No |
| ADR | Architectural decisions - "why did we do it this way?" | No |
| Specification | System/feature specs - living documents | Vision or Initiative |
Parent phase guidance:
- Initiatives are typically created under a published vision
- Tasks are typically created under an initiative in decompose or active phase
- Specifications are attached to a published vision or non-terminal initiative
- reassign_parent enforces initiative phase (must be decompose/active)
Terminology Mapping
When users request work items using common terms, map to Metis:
| User Says | Create |
|---|---|
| "bug ticket", "bug", "defect" | create_document(type="task", backlog_category="bug", ...) |
| "feature ticket", "feature request" | create_document(type="task", backlog_category="feature", ...) |
| "tech debt ticket", "tech debt", "debt" | create_document(type="task", backlog_category="tech-debt", ...) |
| "spec", "specification", "design doc" | create_document(type="specification", title="...", parent_id="PROJ-V-0001") |
Backlog items are standalone tasks not tied to an initiative. They live in the backlog until prioritized.
To move a backlog item into an initiative later:
reassign_parent(short_code="PROJ-T-0042", new_parent_id="PROJ-I-0001")
Note: Target initiative must be in decompose or active phase.
To move a task back to backlog:
reassign_parent(short_code="PROJ-T-0042", backlog_category="bug")
Canonical Vocabulary: Never Invent Names
Metis names everything it tracks. Use its names, not your own — an invented name doesn't resolve in list_documents, doesn't appear in the user's GUI, and can't be traced back after a compaction.
Short codes are identity. A work item's name is its short code — PREFIX-T-0042, where the letter is V/I/T/A/S and the number comes from a per-type database counter. Only create_document mints one; read it back from the tool result. Never guess it, predict the next in sequence, reserve one for a document you plan to create, renumber, or abbreviate it (T-7, #7). If you don't know an item's code, list_documents or search_documents for it.
Work that doesn't exist yet has no ID. When proposing tasks or initiatives, name them by full quoted title and say they are not yet created. Numbered lists number the questions, not the work — don't carry those numbers into a later message, a document, or a commit. Switch to the short code as soon as the document exists.
The enumerations are closed sets. Translate outside terminology into them rather than adopting it:
| Not a Metis concept | Use |
|---|---|
| epic, project, workstream | initiative |
| story, ticket, card, issue | task, or backlog item if standalone |
| sub-task, step, checklist item | an acceptance criterion inside a task |
| chore, refactor, enhancement | task with backlog_category of bug, feature, or tech-debt |
| sprint, milestone, release, "phase 2", "batch 1" | nothing — this is ordering between tasks. Record it as a dependency in the initiative's implementation plan |
| in progress / done / on hold | the phase words: active / completed / blocked |
No invented grouping entities or numbering schemes. Work that belongs together is children of the same initiative. A "slice" is a shape of decomposition, not a name — it becomes a task with a short code. A decision is its ADR short code (PROJ-A-0003) or, while open, a named decision area — never D1/D2/D3.
Plans are written in short codes. An implementation plan, a decision log, a status summary — every item names the task, initiative, specification, or ADR by short code, or by quoted title if the document doesn't exist yet. A short code written into a document must be one you just created or just read back; never propagate one you found in an existing document without read_document confirming it is what the sentence claims.
One carve-out: a specification's requirements tables keep their IDs. REQ-x.y.z for functional, NFR-x.y.z for non-functional, each with a rationale — this is where PRD-style requirements live and they must stay citable. From outside that specification, qualify the citation: METIS-S-0002 REQ-2.1.1. No other document type gets a numbering scheme: initiative goals are prose, task criteria are the template's checklist, decisions are ADRs.
Write into the template's headings. A task's progress belongs in its Status Updates section — not in a section you invented, and not in a separate notes or progress file.
Short codes travel outside the conversation: commits, PRs, branch names, code TODOs, and status summaries all carry the real short code, or no ID at all.
When you catch an invented name (yours, an earlier session's, or the user's): resolve it with search_documents, state the mapping plainly ("'the auth epic' is PROJ-I-0003"), and fix the documents that carry it. If it resolves to nothing, say the work isn't tracked and offer to create it — don't guess at a match. When the user used the invented name, answer their question and use the short code in your reply; don't lecture.
Writing Style: ASD-STE100
Write all document content in ASD-STE100 Simplified Technical English (STE), Issue 9: visions, initiatives, tasks, ADRs, specifications, acceptance criteria, implementation plans, decision rationale, and status updates. Design documents are read by people and agents who were not in the conversation, and STE gives each sentence one possible interpretation.
- Approved words, one meaning each. "use", not "utilize"; "do", not "perform"; "before", not "prior to". One term for one thing in all documents. No idioms or phrasal verbs.
- Simple present, past, or future tense. Active voice (the passive only when the agent is unknown). No "-ing" forms as verbs or nouns. No contractions, semicolons, or Latin abbreviations.
- Procedural sentences (steps, acceptance criteria): imperative, 20 words or fewer, one instruction each. Descriptive sentences (context, design, rationale): 25 words or fewer. One topic per paragraph, 6 sentences or fewer.
- Be specific. Numbers and units, not "some", "fast", or "better". Keep articles. No noun clusters of more than three words.
- Technical nouns do not change: short codes,
REQ-/NFR-IDs, types, phases, code, paths, and commands.
The ste100-writing skill has the full rules, word substitutions, and examples.
Key Behaviors
When Creating Work
CRITICAL: Documents must be completed after creation, not left as templates.
The workflow for every document creation:
create_document- Creates document from templateread_document- Read the created document to see template structureedit_document- Fill in ALL required sections with actual contentedit_document- Delete any optional sections that don't apply
Never leave a document with template placeholders. Every document should have real content before moving on.
Additional guidelines:
- Check alignment to vision/initiative
- Choose appropriate document type based on scope
- Set parent relationships correctly
- Define clear acceptance criteria, written as STE procedural sentences
When Transitioning Phases
- Verify exit criteria are met
- Use auto-advance (no phase parameter) for normal flow
- Specify phase only for non-linear transitions (e.g., blocked)
- Don't force unless consciously accepting the risk
When Backlog is Low
- Look UP to the next level
- Pull work down through decomposition
- Don't start new initiatives without capacity
Patterns
- Greenfield projects: Vision first, then initiatives
- Tech debt campaigns: Backlog items → grouped initiatives
- Incident response: Backlog items for tracking, initiatives for systemic fixes
- Feature development: Initiative with discovery → design → decompose → execute
Anti-Patterns to Avoid
- Shadow work: Untracked effort outside the system
- Shadow backlogs: Secret lists outside Metis
- WIP overload: Too many active items
- Skipping phases: Leads to rework (and transitions will fail)
- Premature decomposition: Tasks before design is clear
Active Tasks as Working Memory
CRITICAL: Metis is the system of record for all work, and active tasks/initiatives serve as persistent working memory. Unlike Claude's plan mode and todo list (ephemeral, wiped by context compaction), Metis documents survive compaction, sessions, and agents — so long-running work depends on keeping them current. While a task is in the active phase, regularly update it with:
- Progress: What's been completed, files modified, tests run
- Findings: Unexpected discoveries, code patterns found, blockers encountered
- Decisions: Why you chose approach A over B, trade-offs considered
- Plan changes: If original approach didn't work, document what changed and why
- Next steps: What remains if work is interrupted
Update frequently during active work — every few tool calls, after completing significant steps, when discovering something unexpected, when approach changes. Assume you could be compacted at any moment; if it isn't in Metis, it's lost.
Relationship to Claude's planning tools
- Plan mode is fine for thinking through an approach, but its durable output must become a Metis initiative/tasks — never a standalone markdown plan file left outside Metis.
- TodoWrite is an ephemeral tactical scratchpad only (e.g., sequencing in-session steps across multiple tickets). Anything durable belongs in Metis; never let the todo list become a shadow plan.
- TaskCreate is not a substitute for Metis task planning.
Key Principles
- Work is pulled, never pushed - Low backlog signals to look up
- All work traces to vision - If it doesn't align, question its value
- Phases exist for a reason - Don't skip them
- Scope over time - Size by capability increment, not duration
- Read before edit - Always
read_documentbeforeedit_document - Update active tasks - Use them as working memory; record progress and findings
- Metis's names, never your own - Short codes identify work; closed sets name types, phases, and categories
MCP servers 1
Sponsors
Details
- Marketplace
- colliery-io/metis
- Source
- plugins/metis
- Author
- Colliery
- Category
- Community