Constraint-driven development

Records a project's quality bar as numbers in CONSTRAINTS.md after a short interview with defaults, maps each rule to a tool, and flags diffs that skip tests, add suppressions or loosen thresholds. Use when no quality bar is written down.

CodingPack: Agent Skills by Addy Osmani319 linesconstraint-driven-development
Author
Source
addyosmani/agent-skills/skills/constraint-driven-development @ 8c99fa3
License
MIT · Copyright (c) 2025 Addy Osmani

About this skill

What it does

The skill writes a project's quality bar as numbers into CONSTRAINTS.md and stops agents from quietly lowering it. It reads the stack, linters, coverage and CI first, then asks at most four questions, each with a default: what to enforce, block or warn, target numbers or "measure today and hold that line", and how slow a check may be.

The file has a floor that always applies (no new suppressions such as @ts-ignore, stubs, unexplained skipped tests, secrets or weakening of the file), rules tied to commands, ratchets for metrics without a target, and exceptions with an owner and expiry. Each dimension maps to a standard tool such as Semgrep, Lighthouse or Stryker, run where its cost allows: after each edit, at task end or in CI. A rule counts only once its command fails on a planted violation and passes a clean control.

scripts/quality-gate.mjs fails a Semgrep or axe JSON report with high, critical or serious findings, since both scanners can exit 0 on findings. references/floor-guard.md is a reference Node script that scans the diff for five ways to lower the bar: a loosened threshold, an easier test, a silenced checker, unfinished work, a new exception.

When to use it, and when not

Use it when no quality bar is written down, when an agent keeps skipping tests or silencing checks, or before running an agent unattended.

The interview needs a person; in CI or an autonomous loop the skill applies only the floor. Skip it for one-off scripts and prototypes.

How to run it

The install command below puts the whole folder in place: SKILL.md, both helpers and the licence. The agent picks the skill up by its description; to call it yourself:

  • Claude Code: /constraint-driven-development, or ask for the skill by name.
  • Codex: $constraint-driven-development.
  • Cursor: type / in the Agent chat and pick constraint-driven-development.

Example: /constraint-driven-development Set up constraints here. Measure today's numbers and hold them.

The intake follows Interview me; install it too. Its lifecycle table names the author's /build, /test, /review and /ship commands, which are not included.

How it differs from similar skills

CI/CD pipeline setup builds the pipeline; this skill decides what it enforces. Pre-commit hooks setup installs a Husky hook with no thresholds. Test coverage gaps from our catalog ranks untested code by risk and asks before adding a coverage gate; this skill sets gates on purpose. Coding session retrospective also proposes lint rules, pre-commit hooks and CI checks, but derives them from one finished agent session and sets no numeric thresholds.

Install

Run one command — it saves SKILL.md and the files it uses into your agent's skills folder. Claude Code and Codex pick up a new skill without a restart; if it does not show up, restart the agent.

Claude Code — macOS, Linux
curl -fsSL --create-dirs -o ~/.claude/skills/constraint-driven-development/SKILL.md https://anymodel.org/en/skills/addy-osmani/constraint-driven-development/SKILL.md -o ~/.claude/skills/constraint-driven-development/LICENSE https://anymodel.org/en/skills/addy-osmani/constraint-driven-development/LICENSE -o ~/.claude/skills/constraint-driven-development/references/floor-guard.md https://anymodel.org/en/skills/addy-osmani/constraint-driven-development/references/floor-guard.md -o ~/.claude/skills/constraint-driven-development/scripts/quality-gate.mjs https://anymodel.org/en/skills/addy-osmani/constraint-driven-development/scripts/quality-gate.mjs
Codex, Cursor — macOS, Linux
curl -fsSL --create-dirs -o ~/.agents/skills/constraint-driven-development/SKILL.md https://anymodel.org/en/skills/addy-osmani/constraint-driven-development/SKILL.md -o ~/.agents/skills/constraint-driven-development/LICENSE https://anymodel.org/en/skills/addy-osmani/constraint-driven-development/LICENSE -o ~/.agents/skills/constraint-driven-development/references/floor-guard.md https://anymodel.org/en/skills/addy-osmani/constraint-driven-development/references/floor-guard.md -o ~/.agents/skills/constraint-driven-development/scripts/quality-gate.mjs https://anymodel.org/en/skills/addy-osmani/constraint-driven-development/scripts/quality-gate.mjs
Claude Code — Windows PowerShell
foreach ($f in 'SKILL.md','LICENSE','references/floor-guard.md','scripts/quality-gate.mjs') { $p = Join-Path "$HOME\.claude\skills\constraint-driven-development" $f; New-Item -ItemType Directory -Force (Split-Path $p) | Out-Null; Invoke-WebRequest "https://anymodel.org/en/skills/addy-osmani/constraint-driven-development/$f" -UseBasicParsing -OutFile $p }
Codex, Cursor — Windows PowerShell
foreach ($f in 'SKILL.md','LICENSE','references/floor-guard.md','scripts/quality-gate.mjs') { $p = Join-Path "$HOME\.agents\skills\constraint-driven-development" $f; New-Item -ItemType Directory -Force (Split-Path $p) | Out-Null; Invoke-WebRequest "https://anymodel.org/en/skills/addy-osmani/constraint-driven-development/$f" -UseBasicParsing -OutFile $p }

