From dev
Define what to build through structured research and experimentation. Produces .dev/prd.md. Use at the start of any feature work. Triggers on: "what should we build", "let's plan", "new feature", "I want to build", "dev/what"
How this skill is triggered — by the user, by Claude, or both
Slash command
/dev:whatThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Human-heavy, interactive phase. No implementation happens here — only understanding.
Human-heavy, interactive phase. No implementation happens here — only understanding.
Hard gate: nothing proceeds to dev/how until .dev/prd.md is saved and approved.
Each phase runs in a fresh context window with no conversation history from previous phases. The only handoff between What and How is .dev/prd.md plus any artifacts it references. If a discovery, decision, or constraint isn't captured in an artifact file, it doesn't exist for the next phase. Write every insight into a file — never rely on the conversation to carry knowledge forward.
Before anything else, check if .dev/ exists and contains files. If it does, check .dev/tasks.yml for any task with status: fatal — that indicates a planned recovery back to this phase.
notes to understand what went wrong, then proceed to step 4 (skip worktree creation — you're already in one). Use the existing .dev/prd.md as the starting point for revision.
.dev/is not empty — there's work-in-progress from a previous run. Either finish the existing feature (dev/howordev/build) or clear it (rm -rf .dev/) before starting a new one.
List the contents so the user can see what's there. Do not proceed until .dev/ is empty or absent.
Before planning anything, check if the project has persistent domain specs.
specs/README.md exists, read the index to understand what domains are already documentedIf no specs/ directory exists, skip this step. Specs will be created after the feature is built (via dev/done).
Set up an isolated workspace for this feature.
dev/priority-filter)nu -c 'use ct/git/worktree *; wk add dev/<feature-name>'
This creates a sibling worktree, fetches origin, and handles existing branches automatically. All subsequent work (research, learning tests, prototyping, prd.md) happens in this worktree.
Ask the user what they want to build. Listen for:
Don't rush this. Ask clarifying questions. Challenge vague requirements.
Before any planning, surface what you don't know:
Be honest about uncertainty. Assume docs are wrong until proven otherwise.
For every external dependency, determine how you can verify its behaviour:
| Category | Example | Verification path |
|---|---|---|
| In-repo code | Project modules, workspace packages | Read the source directly — truth is in the code |
| Inspectable package | npm module in node_modules, open-source library | Read exported types, source files, or vendored code. Can explore node_modules/<pkg>/ or clone the upstream repo to read implementation |
| Black-box / binary | CLI tools, closed-source APIs, SaaS endpoints | Cannot inspect — must verify through execution (learning tests) |
This classification drives whether you research by reading (step 6) or by running (step 7). For black-box dependencies, reading docs alone is never sufficient — you must execute against the real thing.
When external dependencies are involved, investigate before planning.
.dev/research.mdFor inspectable dependencies — go beyond docs. These are your highest-confidence sources:
node_modules/<pkg>/ — exported types, source, README.md. The actual type signatures are ground truth, not the website docs.Research alone is sufficient only for inspectable dependencies where you can read the implementation. For black-box dependencies, research informs your learning tests but does not replace them.
See references/research.md for the research protocol.
When unknowns involve black-box tools, CLIs, or APIs — write small executable tests that validate your assumptions before building against them.
This is the most important technique in this phase. Plans built on untested assumptions fail at build time. Learning tests fail cheaply.
Hard rule: if the dependency is a binary CLI, closed-source API, or anything you cannot read the source of, you must write learning tests before proceeding to Refine. Do not add claims about external tool behaviour to the PRD that haven't been verified by execution. Docs lie. Flags get removed. APIs drift. Run the tool and observe what actually happens.
Autonomy expectation: don't wait for the user to suggest testing. As soon as research surfaces a dependency you can't inspect, immediately write and run learning tests. This is the agent's responsibility — be proactive, not passive. If you read docs that say a CLI flag exists, write a test that exercises it before recording it as a fact in the PRD.
See references/learning-tests.md for the full pattern.
When the feature involves taste, UX, or architectural decisions that can't be resolved through conversation alone.
Two strategies:
All prototype code is throwaway. It exists to close understanding gaps, not to ship.
Take everything gathered — research, learning test results, prototype learnings, conversation — and distill into artifacts. The PRD is the primary artifact; it may reference additional files for detail that would bloat the main document.
Remember: the next phase gets only these files, not this conversation. Every decision, constraint, discovery, and verified behaviour must be written down. If you discussed something important with the user but didn't write it into an artifact, it's lost.
All artifacts are saved to the .dev/ directory (create it if it doesn't exist):
.dev/prd.md — always produced. The self-contained specification. References other artifacts where needed..dev/research.md — optional. Detailed research findings referenced from PRD's Research Summary..dev/lt-*.ts, .dev/lt-*.sh — optional. Executable proof of verified behaviour, referenced from PRD..dev/ — optional. Interface sketches, diagrams, prototype screenshots, API response samples. Anything the PRD cites that's better as a separate file.The PRD must be understandable on its own. Reference files provide depth, not missing context.
Walk through the PRD section by section with the user:
See references/prd-schema.md for the output format.
Stage and commit the .dev/ directory so the worktree is clean for dev/how:
chore: dev/what — [short feature name]
Prototype code must already be deleted (see Rules).
.dev/: prd.md, optionally research.md, learning tests, and reference filesnpx claudepluginhub codethread/claude-code-plugins --plugin devGuides creation, editing, and verification of skills for AI coding agents using test-driven development with subagent scenarios. Use when authoring or debugging skills.