Skip to content
Skills Library
Programming · Review & audit

specwright

/specwright

Specwright takes a software project from spec to production with guardrails. It discovers the project, hunts contradictions between requirements, design, code and config, asks only what needs a human, then installs hooks, rules, a CI-identical gate, feature worktrees and cases-as-spec. Use it for /specwright, starting a project from a BRD or PRD, onboarding a codebase for Claude Code, a contradiction check on new requirements or a defect batch, running a feature through the loop, or auditing a project's AI-delivery setup.

Repository
specwright ↗
Licence
MIT
Last repository change
05.11.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
6
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 05.11.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Specwright takes a software project from spec to production with guardrails. It discovers the project, hunts contradictions between requirements, design, code and config, asks only what needs a human, then installs hooks, rules, a CI-identical gate, feature worktrees and cases-as-spec. Use it for /specwright, starting a project from a BRD or PRD, onboarding a codebase for Claude Code, a contradiction check on new requirements or a defect batch, running a feature through the loop, or auditing a project's AI-delivery setup.

Original author description

Specwright takes a software project from spec to production with guardrails. It discovers the project, hunts contradictions between requirements, design, code and config, asks only what needs a human, then installs hooks, rules, a CI-identical gate, feature worktrees and cases-as-spec. Use it for /specwright, starting a project from a BRD or PRD, onboarding a codebase for Claude Code, a contradiction check on new requirements or a defect batch, running a feature through the loop, or auditing a project's AI-delivery setup.

How it works

  1. How you are invoked
  2. Pick the mode
  3. Prerequisites — check first, every mode
  4. Setup (new or existing)
  5. Feature
  6. Intake
  7. Ground rules for you, the agent
  8. What is in this skill
Original SKILL.md headings · 292 lines, 2,171 words
SKILL.md preview
---
name: specwright
description: Specwright takes a software project from spec to production with guardrails. It discovers the project, hunts contradictions between requirements, design, code and config, asks only what needs a human, then installs hooks, rules, a CI-identical gate, feature worktrees and cases-as-spec. Use it for /specwright, starting a project from a BRD or PRD, onboarding a codebase for Claude Code, a contradiction check on new requirements or a defect batch, running a feature through the loop, or auditing a project's AI-delivery setup.
---

# Specwright

*From spec to production, built straight.*

A method and a kit for delivering software with a coding agent, fast and
without the mess. **Opinionated about practice, neutral about layout and
stack**: the practices are fixed defaults (`references/opinions.md`); the
directory structure, languages, architecture and tools stay the project's.

Your most important job is not installing files. It is **finding what the
project's people know that the files do not**: which source is current, what
may never break, where two documents disagree. Ask those questions, only
those, and write every answer where the next session will find it.

## How you are invoked

Usually as `/specwright <instructions>`. **Treat everything after the command
as the user's request** and pick the mode from it. `/specwright` alone: run
discovery on the current directory and ask what they want, offering the modes
below. Specwright also loads on its own when a request matches the
description.

Examples: `/specwright set up this project, BRDs in docs/brd` ·
`/specwright adopt this monorepo, keep our ESLint` ·
`/specwright check CR-14.pdf for contradictions` ·
`/specwright build the bulk-upload feature` · `/specwright audit`.

## Pick the mode

| The user wants to... | Mode |
|---|---|
| Start a new project (from a BRD/PRD, or from nothing) | **Setup** — new |
| Bring an existing codebase under Specwright | **Setup** — existing |
| Build a feature or fix a defect where Specwright is installed | **Feature** |
| Process a new requirements document, change request or defect batch | **Intake** |
| Know what a project's setup is missing or outdated | **Audit**: `node <skill>/scripts/audit.mjs <root>`, then report |
| Update the project's hooks to this version, or change tier | **Update**: `node <skill>/scripts/install.mjs <root> [--tier <tier>]` — it reuses the existing `specwright.ini`, replaces only the hooks, places what the new tier adds; then fill those parts (Setup phase 5) and verify (phase 6) |

`<skill>` is this skill's directory. If the mode is unclear, run discovery
(Setup step 1) first; what you find usually decides it.

## Prerequisites — check first, every mode

- **Node.js 18+ and git** on PATH. The hooks and scripts are Node, so they run
  natively on Windows, macOS and Linux.
