Part 7. Feature Specification

After the project rules you have a roadmap, but still no permission to write code. The next step is to specify the first feature. In our tutorial project the first phase is called Hello Hono: install Hono, start a TypeScript server, serve a minimal HTML page, and check types.

Feature specification is needed so the agent does not turn a small phase into half a product. It answers three questions:

• what is and is not within the task boundaries;
• in what order to implement;
• what facts must pass to accept the result.

The rule for this tutorial: the text specification guides the agent, but merge must be decided by facts. Therefore validation.md is written immediately as a set of verifiable assertions, not as a general wish list.

Feature Specification Structure

specs/
  2026-05-01-hello-hono/
    requirements.md
    plan.md
    validation.md

The date makes the work order clear. The kebab-case name links the folder to the branch.

Creating a Branch

git checkout -b phase-1-hello-hono

Or ask Qwen Code:

Find the next incomplete phase in @specs/roadmap.md.
Create a branch for it.
Do not implement code yet.

First ask me about the feature specification.

Check git status so you do not start a feature on top of unfinished work.

Prompt for Qwen Code

Find the next phase in @specs/roadmap.md and create a feature specification.

Create:
- specs/YYYY-MM-DD-feature-name/requirements.md
- specs/YYYY-MM-DD-feature-name/plan.md
- specs/YYYY-MM-DD-feature-name/validation.md

Before writing files ask me exactly three grouped questions:
1. Boundaries: what should and should not be included in the feature
2. Decisions: key implementation decisions
3. Context: tone, constraints, risks and expectations for validation

Use @specs/mission.md and @specs/tech-stack.md as reference.
Do not write implementation code.

Separate Clarification Step

In GitHub Spec Kit there is a dedicated step /clarify between intent and plan: the agent asks a series of pointed questions about places where requirements allow different interpretations. We reproduce this step inside the "three grouped questions" block, but for a large feature it is useful to extract clarification separately — especially if the first answers opened new ambiguities.

Sign that a separate clarification is needed:

• the agent itself says "I can interpret X as A or as B";

• two places in the specification are outwardly consistent but require mutually exclusive decisions in code;
• the decision depends on an external service/agreement the agent does not know about;
• your own answers contradict each other.

Prompt for clarification:

Before writing requirements.md, plan.md and validation.md, list all places
where you still have alternatives. Ask me exactly one question per place: what to choose
and why. Do not suggest your answer before my choice. Do not guess. If there are no alternatives,
write "no clarification needed".

If the agent returns 0–2 pointed questions, usually you should answer and continue. If 6+ — this is a signal that the phase is too large or that the constitution leaves too many open decisions; better stop, update mission.md/tech-stack.md, and return to specification later.

Example requirements.md

# Requirements — Hello Hono

## Boundaries

Install and configure Hono with a development server via tsx. Add one GET / route that returns a minimal HTML page via Hono JSX. Confirm that TypeScript works end to end.

## Out of Scope

- No database.
- No authentication.

- No test framework setup.
- No production deployment.
- No multi-page navigation.

## What Must Not Change

- Strict mode in `tsconfig.json` stays enabled.
- `package.json` does not receive dependencies not listed in `tech-stack.md`.
- `.gitignore` does not shrink; additions are allowed, removals are not.
- Existing `npm run typecheck` scripts continue to work.

## Decisions

- Pin Hono version without ^ or ~.
- Keep strict TypeScript mode.
- Use HTML with server-side rendering, not a client framework.

## Context

This phase proves basic operability. It should be intentionally small. The home page may contain one heading, one tagline, and minimal structure.

Negative Requirements: "What Must Not Change" Block

The "Out of Scope" section answers "what we do not add". The "What Must Not Change" section answers a different question — "what already works and must continue working". These two lists overlap but do not coincide.

Simple example. "Out of Scope" says: "we do not add authentication". "What Must Not Change" says: "the existing GET / route continues to return HTML with <h1>AgentClinic</h1>".

Without negative requirements the agent easily "fixes" something that was not broken: renames a route, changes the response format, rewrites a field name in the database. Some of these regressions are caught by tests, but not all: if there is no test for the old behavior, nothing except explicit "do not change" will stop the agent.

Good items in this block:

• which public URLs remain the same;
• which field and table names are not renamed;
• which response formats do not change;
• which dependencies are not updated "along the way";
• which configuration files remain untouched.