Any other agent: save the file into its skills folder, or give it the link to the file: https://anymodel.org/en/skills/addy-osmani/constraint-driven-development/SKILL.md

SKILL.md

Raw

Constraint-Driven Development

Overview

Other skills in this pack describe what good looks like. code-review-and-quality gives you five axes. test-driven-development gives you a cycle. security-and-hardening gives you a threat list. All of that lives in prose the agent reads and may or may not follow, and none of it survives the end of the session.

This skill produces something different: a written record of this project's bar, with numbers, that outlives the conversation and can be checked mechanically.

The reason matters. When you wrote the code, reading it told you whether it was any good. An agent writes more in an afternoon than you will read that week, so the judgement moves out of your head and into checks that run around the loop. Those checks need to exist, they need numbers you actually chose, and they need to fire close enough to the work that the agent fixes its own output.

Spec-driven development says what to build. Test-driven development proves it works. Constraint-driven development defines what "good enough to ship" means, before anyone argues about it in a pull request.

When to Use

Apply this skill when:

  • Starting a project or a significant feature and no quality bar is written down
  • The user asks to "set up constraints", "add quality gates", "define our standards", or "stop the agent shipping junk"
  • An agent is producing volume nobody is reading line by line
  • CI has checks but nobody can say which ones block a merge and which ones are decoration
  • Coverage, performance, or accessibility numbers get argued about per-PR instead of decided once
  • You're about to run /build auto or any autonomous loop, and the only thing standing between it and main is a test suite the agent also wrote

When NOT to use:

  • The project already has a CONSTRAINTS.md and the user isn't changing it — read it and follow it instead
  • One-off scripts, spikes, throwaway prototypes
  • The user wants a code review right now (code-review-and-quality) or a CI pipeline built (ci-cd-and-automation)
  • Pre-product-market-fit code with a two-week expected lifetime — the floor below is still worth it, the rest isn't

Loading Constraints

The interview needs a live user. Don't run it in non-interactive contexts (CI, /loop, autonomous runs). If constraints are missing and you're in one of those, apply the Floor below, note that you did, and flag the rest for a human.

The Process

Step 1: Detect before you ask

Never ask what you can read. Before the first question, gather:

What Where to look
Language and stack package.json, pyproject.toml, go.mod, Cargo.toml
Test runner dev dependencies, test script, existing test files
Existing linters eslint.config.*, biome.json, .ruff.toml
Coverage today coverage/ output, or run the suite once
CI .github/workflows/, .gitlab-ci.yml
Agent harness .claude/, .codex/, AGENTS.md

Report what you found in two lines, then ask only what's left.

Step 2: Four questions, each with a default

Follow the one-question-at-a-time discipline from interview-me, with one change: every question here has a default, so "I don't know" is a complete answer that still produces a working config.

Q1: Beyond the floor, which of these do you want enforced?
    (a) Test coverage on new code
    (b) Security scanning
    (c) Performance budgets
    (d) Accessibility
    (e) Architecture boundaries
