# Specify > Use for design-partner mode: discovery, tradeoffs, decisions, and agreed design artifacts. - **Type:** Skill - **Install:** `agentstack add skill-kreek-consult-specify` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [kreek](https://agentstack.voostack.com/s/kreek) - **Installs:** 0 - **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [kreek](https://github.com/kreek) - **Source:** https://github.com/kreek/consult/tree/main/consult/skills/specify ## Install ```sh agentstack add skill-kreek-consult-specify ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # Specify ## Iron Law `DESIGN-PARTNER MODE: READ THE SYSTEM, DECIDE THE SHAPE TOGETHER, THEN RECORD WHAT WAS AGREED.` ## When to Use - Feature work, refactors, migrations, or bug fixes that touch more than one contract, component, module boundary, state transition, or domain invariant. - Adding or changing a public surface: function signature, exported type, endpoint, event/queue payload, CLI flag, environment variable, config key, file format, or database schema/migration step. - Choosing shared project/package/module structure or a structural runtime dependency such as a framework, database, ORM, auth client, SDK, state library, or job queue. - Ambiguous or risky implementation intent where the agent should turn fuzzy goals into an approved design direction before code lands. - Significant new code with no caller-facing boundary: a substantial new module or component, new or rewritten non-trivial logic or an algorithm, or a deliberate change to observable behavior. Agree the plan or shape before implementing. - The user asks to design, specify, draft an ADR/RFC/tech spec, or capture a design note. - `workflow` chooses the Design-partner mode because architecture, domain modeling, caller-facing interfaces, cross-boundary contracts, or multi-component choices need human participation. ## When NOT to Use - Typos, formatting, comment-only edits, or docs-only changes with no executable or contract effect. - Internal helper extraction with no caller-visible boundary. - Narrow bug fixes that restore intended behavior with no contract, state, data, or boundary change. - Pure dependency bumps with no public surface change. - Small local file moves or private implementation organization that does not establish a package/module boundary future work will depend on. - The user wants a concrete task plan after the design is already settled; use workflow or the harness planning mode instead. - A caller-facing interface is already concrete and only needs approval; use `contract-first` directly. ## Core Ideas 1. Specify turns fuzzy intent into shared design. Its output is agreement on the current surface, target shape, tradeoffs, decisions, and open questions; it is not autonomous coding or document theater. 2. Stay above implementation sequencing. Specify owns contracts, states, tradeoffs, risks, and decisions. File-by-file edits, pseudocode, and task checklists belong to planning after the design direction is agreed. 3. Contracts are any caller-facing boundary: function signature, module export, public type, error vocabulary, CLI flag, environment variable, database schema or migration step, event payload, file format, or config key. "API" does not mean only HTTP. 4. Consultation is not constant interruption. Ask when a decision would be expensive to reverse (caller-facing shape, shared structure, data model, or structural dependency) or when the work is significant enough that the user should shape it: a substantial new module or component, non-trivial logic, or a deliberate observable behavior change. Routine, local, and disposable work does not need a gate. ## Workflow 1. **Frame the design task.** State the intended outcome and the decision that needs collaboration. Say that coding waits until the shape is agreed. 2. **Read before proposing.** Summarize current contracts, data shapes, states, constraints, and ownership with citations. For greenfield work, name the adjacent convention. 3. **Learn with disposable spikes only when needed.** If code is the fastest way to reveal the shape, ask first, keep it local and small, and discard or rewrite it after convergence. 4. **Propose one target shape.** Recommend one option, name the key tradeoff, and mention rejected alternatives only when they explain the choice. 5. **Ask the next design question.** Ask the smallest question that changes the shape: approve, revise, or rule out the recommendation. List secondary uncertainties as notes, then revise the proposal from the user's answer. 6. **Route specialist design risks.** Use `domain-modeling` for data, state, effects, and invariants; `contract-first` for contract approval; and the domain skill for API, persistence, async, security, errors, observability, performance, UI, accessibility, or release risks. 7. **Converge before planning.** Iterate until the human agrees on the design direction or rules it out. Then hand off to planning, implementation, proof, or review. 8. **Capture only what will be used.** If an artifact is needed, choose the smallest useful form after convergence and save it where it will rot least: private `.pi/specify/` for local agent memory, or checked-in `docs/` when the team should keep it. ## Artifact Types - ADR: accepted decision with context and consequences. - RFC: proposal needing review, with tradeoffs and approval state. - Tech spec: implementation-ready design for a scoped change, including proof obligations. - Note: lightweight memory that is useful but not yet a formal decision. When an artifact lists interfaces or domain shapes, mark each one approved or proposed, so the build inherits an explicit list of what still needs sign-off. ## Verification - [ ] Current surface is backed by `file:line` evidence or named greenfield conventions. - [ ] The proposed shape recommends one option, names the key tradeoff, compatibility pressure, unresolved decisions, and proof obligations. - [ ] User-owned decisions are approved, narrowed, or explicitly left open. - [ ] Open questions are genuine blockers that change the design, not template residue or deferrable details. - [ ] Caller-facing interfaces have `contract-first` approval before implementation, or implementation remains out of scope. - [ ] An approved design or RFC approves the direction, not the concrete interfaces or domain structure. Those still get `contract-first` and `domain-modeling` applied during build, with sign-off on the concrete shapes. - [ ] Any artifact records the agreed shape and has a purpose-fit destination. ## Tripwires Use these when the shortcut thought appears: - A design written before reading code is speculation. - Building the whole thing to discover the shape turns discovery into unapproved implementation. - A design file is not approval for a contract, migration, config surface, or caller dependency. - A question barrage is less useful than one recommended decision and notes. - Design-partner means the agent proposes concrete options; the human approves, revises, or rules them out. - Open questions should not wait for code review when they block the design. ## Handoffs - `contract-first`: contract approval. - `documentation`: artifact quality, audience, rot risk, and docs placement. - `domain-modeling`: data shapes, invariants, transitions, and effects. - `architecture`: boundaries, ownership, layering, and system shape. - `proof`: design proof obligations. - `api`, `database`, `async-systems`, `security`, `error-handling`, `observability`, `performance`, `ui-design`, `accessibility`, and `release`: specialist lenses when the design touches those domains. ## References - ADR template: status, date, context, decision, consequences. - The standalone Pi contract-first runtime package has been removed; use this skill directly when interface design needs an explicit gate. ## Source & license This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [kreek](https://github.com/kreek) - **Source:** [kreek/consult](https://github.com/kreek/consult) - **License:** MIT Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/skill-kreek-consult-specify - Seller: https://agentstack.voostack.com/s/kreek - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.