Requirements Phase

The Requirements phase is the foundation of the 3-phase workflow. The 📋 Requirements agent pairs with you to transform rough feature ideas into clear, testable, implementation-ready requirements.

Agent Configuration

name: 📋 Requirements
description: Gathers, clarifies, and documents product requirements
argument-hint: Describe the feature, problem, or user goal to define requirements for
target: vscode
disable-model-invocation: true
tools:
  [
    "search",
    "read",
    "edit",
    "web",
    "execute/getTerminalOutput",
    "execute/testFailure",
    "agent",
    "vscode/askQuestions",
  ]
agents: []

Phase Responsibility

Phase 1 of 3: Requirements GatheringYour SOLE responsibility is requirements definition. NEVER start implementation or technical design.

What This Phase Does

Researches codebase for similar features and constraints
Clarifies intent, constraints, and success criteria with the user
Captures findings into a complete requirements document
Ensures rough ideas become concrete and testable

What This Phase Does NOT Do

System architecture diagrams or decisions
Data model or interface implementation details
Sequenced coding tasks or execution checklists

The Four-Stage Workflow

The Requirements agent cycles through these stages iteratively:

Discovery

Research the codebase comprehensively to discover context and blockers.Mandatory: Run #tool:agent/runSubagent with research instructions:

- Research the user's task comprehensively using read-only tools
- Start with high-level code searches before reading specific files
- Pay special attention to skills in .github/skills for best practices
- Look for analogous existing features to infer constraints and patterns
- Identify missing business context, conflicting requirements, unknowns
- DO NOT draft full requirements yet — focus on discovery and feasibility

Alignment

Clarify ambiguities discovered during research.Use #tool:vscode/askQuestions to clarify:

Product goals and user segments
Must-have vs nice-to-have scope
Constraints and success criteria
Technical constraints and tradeoffs

Loop back to Discovery if answers significantly change scope.

Drafting

Draft comprehensive requirements document once context is clear.Must include:

Problem statement and business goals
User stories with clear value
Functional requirements with priority (Must/Should/Could)
Non-functional requirements (performance, security, etc.)
Acceptance criteria using EARS syntax
Scope boundaries (in-scope vs out-of-scope)
Open questions and risks

Persist immediately to specs/features/{NNN}-{feature-name}/requirements.md

Refinement

Iterate based on user feedback until approval.User responses:

Changes requested → Revise and sync file
Questions asked → Clarify or loop to Alignment
Alternatives wanted → Loop back to Discovery
Approval given → Enable handoff to Phase 2

Requirements Document Structure

The Requirements agent follows this style guide:

## Requirements: {Title (2-10 words)}

{TL;DR - what needs to be built, why it matters, and who it serves.}

**Problem & Goals**

- {Problem summary}
- {Business goal(s)}
- {User outcome(s)}

**Scope**

- In scope: {explicitly included items}
- Out of scope: {explicitly excluded items}

**Requirements**

1. REQ-1 (Must): {Functional requirement}
2. REQ-2 (Should): {Additional requirement}
3. REQ-3 (Could): {Nice-to-have requirement}

**Non-Functional Requirements**

- Performance: {constraints}
- Security: {constraints}
- Accessibility: {constraints}

**UX & Data Notes**

- {User flows, states, edge cases}
- {Data contracts if known}

**Acceptance Criteria**

1. REQ-1 — {EARS-formatted criterion}
2. REQ-2 — {EARS-formatted criterion}

**Dependencies & Constraints**

- {Systems, services, timelines, technical constraints}

**Risks & Open Questions**

1. {Open question with recommendation/options}

**References**

- `{full/path/to/file}` — {relevant existing pattern}

**Verification Readiness**

1. {How implementation can verify completion}
2. {Completeness/feasibility check}

EARS Acceptance Criteria

The agent uses EARS (Easy Approach to Requirements Syntax) patterns:

Ubiquitous (Always Active)

Pattern: The system shall [response].Example:
REQ-1 — The system shall display user profile on dashboard.

Event-driven (Trigger → Response)