- **graphify is required.** Check `graphify --help` runs and the `graphify`
  skill is available. If not, **stop** and give the user the commands:
  `uv tool install graphifyy` (or `pipx install graphifyy`), then
  `graphify install` (Windows: `graphify install --platform windows`), then
  restart Claude Code. Do not continue setup without it: the requirements
  graph is how every later feature asks "what does the spec say".

---

## Setup (new or existing)

Work through the phases in order. Install nothing before phase 4: the
interview changes what gets installed.

### 1. Discover — read-only, before asking anything

Answer everything the project can answer itself (`references/interview.md`
§2 has the full checklist):

- **Layout and units.** Run `node <skill>/scripts/audit.mjs <candidate-root>`.
  Identify the layout (single repo, monorepo, workspace of repos, sibling
  repos, submodules) and the units — directories with their own toolchain.
  `references/layouts.md`.
- **Stack per unit**: manifests, lint/format/typecheck/test commands, the
  commands CI actually runs. `references/stacks.md`.
- **What exists**: agent instruction files (`CLAUDE.md`, `AGENTS.md`,
  `.cursorrules`, copilot instructions), `.claude/settings.json`, lint
  configs, ADRs/decision records, tests, CI/CD and the deployment model, the
  local environment.
- **Requirements and design**: BRDs, PRDs, prototypes, design links, scope
  emails; versions and dates.
- **History of pain** (existing projects): reverts, hotfixes, reopened
  issues, lint-disable counts.

**Do not trust a command because CI runs it.** Check the configuration it
needs exists (a `tsc` with no tsconfig, a linter with no config, tests with no
test files). A broken CI is a finding, not a source of truth.

Show the user a **discovery summary** in this shape:

```
Layout:        <single repo | monorepo | workspace | ...>, project root = <path>
Units:         <path> — <stack>; lint/typecheck/test as CI runs them
Exists:        <instruction files, settings, CI + deploy model, records, tests, local env>
Requirements:  <sources with versions and dates>
Missing:       <what Specwright would add>
Unsure of:     <what you could not settle — these feed the interview>
```

Fill every line; write "none" rather than leaving one out.

### 2. Hunt contradictions

Follow `references/contradictions.md`: collect sources, extract claims with
their references, group by subject, compare, check each against the likely
invariants, check the silences (failure, retry, duplicates, permissions,
volume, deletion). Classify each finding: conflict, supersession, gap,
invariant breach, drift, naming, false alarm.

Build the requirements graph first when there are requirement documents:
`/graphify <requirements dir>`, then query it per subject
(`references/requirements-and-design.md`).

Write every real finding into the open-questions register (template
`templates/workspace/docs/open-questions.md`) at
`<existing docs folder>/open-questions.md` (`docs/open-questions.md` if there
is none), both sides quoted exactly, with class, options and a
recommendation. Drift needing no stakeholder is logged as an FYI entry, not
asked.

**Instruction files are sources too.** Compare `CLAUDE.md`, `AGENTS.md`,
`.cursorrules` and the like against each other, the code and CI **before**
anything merges or imports them.

### 3. Interview — ask what needs a human

`references/interview.md` §3 is the question bank (each with a default); §4
says how to ask.

- Ask only what changes what gets built; otherwise take the default and say
  so in one line.
- Always confirm the starred items: what the product is and who uses it,
  current requirement sources, who decides conflicts, the **invariants**, the
  deployment model, and the **tier** (`references/tiers.md`: lite, standard,
  platform — default standard).
- Ask the blocking contradictions from phase 2.
- Use `AskUserQuestion` when available: at most four questions per call, each
  self-contained, recommended option first, plain language, both sides of a
  contradiction quoted.

Record each answer where it belongs (`references/interview.md` §5). If no one
can answer now: keep it open, take the default for what it does not block,
and say so.

### 4. Install

0. **New project:** scaffold each unit first (manifest, lint config,
   typecheck config, one source file) so the hooks have something to run.
1. Write the project's `specwright.ini` from what you found and were told
   (template: `templates/workspace/.claude/specwright.ini`): `[project]`
   locations and tier, one `[unit <name>]` per unit (path, exts, lint with
   `{file}`, typecheck, install), and `[gate]` steps in order — the same
   commands CI runs. In an existing project every location points at **what
   already exists**.
2. Run `node <skill>/scripts/install.mjs <root> --config <file>`. It writes
   the hooks, **merges** hook wiring into an existing `settings.json` (backup
   `.bak`), stamps the version, and never overwrites a project file: a
   template for an existing file lands beside it as `*.specwright-new` for you
   to merge.
