From Vision to Done: The Requirements-First Development

April 29, 2026

agentic development

From Vision to Done: The Requirements-First Development

TL;DR

Requirements-First captures a clear, testable vision and translates it into concise requirements, specifications, and tests; agents then deliver features in short sprints so writing code becomes the final, mechanical step.

Software is most successful when the team shares a clear, testable understanding of what to build. The Requirements-First skill turns that understanding into a lightweight, repeatable workflow that produces three canonical artifacts: requirements, specifications, and tests. Those artifacts build the application’s context so thoroughly that writing the code becomes the easiest step.

Why Requirements-First?

Too often, development starts with code or UI mockups before the problem is fully understood. That leads to wasted effort, shifting scope, and brittle implementations. Requirements-First reverses this by capturing value, behavior, and constraints up front; it reduces ambiguity, shortens feedback loops, and improves predictability.

The Skill — Overview

The full development process happens over three stages: Requirements Gathering, Planning, and Development.

Requirements Gathering

Requirements gathering is a disciplined process with four core phases:

  1. Capture the vision

    • You or another developer collect stakeholder goals, customer outcomes, acceptance criteria, and non-functional requirements (performance, security, compliance). This can be free text, blurbs, or transcripts; you do not have to get fancy with the structure.

  2. Create the requirements

    • A PO agent takes the vision and generates requirements and requirement questions.
    • Keep requirement files small — one epic per file. An epic will have multiple user stories. User stories will have multiple acceptance criteria.
    • The PO agent will raise questions either on an epic or in a general question file.
    • Answer all the questions, then ask the agent to review and update the requirements. Repeat this step until no more questions are raised and you approve the completed requirements.

  3. Write specifications (how it should behave)

    • If you have constraints or examples that the architecture must follow, create an ArchitectureGuidelines.md file and document them.
    • An architect agent will review requirements and guidelines and create the specs, translating requirements into executable artifacts: data shapes, domain rules, API contracts, UX flows, and error cases.
    • Include examples and edge cases. Keep specs small and testable.
    • Start the review loop. The architect will also raise questions or decision records for you to answer. Repeat until the architecture is approved.

  4. Define tests (verify behavior)

    • A QA agent will create test definitions (not implementations) based on requirements and any specs that require direct tests.
    • Tests become living documentation and a safety net for future changes.
    • Start the review loop.

Each stage produces artifacts that feed the next: requirements inform specs, specs generate tests, and tests validate the implementation.

Planning & Prioritization

Planning and prioritization brings agile into the agentic process. This helps focus the agent team to complete a single vertical, testable slice of a feature at a time. That prevents having hundreds of files to review and gives you a chance to provide feedback and course-correct along the way in smaller chunks.

  1. Create the backlog
    • An architect agent creates a backlog of work items. Work items (WIs) accomplish REQ, SPEC, and/or TESTs.
    • Work items include development details, tasks that need to be accomplished, dependencies, and other definitions of done.
  2. Create a delivery plan
    • A PO agent creates the sprints required to complete development.
    • A sprint has a goal to deliver a small slice of development that you can validate and give feedback on.
    • You can give feedback on individual work items in the sprint backlog or on the general state of the product.

Development

Development completes the organized sprints and lets you give feedback a sprint at a time, course-correcting the product by updating requirements as needed each sprint.

  1. Develop the sprint
  • The agent team completes the development of the sprint: coding, tests, code reviews, architecture review, and AC reviews.
  • You will have a list of user acceptance tests to complete manually; you will pass, fail, or update these items. Generally, you may also give feedback when you notice aspects of the user experience that need adjustment.
  1. Feedback loop
  • Ask your agent team to update REQ, SPEC, TEST, add future WIs, and adjust sprints if needed.
  • Once requirements and plans are updated, repeat development on the sprint until completed.
  1. Sprint completion
  • The sprint, work items, and requirements are marked as completed.

How This Makes Development Easier

  • Clear what the system does — no more wondering who remembers how this is supposed to work.
  • Code can be generated from this detailed context.
  • Changes to code or requests for enhancement are compared with a central set of requirements.
  • Moving code to a new tech stack has a starting point: when going from web to mobile, you have requirements and tests; you’ll need to recreate the spec with new guidelines or maintain two sets of guidelines.

In short: with requirements and specs defined, code becomes the mechanical step of realizing a well-understood behavior rather than inventing requirements on the fly.

Adoption Tips

  • Start small: create a vision for a product or tool for yourself.
  • Create an agent team with an orchestrator, recruiter agents, and the agents mentioned above.
  • Create a skill to build requirements, plan items, and iterate on development.

