Spec Generation — Single-Session spec.md from intent.md

Spec generation is the process of translating an accepted intent.md into a formal technical requirements and design document (spec.md). In the AI-native SDLC, requirements and design collapse into a single prompted session where the AI agent is strictly constrained by organizational policy skills (security, brand, compliance, and UX) to surface conflicting constraints before any code is written.

Scorecard question: How do you turn intent into technical specifications and requirements (spec.md)? Max‑score answer (3 pts): Single-session spec.md generated under brand/security/UX skills; flagged concerns resolved before build starts.

Why this matters in 2026

In traditional organizations, requirements elicitation and architecture design are handled by separate teams in sequential handoffs. Analysts produce requirement specifications over weeks, and architects or designers spend weeks translating them into technical designs. This handoff introduces delay, loses original intent, and postpones security or compliance discovery to late review stages.

In an AI-native workflow, a product owner or tech lead runs a single prompted session that ingests intent.md and applies institutional policies encoded as skills (.claude/skills/, .cursor/skills/, .agents/skills/). The model drafts spec.md and highlights policy conflicts immediately, allowing teams to resolve tradeoffs before engineering implementation begins.

What “max score” actually looks like

A max-score Q5 setup demonstrates four key capabilities:

1. Direct derivation: Every spec.md explicitly traces back to a committed intent.md.
2. Policy enforcement via skills: The agent evaluates the feature against active security, UX, and compliance skills during drafting.
3. Flagged concerns section: The agent isolates contradictions or unaddressed edge cases under a dedicated section for policy owners.
4. Human sign-off: The product owner and a technical lead approve spec.md before plan mode or code generation starts.

Step-by-step implementation

1. Verify policy skills are present.

   Confirm your repository or global agent environment contains versioned skills for core policies:

   • Security standards (e.g., authentication, data sanitization)
   • UX and brand guidelines (e.g., design system tokens, responsive rules)
   • Architectural standards (e.g., API schemas, database access rules)

2. Generate spec.md from intent.md.

   Launch an agent session with your policy skills loaded. Provide intent.md and instruct the model to produce spec.md:

   Claude Code

   Switch to Plan mode (Shift+Tab) and run:

   Read intent/FEATURE_SLUG.md. Apply our skills for security, brand, and UX.
   Generate spec/FEATURE_SLUG.md documenting functional requirements, API
   contracts, data models, and edge cases. Flag any policy contradictions
   under a Flagged Concerns section. Do not modify application code.

   Cursor

   Stay in Ask or Plan mode with .cursor/skills/ active:

   Analyze intent/FEATURE_SLUG.md against the rules and skills in our repo.
   Create spec/FEATURE_SLUG.md specifying endpoints, data models, and UI flows.
   Highlight any architectural or security conflicts for team review.

   Codex

   Run in the Codex CLI using /plan:

   /plan Read intent/FEATURE_SLUG.md and generate a comprehensive spec.md.
   Apply all policies from .agents/skills/. List unresolved tradeoffs under
   Flagged Concerns.

3. Resolve flagged concerns.

   Review the flagged concerns with relevant stakeholders (e.g., security engineer or design lead). Update constraints in spec.md based on their decisions.

4. Commit the completed spec.

   Commit spec/FEATURE_SLUG.md alongside the corresponding intent.md:

   git add spec/FEATURE_SLUG.md
   git commit -m "docs(spec): technical specification for FEATURE_SLUG"

5. Approve before implementation.

   Obtain explicit sign-off from the technical lead or product owner. This approval serves as the gateway to Stage 3: Build (plan.md).

Common pitfalls

• Skipping policy skills: Allowing the agent to draft a specification based on generic knowledge rather than project-specific security and brand constraints.
• Burying tradeoffs: Letting the agent make silent architectural choices without surfacing contradictions in a dedicated concerns section.
• Editing code during specification: Writing unit tests or scaffolding code before spec.md is approved, which wastes engineering time when requirements shift.

How to verify you’re there

• spec.md is committed and explicitly references its parent intent.md.
• Flagged concerns are explicitly addressed with written rationale before the build phase starts.
• Elapsed time from intent.md commit to spec.md commit is measured in hours.
• Engineers implement from an approved specification without discovering missing architectural decisions.

Further reading

AI-Native SDLC Design Stage Deep-dive into collapsing requirements and design with policy skills.

Q6 · Agent Skills How to write and organize machine-readable policy skills.

The Artifact Chain Understand the flow from intent.md to spec.md and plan.md.