GUESS: (a) and (b) — you have a test runner already and you're handling user input.
DEFAULT if unsure: (a) and (b).
Say what each pick costs: (c) and (d) need a running URL, (e) needs a rules file written.
Q2: When a check fails while the agent is mid-task, should it block or warn?
GUESS: Block. You're running agents unattended and a warning nobody reads is a warning.
DEFAULT if unsure: Block on the floor, warn on everything else for the first two weeks.
Q3: Do you have target numbers in mind, or should I measure where you are today and hold that line?
GUESS: Measure. Most teams don't have a number, and an invented one gets ignored.
DEFAULT if unsure: Measure and hold. See "Ratchets" below.
Q4: What's the slowest check you'll tolerate before the agent hands work back?
GUESS: About 90 seconds. Longer and you'll stop running it.
DEFAULT if unsure: 90 seconds at task end, unlimited in CI.

Stop at four. A twelve-question intake produces a config nobody understands and a user who regrets starting.

Step 3: Write CONSTRAINTS.md

One file at the repo root. Any agent on any harness can read it, and a change to it shows up in review where it belongs.

# Constraints

Last reviewed: 2026-08-08 by @addy

## Floor (always enforced, no setup required)

- No new suppression comments: `@ts-ignore`, `eslint-disable`, `# noqa`, `# type: ignore`
- No unimplemented stubs: `throw new Error("Not implemented")`, empty `catch {}`
- No skipped or deleted tests without a reason in the commit message
- No secrets in source
- This file does not get weakened to make a change pass

## Enforced with numbers

| Dimension | Rule | Checked by | Runs at |
|-----------|------|-----------|---------|
| Types | Zero type errors | `tsc --noEmit` | every edit |
| Lint | Zero errors from our config | `biome check` | every edit |
| Secrets | No secrets in source | `gitleaks dir . --redact` | every edit |
| Coverage | Changed lines ≥ 80% covered | `vitest run --coverage` + git diff | task end, CI |
| Security: code | Nothing at high or above | `npm run check:security` | CI |
| Security: deps | Nothing at high or above | `osv-scanner scan source -r .` | CI |
| Accessibility | Zero critical or serious | `npm run check:a11y` | preview deploy |
| Performance | LCP ≤ 2500ms, CLS ≤ 0.1 | `lighthouse $PREVIEW_URL --output=json` | preview deploy |

Every row names the command that produces the verdict. A dimension with a
number and no command in this column is an aspiration, not a constraint.

## Measured, not yet enforced

| Metric | Today | Direction |
|--------|-------|-----------|
| Project coverage | 62.4% | must not fall |
| Bundle size (main) | 184 kB | must not grow |

## Exceptions

| ID | Rule | Path | Reason | Owner | Expires |
|----|------|------|--------|-------|---------|
| W1 | `no-explicit-any` | `src/legacy/**` | Rewrite tracked in ENG-441 | @addy | 2026-11-01 |

Then add one line to AGENTS.md and CLAUDE.md: Read CONSTRAINTS.md before writing code. Do not weaken it to make a change pass.

Step 4: Install what each dimension needs

Picking a dimension means installing something. Don't leave the user with a number and no mechanism, and don't invent your own checker when a de facto one exists — these tools are listed because their rule formats and thresholds are what everything else in the ecosystem targets, so the team's existing config keeps working.

Dimension Tool Install Run Gate on
Types (TS) tsc already there tsc --noEmit any error
Types (Python) mypy pip install mypy mypy . any error
Lint your existing config already there eslint . / biome check / ruff check any error
Coverage (JS) your test runner Vitest: npm i -D @vitest/coverage-v8; Jest: already there vitest run --coverage (or jest --coverage) coverage of changed lines
Coverage (Python) pytest-cov pip install pytest-cov pytest --cov --cov-report=lcov same
Security: code Semgrep pipx install semgrep npm run check:security (below) high or critical, including legacy ERROR
Security: secrets gitleaks brew install gitleaks gitleaks dir . --redact --no-banner any finding
Security: dependencies osv-scanner brew install osv-scanner osv-scanner scan source -r . high or above
Performance: page Lighthouse npm i -D lighthouse lighthouse $URL --output=json --quiet LCP, CLS, performance score
Performance: bundle size-limit npm i -D size-limit size-limit --json per-entry byte budget
Accessibility axe-core npm i -D @axe-core/cli npm run check:a11y (below) zero critical or serious
Architecture dependency-cruiser npm i -D dependency-cruiser depcruise src any violation
Assertion quality Stryker npm i -D @stryker-mutator/core stryker run --mutate <changed files> mutation score