Closing

Requirements-First is a cultural and process shift that pays back in predictability, quality, and developer happiness. By building context with requirements, specifications, and tests, teams make the code the natural final step from vision to done.

Templates

REQ template

REQ- — Short title

Short description: One-line summary of the requirement.

Priority: <Must Have / Should Have / Nice to Have>

User Story: As a , I want so that .

Acceptance Criteria: Provide explicit, testable acceptance criteria (Gherkin preferred):

Given <precondition>
When <action>
Then <expected outcome>

Notes / Dependencies:

  • Links, implementation constraints, or dependencies (e.g., related REQs or infra items).

SPEC template

Specs will come in many forms depending on what is being specified. The decision record template below helps review options so you can pick the right path.

  • Code structure
  • Authentication
  • Vendor integration
  • Tech stack
  • UX style guide
  • Infrastructure

TEST.yml template

Tests are language-agnostic definitions of expected behavior. So no matter what the future implementation of the application may be, the tests will have a definition.

- id: TEST-<req-id>
  title: Short, descriptive title of the test
  type: integration   # one of: unit | integration | e2e
  priority: must      # must | should | nice
  traces:
    reqs: [REQ-<id>]
    specs: [SPEC-<id>]
  preconditions:
    - <list any setup or required state>
  steps:
    - <step 1 — action to perform>
    - <step 2 — follow-up action or verification step>
  expected_result: >
    <Describe the observable outcome or assertion(s) that determine success.>
  notes: |
    <Optional notes or implementation considerations.>

DECISION RECORD (DEC) template

---
status: <draft|proposed|approved|deprecated>
owner: <role or team>
version: 1.0
supersedes: <optional — previous DEC id or none>
---

# DEC-<id> — Short title

## Context
Describe the background, constraints, and forces that make the decision necessary.

## Options Considered
| # | Option | Notes |
|---|--------|-------|
| 1 | <Option A> | Brief notes on tradeoffs |
| 2 | <Option B> | Brief notes on tradeoffs |

## Decision
State the chosen option clearly and concisely.

## Rationale
Explain why this option was chosen, referring to relevant REQs/SPECs and measurable criteria where possible.

## Consequences
- Positive: list benefits and opportunities
- Negative: list risks, costs, and mitigation plans

## Status
Draft / Approved / Superseded — include approver or date if relevant

WORK ITEM (WI) template

---
 id: WI-<nn>
 title: Short title
 epic: Epic <##> — <epic title>
 status: backlog   # backlog | in_progress | complete
 priority: must_have  # must_have | should_have | nice_to_have
 estimated_effort: <e.g., 2-4 hours>
 dependencies: []
 version: 1.0
---

# WI-<nn>: Short title

## Purpose
A short paragraph describing why this work item exists and what it delivers.

## Requirements Coverage
List the REQ IDs covered by this work item (e.g., REQ-042)

## Specifications Coverage
List SPEC IDs covered (e.g., SPEC-040)

## Test Coverage
List TEST IDs that verify this WI (e.g., TEST-241)

## Tasks
- [ ] Task 1
- [ ] Task 2

## Acceptance Criteria
- [ ] Explicit, testable acceptance criteria (cross-reference TEST- and SPEC- IDs where possible)

## Dependencies
- Any blocking or related work items or infra

## Estimated Effort
Estimated time or story points

## Notes
Implementation notes, suggested tools, commands, or helpful links

SPRINT template (agentic sprint)

---
 status: <planned|in_progress|complete>
 owner: <PO | Team>
 version: 1.0
 supersedes: <optional — previous sprint id or none>
 source_vision: <vision version, e.g., v1.1>
---

# Sprint <n> — Short title

## Goals
A brief list of sprint goals and success criteria.

## Sprint Backlog
WorkItems assigned to this sprint (table):

| Title | WorkItem_ID | Status |
|-------|-------------|--------|
| Example WI title | WI-01 | backlog |

## Definition of Done
- [ ] All tasks from assigned WIs complete
- [ ] Code review approved
- [ ] QA tests for covered TEST-### IDs pass
- [ ] Architect validated against covered SPEC-### IDs
- [ ] PO/Driver validated against covered REQ-### IDs
- [ ] Driver accepted deliverable

## Driver Validation Plan
Table or steps for PO/Driver to validate sprint deliverables end-to-end (build, test, UAT steps).

## Code Review Feedback
Record blocking and non-blocking findings discovered during code review.

## UAT & Feedback
Document PO/Driver feedback and acceptance decision.

## Date Completed / Status
Completion date and approver when sprint is complete.