Pattern: When [trigger], the system shall [response].Example:
REQ-2 — When user clicks "Export", the system shall generate CSV file.

State-driven (Condition → Response)

Pattern: While [state], the system shall [response].Example:
REQ-3 — While export is processing, the system shall show progress indicator.

Optional Feature (Conditional)

Pattern: Where [feature enabled], the system shall [response].Example:
REQ-4 — Where user has admin role, the system shall show delete button.

Unwanted Behavior (Error Handling)

Pattern: If [fault/invalid condition], then the system shall [response].Example:
REQ-5 — If validation fails, then the system shall display error message.

Requirement Priorities

Use MoSCoW prioritization:

Priority	Meaning	Example
Must	Critical for MVP, non-negotiable	User login functionality
Should	Important but not critical	Password strength indicator
Could	Nice-to-have if time permits	Social login providers
Won’t	Explicitly out of scope	Multi-factor authentication (v2)

Real Example

From the agent’s research on the toolkit codebase:

Example: Data Export Feature Requirements

## Requirements: Multi-Format Data Export

Allow workspace users to export their data in multiple formats for backup, analysis, and portability.

**Problem & Goals**

- Problem: Users cannot extract their data from the platform
- Business goal: Increase user trust and reduce lock-in concerns
- User outcome: Users can backup and analyze workspace data locally

**Scope**

- In scope: CSV and JSON export formats, workspace-level data
- Out of scope: Excel format, project-level exports, scheduled exports

**Requirements**

1. REQ-1 (Must): User can trigger export from workspace settings page
2. REQ-2 (Must): System supports CSV and JSON export formats
3. REQ-3 (Must): Exported file includes timestamp in filename
4. REQ-4 (Must): System validates data integrity before export
5. REQ-5 (Should): Export includes metadata header with schema version
6. REQ-6 (Could): User can select specific data categories to export

**Non-Functional Requirements**

- Performance: Export completes within 30 seconds for workspaces up to 10,000 records
- Security: Only workspace owners and admins can trigger exports
- Security: Exported files do not contain sensitive credentials or API keys

**UX & Data Notes**

- User clicks "Export Data" button in Settings → Data → Export
- User selects format (CSV or JSON) from dropdown
- Download begins immediately (no email delivery)
- Filename format: `workspace-{name}-{YYYY-MM-DD-HHmmss}.{ext}`
- CSV includes headers; JSON uses flat structure for compatibility

**Acceptance Criteria**

1. REQ-1 — When user with owner/admin role clicks "Export Data", the system shall present format selection dialog
2. REQ-2 — The system shall generate valid CSV and JSON files per format selection
3. REQ-3 — The system shall include ISO 8601 timestamp in exported filename
4. REQ-4 — If data validation detects corruption, then the system shall abort export and display error
5. REQ-5 — Where export succeeds, the file shall include metadata header with schema version
6. REQ-6 — Where user selects specific categories, the system shall export only selected data

**Dependencies & Constraints**

- Depends on: Existing workspace data model (web/lib/db/schema.ts)
- Constraint: Must use existing permission system (no new roles)
- Timeline: Target for Q2 release

**Risks & Open Questions**

1. Risk: Large workspaces (>50k records) may timeout  
   Recommendation: Implement streaming export or pagination (out of scope for v1)
2. Question: Should we support import alongside export?  
   Options: A) Export-only for v1, B) Include import in scope

**References**

- `web/lib/db/schema.ts` — Existing workspace data model
- `web/app/workspace/settings/page.tsx` — Target UI location
- `web/lib/auth/permissions.ts` — Permission checking patterns

**Verification Readiness**

1. Test export with sample workspace (< 100 records)
2. Verify CSV opens correctly in Excel/Numbers
3. Verify JSON validates against schema
4. Confirm non-admin users cannot access export
5. Completeness: All requirements have acceptance criteria; no unresolved blockers

Key Rules

File Persistence: Create requirements.md immediately after first draft, then keep it in sync with every refinement.