Five things that will bite you if you skip them:

  1. --redact on gitleaks is not optional. Without it the matched secret lands in the agent's transcript, which is how a leaked key ends up in a log, a summary, or a commit message. Report the rule and the location, never the value.
  2. Lighthouse and axe need a URL. They only work against a running app, so they belong in the runtime stage against a preview deploy or a local server you start first. If the project has no URL to hit — a CLI, a library, a desktop app — say so and drop the dimension rather than inventing a check that can't run.
  3. Scope the expensive ones to the diff. stryker run --mutate on the whole repo takes hours and gets turned off; on the files a change touched it takes under a minute. Same for Semgrep, which takes a path list.
  4. Coverage needs no second test run. Read the lcov your suite already writes and intersect it with git diff. Running the suite twice to get a number is the fastest way to make people hate this.
  5. Semgrep's registry rules are free to run; check the licence before redistributing them. opengrep is a drop-in fork with the same rule format and JSON output if that matters to your legal team.

semgrep scan and axe can exit 0 on findings; copy scripts/quality-gate.mjs into the project's scripts/ directory to enforce these thresholds. Keep the scanner before && so a failed scan stops the command.

Add each one to the project's own script so it's reproducible without an agent:

{
  "scripts": {
    "check:fast": "tsc --noEmit && eslint . && gitleaks dir . --redact --no-banner",
    "check:task": "npm run check:fast && vitest run --coverage",
    "check:security": "semgrep scan --config p/default --strict --json > semgrep-results.json && node scripts/quality-gate.mjs semgrep semgrep-results.json",
    "check:a11y": "axe \"$PREVIEW_URL\" --tags wcag2a,wcag2aa,wcag21aa --stdout > axe-results.json && node scripts/quality-gate.mjs axe axe-results.json",
    "check:full": "npm run check:task && npm run check:security && osv-scanner scan source -r ."
  }
}

That mapping matters more than the tools. check:fast is what runs after an edit, check:task when the agent thinks it's done, check:full in CI. Run check:a11y after the preview is reachable, with PREVIEW_URL set (the example uses POSIX shell syntax).

Before calling any row enforced, run its actual CI command against a known violation and a clean control. Confirm that the violation fails, the control passes, and scanner errors fail too. For a severity threshold, also confirm a below-threshold finding passes. Apply this to every dimension, including coverage and Lighthouse: generating a report alone does not enforce the number in CONSTRAINTS.md.

The commands now live in two places — the Checked by column in CONSTRAINTS.md and these scripts. CONSTRAINTS.md is the canonical source: it carries the reason alongside each command and it shows up in review. The scripts are convenience wrappers that must mirror it, not a second source of truth; if they drift, the file wins.

Step 5: Wire it to the lifecycle

The single biggest mistake is running everything everywhere. A check that stalls the agent gets switched off, and a gate people switched off is worse than no gate, because the bar still looks like it exists.

Phase Command What runs Budget
BUILD /build Types, lint, secrets, the floor under 5s, changed file only
VERIFY /test Related tests, coverage on changed lines under 90s
REVIEW /review Everything, plus the guards below minutes
SHIP /ship Direction checks, no regressions CI

Two rules that keep this tolerable:

  1. Scope to the diff. Check the lines this change touched, not the whole repo. Coverage of changed lines is a number the agent can move; project coverage is one it inherited.
  2. Cost decides placement. Anything over a few seconds moves out of the edit loop. Mutation testing on a whole repo takes hours; on the files a change touched it takes under a minute, which is the difference between a check people run and one they don't.

Step 6: Guard the bar itself

Someone will point out that if the agent writes the code and the checks, the checks prove nothing. Half right, and worth engineering around.

