// Create or update a concept capsule — the conceptual anchor for a project or feature area. Use before writing code on a new project or feature, or when terms and boundaries feel unclear. Defines glossary, invariants, happy-path scenario, and non-goals.
| name | capsule |
| description | Create or update a concept capsule — the conceptual anchor for a project or feature area. Use before writing code on a new project or feature, or when terms and boundaries feel unclear. Defines glossary, invariants, happy-path scenario, and non-goals. |
| argument-hint | [project or feature area to define] |
Create a concept capsule — a short, precise document that anchors all subsequent work to a shared vocabulary (ubiquitous language, DDD) and a set of constraints (design by contract).
The capsule is the durable semantic authority for a project or feature area. It should change slowly after initial establishment.
Use the capsule for durable conceptual truths only:
Do not use the capsule for:
The project or feature area: $ARGUMENTS
If the user hasn't described the domain clearly enough, interview them:
Write a document with exactly these four sections. Keep it to one screen (~250-500 words). Each bullet should be one sentence.
5-15 domain terms with their exact intended meanings in this project. These are the names that must appear in code — types, functions, modules, test suites.
Format:
- **Term**: Definition (one sentence)
3-10 statements that must always be true. Constraints, not features.
Format:
- An X must always have a Y
- X can never be Z while W is true
A single concrete input → output story. This becomes the first integration test.
Format:
Given: [concrete starting state]
When: [concrete action]
Then: [concrete observable result]
Must be specific ("Given a file post.md with front-matter...", not "Given some input...").
Two things this project or feature explicitly will not do. These prevent scope creep and stop the agent from "helpfully" adding features.
Format:
- This will NOT do X (because Y)
- This will NOT do Z (because W)
These are deliberate exclusions, not "not yet" items.
Update a capsule when one of these is true:
Do not append changelogs, progress logs, milestone status, or decision journals inside the capsule.
When an assumption stabilizes into a durable law, promote it from
docs/assumptions.md into capsule invariants and track enforcement via
/pragma:contract.
docs/capsule.md for project-leveldocs/capsule-<feature>.md for feature-levelAfter writing, check:
If any check fails, revise before proceeding.
Append to the response:
foundation/pragma:skeleton/pragma:consult (default unless user explicitly continues directly)Read and write a Petri net (SDCPN) document by Automerge URL. Use when creating, editing, or querying Petri nets — adding or removing places, transitions, arcs, color types, differential equations, and parameters.
Create and maintain an Assumption Ledger — a persistent record of assumptions, their confidence, and validation status. Use when starting a new slice, resuming work in a new context window, or when implicit assumptions risk causing drift. Tracks requirements, architecture, and implementation assumptions.
Write a tracer-bullet card — a precise specification for one thin end-to-end slice of work. Use when scoping a new slice, defining what to build next, or breaking a feature into provable increments. Covers target behavior, boundary crossings, risks, and definition of done.
Create characterization tests (Golden Master) for existing code so you can refactor or replace safely. Use before refactoring, strangler-replacing, or modifying code with unclear behavior. Captures observable behavior with a minimal harness, producing tests, fixtures, and a coverage report.
Methodology triage consultant for tracer-bullet development. Use when unsure which pragma skill to run next, when starting a new project, or when the current approach feels stuck. Interviews the user, assesses state, and recommends the next pragma skill.
Turn capsule invariants and boundary crossings into executable contracts. Use after creating a concept capsule, or when invariants need to be enforced in code. Covers preconditions, postconditions, constructor validation, domain types, and contract tests.