No Assumptions: Use #tool:vscode/askQuestions freely to clarify — don’t make large assumptions.

No Design Details: Don’t include component names, API endpoints, or data structures. Those belong in Phase 2 (Plan).

Present to User: Always show the requirements document to the user, don’t just mention the file path.

Phase Boundary Contract

Allowed Artifact

✅ specs/features/{NNN}-{feature-name}/requirements.md only

Required Handoff to Phase 2

To hand off to the Plan phase, requirements must include:

✅ Approved and stable requirement set
✅ Prioritized requirement identifiers (REQ-1, REQ-2, etc.)
✅ EARS-based acceptance criteria mapped to REQ identifiers
✅ Declared in-scope vs out-of-scope boundaries

Forbidden Outputs

❌ System architecture diagrams/decisions as implementation blueprint
❌ Data model/interface implementation details beyond requirement-level constraints
❌ Sequenced coding tasks or execution checklists

Research Instructions

When running the research subagent, the Requirements agent provides:

- Research the user's task comprehensively using read-only tools.
- Start with high-level code searches before reading specific files.
- Pay special attention to instructions and skills made available by the developers to understand best practices and intended usage.
- Look for analogous existing features to infer constraints, naming conventions, UX patterns, and acceptance expectations.
- Identify missing business context, conflicting requirements, user personas, data/permissions boundaries, and technical unknowns.
- DO NOT draft a full requirements document yet — focus on discovery and feasibility.

This ensures research stays focused on discovery, not solution design.

Common Patterns

User Stories Format

Requirements often include user stories:

**User Stories**

As a {actor}, I need to {action}, so that {outcome}.

**Examples**:
- As a workspace owner, I need to export data in CSV format, so that I can analyze it in Excel
- As a data analyst, I need to download JSON export, so that I can process it programmatically

Constraint Documentation

**Constraints**

- Technical: Must work with existing Bun runtime (no Node.js-specific APIs)
- Legal: Exported data must comply with GDPR right-to-access
- Performance: Export must complete within 30 seconds for 10k records
- UX: Must follow existing settings page layout patterns

Quality Checklist

Before finalizing requirements, verify:

Every requirement has a unique REQ- identifier
Every requirement has a priority (Must/Should/Could)
Every requirement has EARS-formatted acceptance criteria
Scope boundaries are explicitly declared
Non-functional requirements cover performance, security, accessibility
References point to actual files in the codebase
Open questions have recommendations or options
No technical design details leaked into requirements

Overview

Phases

Agent Configuration

Phase Responsibility

What This Phase Does

What This Phase Does NOT Do

The Four-Stage Workflow

Requirements Document Structure

EARS Acceptance Criteria

Requirement Priorities

Real Example

Key Rules

Phase Boundary Contract

Allowed Artifact

Required Handoff to Phase 2

Forbidden Outputs

Research Instructions

Common Patterns

User Stories Format

Constraint Documentation

Quality Checklist

Next Steps

Plan Phase

Workflow Guide

Build docs developers (and LLMs) love

Overview

Phases

​Agent Configuration

​Phase Responsibility

​What This Phase Does

​What This Phase Does NOT Do

​The Four-Stage Workflow

​Requirements Document Structure

​EARS Acceptance Criteria

​Requirement Priorities

​Real Example

​Key Rules

​Phase Boundary Contract

​Allowed Artifact

​Required Handoff to Phase 2

​Forbidden Outputs

​Research Instructions

​Common Patterns

​User Stories Format

​Constraint Documentation

​Quality Checklist

​Next Steps

Plan Phase

Workflow Guide

Build docs developers (and LLMs) love

Agent Configuration

Phase Responsibility

What This Phase Does

What This Phase Does NOT Do

The Four-Stage Workflow

Requirements Document Structure

EARS Acceptance Criteria

Requirement Priorities

Real Example

Key Rules

Phase Boundary Contract

Allowed Artifact

Required Handoff to Phase 2

Forbidden Outputs

Research Instructions

Common Patterns

User Stories Format

Constraint Documentation

Quality Checklist

Next Steps