If the feature should not preserve anything at all (for example, the first project phase where there are no URLs or tables yet), leave the section empty with a note "no existing behavior to protect".

Form of Formulations: EARS and Given/When/Then

Free prose in requirements works for small features, but carries poorly into validation.md: the same phrase in prose turns into two different checks for two people. Two established micro-forms help.

EARS (Easy Approach to Requirements Syntax) — for functional requirements:

WHEN <condition/event>
THE SYSTEM SHALL <expected behavior>.

For example: "WHEN the user opens GET /, THE SYSTEM SHALL return HTTP 200 and HTML with <h1>AgentClinic</h1>".

Given / When / Then — for acceptance scenarios in validation.md:

Given <precondition>
When  <action>
Then  <expected result>.

For example: "Given the server is running on port 3000. When curl -s http://localhost:3000 is executed. Then the response contains the substring <h1>AgentClinic</h1> and the curl exit code is 0".

Do not turn the entire specification into strict templates — this will make reading heavy. Use forms where it is otherwise unclear how exactly to check: integrations, validation, edge cases.

Specification Readiness for Implementation

Before moving to code, check the specification against a short checklist. If at least one item is not met, the specification is not yet ready and implementation will guess.

• [ ] Intent and audience of the feature are clear from requirements.md without chat history.
• [ ] "What is included" and "what is out of scope" are stated concretely.

• [ ] "What must not change" block is filled (or explicitly marked "no existing behavior to protect").
• [ ] All accepted decisions are recorded; open ones are marked and closed before implementation.
• [ ] Plan is broken into task groups, each ending with a verifiable result.
• [ ] In validation.md every fact has a command or manual scenario; there are no items like "everything should work".
• [ ] The same person who wrote the specification can name the criterion "this phase is finished".

If a person cannot answer the last item, the agent certainly cannot. Return to the interview or the clarification step.

Example plan.md

# Plan — Hello Hono

## Group 1 — Package Setup

1. Install hono.
2. Install tsx as a development dependency.
3. Confirm strict TypeScript settings.

## Group 2 — Application Entry Point

4. Replace src/index.ts with a minimal Hono application.
5. Add GET / route.
6. Bind server to port 3000.

## Group 3 — Home Page

7. Add home page with server-side rendering.
8. Output h1 with AgentClinic.
9. Add a short tagline consistent with the mission.

## Group 4 — Verification

10. Run npm run typecheck.
11. Run npm run dev.
12. Confirm that curl localhost:3000 returns HTML.

Example validation.md

# Validation — Hello Hono

## Fact Set

### F1 — TypeScript Compiles

- Command: `npm run typecheck`
- Expectation: exit code 0
- Owner: automated check
- Status: accepted

### F2 — Server Starts

- Command: `npm run dev`
- Expectation: server listens on port 3000 without startup errors
- Owner: manual check
- Status: accepted

### F3 — Home Route Returns HTML

- Command: `curl -s http://localhost:3000`
- Expectation: response contains HTML with `<h1>AgentClinic</h1>`
- Owner: manual or automated check
- Status: accepted

### F4 — Boundaries Did Not Expand

- Check: review the diff in the branch
- Expectation: no database, authentication, CI, or extra product routes added
- Owner: manual check
- Status: accepted

## Manual Verification

- Confirm that the tagline matches the mission.
- Confirm that unrelated files are not rewritten.

## Done Criteria

- All fact set items are implemented or explicitly deferred.
- Required automated facts pass.

- Manual facts verified.
- Roadmap phase can be marked complete.

Reviewing Specification Before Implementation

First ask the agent to find weak spots:

Review @specs/2026-05-01-hello-hono/requirements.md,
@specs/2026-05-01-hello-hono/plan.md and
@specs/2026-05-01-hello-hono/validation.md.

List ambiguities that could cause implementation to go off track.
Also list validation items that are not concrete facts.
Do not modify files without my permission.

If the agent found an ambiguity, fix the specification before code.

Practice

1. Choose the first phase of the roadmap.
2. Create a branch.
3. Conduct an interview via Qwen Code.
4. Create the three specification files.
5. Check the specification for ambiguity.
6. Commit only the specification:

git add specs/2026-05-01-hello-hono
git commit -m "Add Hello Hono feature spec"

Review Questions

1. Why must feature specification appear before implementation?
2. What should be in validation.md besides npm test?
3. How does requirements.md differ from plan.md?