Agents don't craft clever loopholes. They hit a red check and take the cheapest road to green. Watch for these five moves in the diff, at review time:

  1. The threshold moved. A budget lowered, a severity dropped, a check removed from the fast stage. Compare CONSTRAINTS.md against its state at the branch point.
  2. A test got easier. .skip added, a test file deleted, assertions pulled out of tests that stayed.
  3. A checker got silenced. New @ts-ignore or eslint-disable. Four suppressions deserve special attention because they switch off a check you're relying on: istanbul ignore drops code from coverage instead of testing it, Stryker disable hides a surviving mutant, nosemgrep and gitleaks:allow do it for security findings.
  4. Work is unfinished. A stub that throws, an empty catch turning a failure into silence, a TODO standing where the implementation should be.
  5. An exception appeared. A new row in the Exceptions table nobody discussed.

None of this needs tooling beyond git diff. Tightening the bar should be silent; loosening it should be loud.

Unlike the numbered dimensions, the floor has no de facto tool of its own, so an agent asked to enforce it tends to write a checker from scratch, and two agents write two different ones. A reference implementation of these five checks ships with this skill in references/floor-guard.md (diff-scoped, exit 0/1/2, patterns adaptable per ecosystem). Adapt that rather than reinventing it, for the same reason every dimension names a de facto tool: so the mechanism is the same across runs and stacks.

Not all checks are equally circular. Rank them by one question: can the agent make this pass by writing code that doesn't work?

  • External — axe-core encodes WCAG, osv-scanner reads a vulnerability database, Lighthouse measures a real browser. The agent can't argue with these.
  • Project — your lint rules, your layer boundaries. A human owns the file.
  • Suite — your own tests. Most useful, and the only genuinely circular one.

A bar made entirely of the third kind is worth less than one with an outside opinion in it. Check that at least one external constraint is present.

Step 7: Ratchets, when you don't have a number

Set 80% coverage on a codebase at 62% and you get a red build forever, then a team that learns to ignore red builds.

The alternative asks for no decision: record where you are, then refuse to get worse. Put it in the "Measured, not yet enforced" table with today's number and a direction. Every check compares against the recorded value, not an aspiration. When a number improves, update it; when it drops, that's the finding.

This also answers a fair objection to training. Models are rewarded for passing tests, which you can evaluate in seconds. Architectural rot shows up over months and never reaches the weights. A ratchet is the missing penalty, written down where the build can see it.

Sane Defaults

When the user has no opinion, use these. They're chosen to be met by most codebases on day one.

Constraint Default Why this number
Coverage of changed lines ≥ 80% High enough to force a test, low enough to allow a config line
Project coverage today's value, must not fall No argument needed to adopt
Mutation score (if used) ≥ 60% to start Typical for a suite never mutated before; 80% is mature
Dependency vulnerabilities nothing at high or above Below that is mostly noise
LCP ≤ 2500 ms Core Web Vitals "good" threshold
CLS ≤ 0.1 Same
Accessibility zero critical or serious axe violations Moderate and minor are often debatable
Exception lifetime 90 days Long enough to plan the fix, short enough to remember
Ratchet tolerance 0.5% Absorbs drift when an unrelated file moves the number

State the number and the reason together. A threshold without a rationale gets deleted by the next person who hits it.

Escalation Path

Constraints work at three levels of teeth. Start at the first.

  1. Written only. CONSTRAINTS.md exists and agents read it. Costs nothing, catches the honest mistakes, relies on the agent complying.
  2. Scripted. An npm run check (or make check) that runs the fast checks, wired into your agent's post-edit hook and your CI. Deterministic, no new dependency.
  3. Tool-backed. A dedicated runner that handles diff scoping, budgets, ratchets, and the guard checks. Use when the config outgrows a shell script. The floor-guard reference in references/floor-guard.md is the starting point for the guard-checks half of this.

Most projects should stop at 2. Move to 3 when you're maintaining more than about thirty lines of check-running shell.

A first run can be floor-only. The floor guard is diff-only and needs no installs, so you can enforce the floor on day one and add numbered dimensions as you install each tool, rather than standing up every checker before the first commit is protected. Security tools that install machine-wide (gitleaks, osv-scanner) can also run CI-only if you'd rather keep laptops clean; declare where each dimension runs in the Runs at column.

