Design: write spec.md

The design stage converts an accepted intent.md into a committed spec.md with requirements, architecture, acceptance criteria, and flagged policy concerns. A product owner accepts the outcome, while technical or policy owners resolve high-risk questions before an implementation plan or application code is allowed to start.

Traditional: Requirements and design are separate phases run by separate teams. Analysts formalize the idea; designers parse those back into a design. The separation exists for accountability, but it is slow and lossy.

AI-native: Both phases happen in one prompted session. The agent takes intent.md and produces a requirements and design spec, constrained by the organization’s skills, with areas of concern flagged.

For UI work, create a mock from intent.md with an approved design tool, configured Figma integration, or image input. Iterate, record human acceptance, then hand the versioned artifact to the coding agent. The four-artifact composition lives in the Design pipeline.

Before you begin

• An accepted intent.md
• Brand, security, compliance, and UX policies written as skills
• Product-owner access to Claude, Cursor, or Codex — no engineering skill required

Prerequisites: Plan (intent.md) and at least one policy skill.

Produce the spec

1. Open a session with the organization’s skills available and attach intent.md.

2. Point the prompt at intent.md, name the constraints, and demand flagged concerns.

   Run this by hand at first. Then encode it as an organization-level slash command or skill. From there, make acceptance of intent.md the trigger: a non-interactive job fires on the merge, runs the pass with skills loaded, and opens spec.md as a pull request. The product owner’s first involvement is then the review.

3. Review the spec against the idea.

   Does the spec solve the stated problem? Are the open questions from intent.md answered or carried forward?

4. Work through flagged concerns first.

   These are the points an analyst would have escalated. Resolve each one with its policy owner before engineering sees the spec.

5. Commit spec.md alongside intent.md.

   The file pair records what was asked for and what was decided.

6. Decide whether the spec and intent progress to build.

   Consult a technical lead for anything the organization classes as higher risk. A human teammate always makes this call. Accepting the spec starts plan mode in Build.

Use the following prompt (replace nothing except the attached file):

Read the attached intent.md and produce a requirements and design spec
for integrating it into our existing codebase. Apply the skills available
to you so the plan conforms to our brand guidelines, security policies,
and UX standards. Document the spec fully as spec.md, ready to hand to
the engineering team. Describe clearly any areas of concern, especially
where you cannot satisfy contradicting policies.

Claude Code

Stay in plan mode (Shift+Tab) until the spec is accepted:

Read intent/FEATURE.md. Produce spec.md using our skills for brand,
security, and UX. Flag contradictions. Do not edit application code.

Cursor

Stay in Ask or Plan mode. Attach intent.md and the skill files under .cursor/skills/ (Cursor also reads .claude/skills/).

Codex

Use /plan and attach intent.md. Encode the same policy as skills under .agents/skills/ or ~/.agents/skills/.

Governance

Live policy is read and applied while the spec is written. Skills are constraints on the spec. The spec, the prompt that produced it, and the skill versions in force are all logged in version control. The product owner signs off the spec and routes flagged concerns to named policy owners.

A skill is advisory. A policy that must always hold also needs a deterministic check later (a hook or a review pass). See Build and Deploy.

Verify

• spec.md is committed next to the accepted intent.md.
• Every flagged concern has an owner or is carried forward as an open question.
• A human has accepted the spec before any implementation plan starts.

Leading indicator: elapsed time between the intent.md commit and the spec.md commit for the same change.

Lagging indicator: requirements rework after build starts — spec.md commits dated after the first plan.md commit for the same change.

Apply the play in your tool

Claude Code adapter Combine CLAUDE.md context with project skills in .claude/skills/.

Cursor adapter Combine scoped rules, project skills, images, and approved MCP tools.

Codex adapter Combine AGENTS.md, .agents/skills/, images, MCP, and repository inspection.

Hand the accepted spec to build

Hand the accepted pair to engineering and continue with Build.