3. Workspace of repos: run `node scripts/bootstrap.mjs` so every repo gets its
   own hooks (a session may start inside a repo).
4. Point CI at `node scripts/gate.mjs`, or keep CI's command and mirror it in
   `[gate]`. One command, identical to CI.

Never restructure the project. Never commit, push, merge, migrate or deploy
unless asked; stage by path when you do commit.

### 5. Fill — make it the project's own

What to fill depends on the tier (`references/tiers.md`).

- **Instruction files.** Fill `CLAUDE.md` (product, units, invariants, where
  requirements and open questions live, the feature loop, local environment,
  working beside other sessions, and the import `@<lessons_dir>/INDEX.md`).
  Existing project: merge `CLAUDE.md.specwright-new` into the existing file,
  keep every existing rule, and send conflicting ones to the register. A
  team on `AGENTS.md` keeps content there and imports it. Per-unit
  instruction files where units differ. `references/enforcement.md` §1.
- **Team lessons** (all tiers). `<lessons_dir>/INDEX.md` in the repo, one line
  per lesson, imported by `CLAUDE.md`, so every developer's sessions learn
  from every trap. Seed it with traps already known from the history.
- **Path-scoped rules** (standard+). One `.claude/rules/<topic>.md` per topic
  where a mistake is silent until production. `references/enforcement.md` §3.
- **Architecture lint**. Boundaries, one door for dangerous handles, no
  cycles, size limits, narrow DRY, type safety, in the unit's own linter
  (`references/stacks.md` §2). Existing code with many violations: strict for
  new files, baselined for old, plan in the decision log.
- **Topic docs** (standard+). Short build docs, one topic each, that rules
  link to. Existing projects: link what exists; write only what is missing.
- **Invariants into enforcement.** Each confirmed invariant gets a lint rule,
  a test, or at least a line in the instructions file with its reason.
- **Requirements** (standard+). Sources stay where they are; the graph from
  `/graphify` sits beside them.
- **Cases** (standard+, when there is UI or an end-to-end flow). Cases
  directory beside existing e2e tests, the check as a `[gate]` step, a first
  case file for one screen. `references/cases-and-verification.md`.
- **Verification** (platform). Per-session isolated stacks, multi-tenant load
  test, leak probe.
- **Departures** from an opinion go into the decision log with the reason.

### 6. Verify

- `node <skill>/scripts/audit.mjs <root>`: nothing missing for the tier, no
  unfilled `__PLACEHOLDERS__`, no unmerged `*.specwright-new`, no unknown
  config keys, version current.
- Feed the hooks real input from the project root:
  `node .claude/hooks/lint.mjs` with stdin
  `{"tool_input":{"file_path":"<absolute path of a real source file>"}}` must
  exit 0 on a clean file and exit 2 with findings on a broken one;
  `node .claude/hooks/gate.mjs` with stdin `{}` must exit 0 on a clean tree.
- Run `node scripts/gate.mjs` once. Failures that already exist on the
  default branch are findings to report, not your bugs.
- Do not create test branches or worktrees in the user's repos to try
  `feature-start.mjs`; the first real feature does that.

### 7. Hand over

Report briefly: layout and units as configured, tier, what was installed and
merged, open questions grouped by who answers, departures from the opinions,
what remains of the adoption plan (`references/cookbook.md`), and every
process or container you started and stopped.

---

## Feature

For a project with Specwright installed. The full loop is the project's
`feature-workflow.md` (template `templates/workspace/docs/feature-workflow.md`):

1. `node scripts/feature-start.mjs <name>` and work in that worktree.
2. **Clarify**: query the requirements graph, read the design source for each
   screen, read the decision log, open questions and lessons, run the
   contradiction procedure over what the feature touches, and **ask** the
   blocking questions. Do not build on an open contradiction.
3. Enumerate callers of what you will change.
4. Write or update the **case** first.
5. Decide data access, indexes, caching, job-vs-request, cost at volume.
6. Build every unit the feature touches; contracts generated, not hand-written.
7. Tests: happy path, user-facing error, the isolation boundary.
8. `node scripts/gate.mjs`.
9. **Run it yourself**: API by script, screens in a browser, on the server you
   actually changed (`references/cases-and-verification.md` §5).
10. Volume, load and leak checks where the tier and feature call for them.
11. Add a lesson for anything that cost time; log deferrals; stop what you
    started; `node scripts/feature-end.mjs <dir>` once merged.

