Plain-English definitions for every term used in this cookbook. If you encounter a word you don’t know while reading the guides, look it up here first.
Tip: Terms link to the guide where they are used in context. You don’t need to read everything — look up what you need, then follow the link.
The specific, testable conditions that prove a feature is complete. Written as “Given / When / Then” statements in spec.md. If you can’t write an automated test for a criterion, it’s not specific enough.
Example: “Given a user submits a login form with correct credentials, when the server processes it, then a
tokencookie is set and the response is 200.”
See Greenfield Guide
SKILL.md)A folder that packages one reusable ability for an agent. It contains a SKILL.md file — a short YAML header with a name and a description, then Markdown instructions — plus optional helper scripts and reference files. The same folder works across Claude Code, Cursor, Codex, Copilot and other tools, because the format is an open specification.
Example: a
release-notesskill that tells the agent how to turn a git log into a changelog.
See Agent Standards
A plain Markdown file at the root of a repository that tells any coding agent how to work in that project — how to install, how to run the tests, which folders are off limits. It is read at the start of every session, so it should stay short. Governed by the Agentic AI Foundation under the Linux Foundation.
See Agent Standards
An AI model (such as Claude Code, Cursor, or GitHub Copilot) that can read files, write code, run commands, and make decisions — all within a defined scope. In this cookbook, agents are given specific roles and constraints so they behave predictably.
See AGENTS.md
A software development approach where AI agents write the majority of the implementation code (~75%), while humans define intent, approve specs, and verify outcomes. Your role shifts from code author to intent definer and outcomes verifier.
See README.md
When something goes wrong, the response focuses on why the system failed (unclear spec? missing gate? weak test?) — not on who caused it. Every failure becomes a learning input that improves the spec, gates, or guidelines. No blame, only system improvement.
Working in an existing codebase that already has running code, tests, and data. The key challenge is making changes without breaking what already works. Contrast with Greenfield.
The agent role responsible for executing the TDD loop (RED → GREEN → REFACTOR) for each task in tasks.md. Writes minimum code to pass tests, nothing more.
See AGENTS.md
An interactive session run via /speckit.clarify where Spec-Kit asks targeted questions about the spec to remove ambiguities before implementation begins. Answers are appended to spec.md.
Example: “What are the pre-defined expense categories? Or can users create custom ones?”
See Greenfield Guide
constitution.md)A project-level rules file (at .specify/memory/constitution.md) that defines the tech stack, forbidden actions, protected paths, and constraints that all agents must obey. It is the highest-authority document in the workflow — it overrides everything except a direct human instruction.
Example: “Tech stack: Node.js 20, Express 4.x. Do not modify:
src/database/migrations/.”
A specification written for a brownfield project that describes only the change being made — not a full system description. Focuses on what is being added, modified, or removed, and how it must remain backward-compatible with existing behavior.
An eval is an automated check on the quality of a model’s output, as opposed to a test that checks whether code runs. It works from a golden dataset: a fixed list of inputs paired with what a good answer looks like. Running the eval scores every case, so you can tell whether a prompt or model change made things better or worse. Ten real cases taken from actual failures are worth more than a thousand invented ones.
See Evaluation & Observability
The append-only journal at .ai/traces/AGENT_LOG_REFLECTIONS.md where agents record what happened after every implementation session: outcome (COMPLETE / PARTIAL / BLOCKED), frictions encountered, and suggested improvements. Never overwritten — always appended.
The feedback loop that makes the development process smarter over time: execution → log → verify → learn → refine → next execution. Each failure logged becomes a system improvement that prevents the same failure from recurring.
The four sequential verification gates that code must pass before merging:
Adding features, abstractions, or complexity beyond what the spec requires. Strictly prohibited. A smaller, correct implementation always beats a larger, unrequested one.
The second phase of the TDD loop. Write the minimum code required to make the failing test pass. Nothing more — no extra features, no early abstractions. See also: RED phase, REFACTOR phase.
Starting a brand-new project or feature from an empty directory with no existing code or tests. Contrast with Brownfield.
A specific text block you paste into your coding agent’s chat interface to transfer control from Spec-Kit (planning) to Superpowers (execution). It tells the agent which tasks.md to follow and what constraints to obey — critically, it prevents the agent from re-creating the plan or the git branch.
See Greenfield Guide
Using a second AI model to score the output of the first — useful for qualities a regular expression cannot express, such as tone or reasoning quality. Judges are systematically optimistic, so before trusting one you must calibrate it: have a human label about 50 outputs, run the judge on the same 50, and check how often they agree. An uncalibrated judge measures the judge, not your product.
See Evaluation & Observability
An open standard that lets an agent call tools and read data living outside itself — a database, a ticket tracker, an internal API. You write one MCP server for your system and every MCP-capable client can use it. Since the 2026-07-28 revision the protocol is stateless: there is no session handshake, so a server is an ordinary HTTP service that scales like any other. Governed by the Agentic AI Foundation under the Linux Foundation.
See Agent Standards
Recording what an agent actually did during a run. One run produces one trace, made up of spans — one per step (each model call, each tool call) with its duration, token count and cost. Observability tells you what happened; an eval tells you whether it was good. You need both, in that order.
See Evaluation & Observability
The agent role that manages routing between other roles. It loads context at session start, enforces the Spec-Kit → Superpowers handoff boundary, and escalates blocked states to the human.
See AGENTS.md
A task marked [x] in tasks.md with no corresponding code commit. The task appears done but no implementation exists. Caught by the Verifier role using Verify Tasks extension.
plan.md)A technical design document generated by /speckit.plan that describes which files will be created or modified and why, based on the approved spec. It is the bridge between the spec (what to build) and the tasks checklist (how to build it step by step).
See Greenfield Guide
The agent role responsible for translating a human’s idea into a verified spec.md with testable acceptance criteria. Runs clarification Q&A to flush ambiguities before planning begins.
See AGENTS.md
The three-stage loading model that makes agent skills cheap to keep installed. Stage 1: only the skill’s name and description stay in the agent’s context — around a hundred tokens each. Stage 2: the SKILL.md body loads only when a task matches that description. Stage 3: bundled scripts and reference files load only if the body points to them. This is why you can install fifty skills and pay for almost none of them.
See Agent Standards
The first phase of the TDD loop. Write a test that fails — before writing any implementation code. A test that doesn’t fail first proves nothing; it may be testing the wrong thing or nothing at all.
The third phase of the TDD loop. Clean up the code — improve naming, remove duplication, simplify logic — while keeping all tests green. No new behavior is added during refactor.
The agent role that performs two-stage review: (1) spec compliance — does every acceptance criterion have a passing test? (2) code quality — is the code clean, minimal, and consistent with the existing style?
See AGENTS.md
spec.md)A document generated by /speckit.specify and refined by /speckit.clarify that describes what a feature should do in terms of user stories and acceptance criteria. It is the authoritative source of truth for implementation — the agent must implement exactly what it says, nothing more.
See Greenfield Guide
A CLI tool developed by GitHub (specify-cli) for AI-assisted planning. It runs a structured workflow (constitution → specify → clarify → plan → tasks) that produces a verifiable tasks.md before any code is written. Handles the “what to build” half of the workflow.
An AI agent plugin (by @obra) that handles the “how to build it” half of the workflow. Once it receives the handoff message, it creates an isolated git worktree, picks up tasks from tasks.md, and runs the TDD loop for each one.
tasks.md)A checkbox checklist generated by /speckit.tasks from the technical plan. Each item is a discrete unit of work for the Coder agent. The handoff message points to this file. It is the authoritative implementation plan — agents must not replan or skip items.
Example:
- [ ] Task 3: Write unit tests for expense CRUD helper functions.
See Greenfield Guide
A development discipline where tests are written before implementation code. The sequence is always: write a failing test (RED) → write code to pass it (GREEN) → clean up (REFACTOR). Enforced by the test-driven-development Superpowers skill.
A mandatory checkpoint that code must pass before proceeding to the next stage. Gates are defined in .ai/config/VERIFICATION_AND_EVAL_GUIDE.md. Failure at any gate blocks progress until the issue is resolved.
The agent role that runs all automated gates before a branch is merged. Catches phantom completions, triggers postmortem logging on gate failures, and produces a green signal for finishing-a-development-branch.
See AGENTS.md
A git feature that lets you check out a branch into a separate directory without cloning the repo again. Superpowers creates an isolated worktree for each feature so the agent can work without affecting your main working directory. Run git worktree list to see active worktrees.