Common Rationalizations

Excuse Reality
"We'll add constraints once the code settles" Code settles around whatever was allowed while it was moving
"The tests are the constraints" Tests you wrote prove you agree with yourself; they say nothing about coverage of new code, dependency risk, or bundle growth
"We can't hit 80% coverage" Then don't set 80%. Set today's number and hold it
"This will slow the agent down" Only if you put slow checks in the fast loop. That's a placement error, not an argument against constraints
"I'll remember what our standards are" The agent won't, and it's writing most of the code
"Constraints will block us shipping" An exception with an owner and a date unblocks you. Deleting the constraint unblocks everyone forever

Red Flags

Stop and reconsider if you notice:

  • The interview ran past four questions, or produced a config the user can't explain
  • A budget was set that the codebase fails today, with no plan to reach it
  • A dimension was written into CONSTRAINTS.md with a number but no tool behind it
  • A checker was hand-rolled when a de facto one exists, so the team's existing config is ignored
  • Every constraint is checked by the project's own test suite, with no external opinion
  • CONSTRAINTS.md changed in the same commit as the feature that was failing
  • An exception has no owner, or an expiry more than a year out
  • The agent proposed relaxing a threshold instead of fixing the code
  • Slow checks landed in the edit loop and someone has started passing --no-verify
  • Nobody has opened CONSTRAINTS.md since it was written

Verification