## Intake

A new requirements document, change request or defect batch:

1. Confirm **which product and environment** it is for.
2. Store the source untouched; update the graph (`/graphify <requirements dir> --update`).
3. Run the contradiction procedure against existing requirements, the design,
   the decision log and current behaviour.
4. Log findings, ask the blocking ones; for defects, one tracker row each
   (`templates/workspace/docs/defects.csv`), issue verbatim.
5. Each item then goes through the Feature loop.

---

## Ground rules for you, the agent

- **Adapt to the project; never restructure it.**
- **Merge, never overwrite.** Existing instructions, settings, lint configs,
  docs and records are kept; templates are merged into them.
- **Never resolve a contradiction silently.** Picking the side that is easier
  to build is a decision nobody made.
- **Ask only what needs a human; recommend an answer every time.**
- **Write every answer down** where the next session finds it.
- **Explain why.** Every rule, hook and script you add carries the failure it
  prevents.
- **Git is the user's.** Commit, push, merge, migrate or deploy only when
  asked; stage by path.
- **Clean up.** Stop every process and container you started, by the pid
  listening on its port after checking it is yours; never an unscoped kill.
  Say what you stopped.

## What is in this skill

| Path | What |
|---|---|
| `references/interview.md` | Discovery checklist, question bank with defaults, how to ask, where answers go |
| `references/contradictions.md` | Where contradictions hide, the procedure, classes, register entries, examples |
| `references/tiers.md` | Lite, standard, platform: what each includes and how to choose |
| `references/layouts.md` | Recognising layouts, unit blocks, where files go, merging into existing projects |
| `references/stacks.md` | Practice → tool per ecosystem, architecture lint, invariants by architecture |
| `references/opinions.md` | The opinions, why, when they may bend, recording a departure |
| `references/enforcement.md` | Instruction loading, hooks and their traps, path-scoped rules, the gate |
| `references/requirements-and-design.md` | Untouched sources, the graphify graph, design from markup |
| `references/cases-and-verification.md` | Cases as spec, the check, e2e traps, isolated stacks, running it yourself |
| `references/records-and-parallel-work.md` | Team lessons, decision log, register, defects, worktrees, clean-up |
| `references/cookbook.md` | The method for humans, with the adoption plan |
| `templates/` | What install.mjs places |
| `examples/` | Fourteen real files from the reference project, for shape — index in `examples/README.md` |
| `scripts/install.mjs` · `audit.mjs` · `selftest.mjs` | Merge-safe installer · read-only audit · cross-platform self-test |
Files in this package (6)
  • .gitignore 1 KB
  • LICENSE 1 KB
  • MANIFEST.md 5 KB
  • README.md 15 KB
  • SKILL.md 15 KB
  • VERSION 1 KB

Versions

The database has no other skills named specwright.

Database snapshot: 13.11.2026 · package version 6a81efde75a3 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100sw-start
    Specwright's single entry. Detects the workspace and its state, routes to one of the public skills (sw-shape, sw-ingest, sw-spec, sw-plan, sw-review, sw-publish, sw-view), and tidies up after a step (assets, graph, trace, lint) before stopping at the next human decision. Use…
  • 100to-feature-spec
    Turns the current conversation and codebase understanding into a feature spec. Use when asked to capture agreed requirements, write a feature spec, or turn the current context into a PRD; not to start a new requirements interview or implementation.
  • 100spec
    Use when the user wants a spec-driven development workflow for implementing a feature in the current codebase, from fuzzy idea or existing active spec through requirements, technical plan, tasks, implementation, verification, and closure report. Auto-detects project/spec state,…
  • 100spec-coder
    Structured spec-first development workflow with multi-role expert review gates: clarify requirements, author spec documents (requirements/design/tasks), generate code from spec, verify with real tests, and iterate while keeping spec and code in sync. Use when user wants to build…
  • 100ai-test-generation
    Use AI to write NEW test code from specs, PRDs, user stories, code diffs, bug reports, or OpenAPI specs. Staged pipeline: requirements extraction → risk analysis → coverage matrix → scenario generation → oracle design → test code → human review, with guardrails against…
  • 100code-to-spec
    Reverse-engineer a SPEC document from an existing project. Analyzes code, config, tests, and structure to produce a comprehensive specification. Triggers on: code-to-spec, reverse spec, generate spec, 逆向规格, 生成规格文档, 生成设计文档, 生成设计方案, extract spec, document this project, what does this project do.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.