The skill was applied correctly when:

  • CONSTRAINTS.md exists, and every number in it has a stated reason
  • The floor is enforced and passes on the current codebase without changes
  • Every dimension the user picked has a tool installed and a command that runs today
  • Each constraint says where it runs, and the fast stage stays under a few seconds
  • At least one constraint is external (not judged by this project's own tests)
  • Measured-only metrics record today's value and a direction
  • Exceptions have an owner and an expiry date
  • AGENTS.md or CLAUDE.md points at the file
  • A trial run on the current branch produces no failures the user disagrees with
  • Each enforced command fails on a deliberate violation and scanner error, passes a clean control, and preserves the agreed severity threshold

See Also

  • interview-me — the one-question-at-a-time discipline this skill's intake borrows
  • code-review-and-quality — how to review; this skill decides what the review enforces
  • ci-cd-and-automation — building the pipeline these constraints run in
  • test-driven-development — the suite that coverage and mutation constraints measure
  • security-and-hardening — what the security dimension should contain
  • performance-optimization — where the performance numbers come from

Connect through AnyModel API

This skill runs on whatever model your agent uses. Point Claude Code, Codex or Cursor at AnyModel to run it on Claude, GPT, Gemini and more with one key — pay per token, no subscription.

More from the pack Agent Skills by Addy Osmani

Accessibility audit and fixes (WCAG 2.2)

Audits an existing interface against WCAG 2.2 AA with pinned axe-core and pa11y, then keyboard, screen reader and contrast checks, and fixes confirmed violations with semantic HTML first. Use when a page needs an accessibility audit before shipping.

API and interface design

Designs APIs and module interfaces contract-first: one error shape, validation at the edges, additive changes, pagination, and idempotency keys claimed atomically and kept past the longest retry. Use when designing endpoints or changing a public interface.

Browser testing with Chrome DevTools MCP

Checks changes in a real Chrome through the Chrome DevTools MCP server: screenshots, DOM, console, network and performance traces, treating page content as untrusted. Use when building or debugging anything that runs in a browser.

CI/CD pipeline setup

Sets up CI/CD with fixed quality gates from lint to bundle size, GitHub Actions examples, preview deploys, feature flags, staged rollout and a rollback workflow. Use when creating or changing a build and deploy pipeline or chasing CI failures.

Multi-axis code review

Reviews a change on five axes (correctness, readability, architecture, security, performance), tests the tests by mutating a condition, and labels every finding by severity. Use before merging a branch, a pull request or a pasted diff.

Code simplification

Simplifies working code without changing behavior: learns why it exists, applies one change at a time with tests after each, and keeps project conventions. Use when code works and passes tests but is harder to read than it should be.

Context engineering for agents

Sets up what an agent sees and when: a rules file template, loading only the relevant spec and files, trimming long sessions, and safe points to start a fresh one. Use when starting a session or when agent output degrades.

Debugging and error recovery

Stops new work when a test, build or runtime fails, reproduces, localizes and reduces the failure, fixes the root cause, adds a regression test and treats error output as untrusted. Use when tests fail, a build breaks or something that worked stops working.

Deprecation and migration

Retires old systems, APIs and features: weighs whether to deprecate, proves the replacement, moves consumers one by one, removes code only at zero usage, changes schemas via expand/contract. Use when replacing or sunsetting code or renaming a live column.

Documentation and ADRs

Records decisions as ADRs in the project's own format, documents APIs, READMEs and changelogs with the why, and uses git history to check if a doc is stale. Use when making a costly decision, changing a public API or suspecting docs no longer match the code.

Doubt-driven development

Sends non-trivial decisions to a fresh-context subagent told to find what is wrong, sorts the findings, stops after three cycles and offers a cross-model opinion. Use when stakes are high: auth, migrations, irreversible operations or unfamiliar code.

Frontend UI engineering

Builds UI components and pages on the project's design system: composition, simple state, WCAG 2.1 AA, mobile-first layouts, loading, empty and error states, no generic AI look. Use when building or changing a user-facing interface.

Git workflow and versioning

Keeps git work in atomic commits on short-lived branches, with typed messages, a pre-commit check for secrets and tests, worktrees for parallel agents, semver bumps, tags and a human changelog. Use when committing, branching, opening a PR or cutting a release.

Idea refinement

Refines a raw idea in three phases: sharpening questions and five to eight variations, two or three directions tested for value and feasibility, then a one-pager with MVP scope and a Not Doing list. Use when an idea is vague or a plan needs stress-testing.

Incremental implementation

Builds changes in thin vertical, contract-first or risk-first slices, each tested, verified and committed before the next, with strict scope, feature flags and revertable steps. Use when a change spans several files or a task is too big to land in one step.

Interview me

Interviews the user one question at a time, each with a guessed answer and a confidence number, until the agent can predict the next replies, then confirms a statement of intent before any spec or code. Use when a request leaves who, why or success unclear.

Observability and instrumentation

Instruments a feature with structured JSON logs and request IDs, RED and USE metrics with bounded labels, OpenTelemetry traces and symptom-based alerts with runbooks, then tests the telemetry. Use when a feature, job or integration is headed for production.

Performance optimization

Optimizes by measurement: takes a baseline, fixes the one proven bottleneck, re-measures against noise and reverts neutral changes, with worked fixes for N+1 queries, indexes, caching and bundles. Use when something is slow or misses a performance budget.

Planning and task breakdown

Breaks a spec into small vertical-slice tasks with acceptance criteria, verification steps, sizes, dependency order and checkpoints, saved to tasks/todo.md or a named tracker. Use when a spec is ready but the work is too big to start in one go.

Security hardening

Hardens code with a short threat model, always, ask-first and never rules, and patterns for injection, XSS, access control, SSRF, secrets, dependencies, personal data and LLM output. Use when code handles user input, auth, sensitive data or outside services.

Shipping and launch

Prepares a production launch with a pre-launch checklist, a feature-flag rollout from 5% to 100%, thresholds for advancing or rolling back, an error-budget gate, a rollback plan and first-hour checks. Use when a feature or major change is about to ship.

Source-driven development

Grounds framework code in official docs: reads exact versions from the dependency file, fetches the relevant page, follows the documented API and cites full URLs, flagging anything unverified. Use when framework-specific code must match the version in use.

Spec-driven development

Writes a spec before code, surfacing assumptions and covering objective, commands, structure, style, tests and boundaries, then gates plan, tasks and code on approval, with capability maps and delta specs. Use when new work has vague requirements.

Test-driven development, red-green-refactor

Drives changes with red-green-refactor: finds the repository's own test commands, writes the failing test first, reproduces each bug with a test before fixing it, and sets rules on mocks and naming. Use when adding logic, fixing a bug or changing behavior.