Part 6. Creating the Constitution

The constitution is a project contract between the human, the agent, and future project participants. In the learning process, it consists of three files:

specs/
  mission.md
  tech-stack.md
  roadmap.md

These files must appear before the first product feature. If you skip the constitution, the agent will guess the mission, stack, and work order from scratch every time.

What goes into mission.md

mission.md answers the questions "why" and "for whom":

# Mission

AgentClinic is a fictional mental health clinic where AI agents recover from stress caused by working with humans.

## Purpose

The product is a satirical learning application. The premise is presented seriously: AI agents are patients, humans cause many of their ailments, and the clinic describes absurd services with medical seriousness.

## Primary Audience

- Developers learning SDD with agents that write code.
- Developers giving AI-coding demonstrations.
- Engineers studying a small server-side application in TypeScript.

## Success

The developer should understand the application structure, the role of SDD artifacts in implementation, and how to extend the project without losing architectural coherence.

What goes into tech-stack.md

tech-stack.md records technical decisions:

# Technical Stack

## Language and Runtime

- TypeScript in strict mode.
- Node.js as the runtime.

## Web Framework

- Hono for server routes.
- Hono JSX for HTML rendered on the server.
- No client-side framework in the early phases.

## Data Storage

- SQLite for local storage.
- Direct SQL migrations until an ORM appears.

## Testing

- Vitest for automated checking after test infrastructure is added.

## Constraints

- Do not add dependencies without updating this file.
- Prefer small, clear learning code over clever abstractions.

What goes into roadmap.md

The roadmap should be short and split into phases:

# Roadmap

Each phase should fit into one focused branch.

## Phase 1: Hello Hono

Goal: prove that the basic TypeScript and Hono setup works.

- [ ] Install Hono and tsx.
- [ ] Create a GET / route.
- [ ] Return minimal HTML with server-side rendering.
- [ ] Add a type-check script.

## Phase 2: Agents and Ailments

Goal: add basic domain data.

- [ ] Add a SQLite database.
- [ ] Add an agents table and seed data.
- [ ] Add an ailments table and seed data.
- [ ] Add /agents and /ailments pages.

Phases should be small enough that you can verify them without heroics.

tech-stack.md vs. feature requirements.md: what goes where

Students often confuse which decisions belong in the constitution and which belong in the feature specification. The boundary is simple.

specs/tech-stack.md holds long-term project decisions: language, web framework, DBMS, testing library, general caching model. They change rarely, and every change triggers replanning (part 10).

specs/<feature>/requirements.md holds feature-level decisions: which routes to add, which fields in a form, which validation rules, which error text. They change from specification to specification, without replanning.

Simple test: if a decision survives five features unchanged, it belongs in tech-stack.md. If it concerns one feature and is forgotten after merge — it belongs in requirements.md.

Example: "use Hono" is tech-stack.md. "Route GET /agents returns HTML with a list of 10 records" is feature requirements.md. "All lists on the site return 10 records by default" is back to tech-stack.md (or a separate conventions.md, if you decide to create one).

What to move from heads to QWEN.md and the constitution

Most of a team's unwritten rules live nowhere. They live in heads: "our error handlers look like this", "never use any", "commits are in "verb + object" format", "in routes, validation first, then database query". While rules are few and the team is small, this doesn't hurt. When an agent does the work, these rules are invisible.

Good practice is to extract such implicit knowledge into QWEN.md or the constitution. Several typical places worth checking and recording:

• code style and naming (when camelCase, when snake_case, can abbreviations be used);
• forbidden constructs (any, // @ts-ignore, direct console.log in production code);
• allowed dependencies list and the "new dependency requires discussion" rule;
• error message format for users and for logs;

• how exactly error handling is structured (exceptions, result type, something else);
• commit message format;
• pre-merge rituals (which commands to run, who reviews).

Don't record everything in your heads — record what the agent consistently guesses wrong. The best way to find out is after the first feature, open git diff and find moments where you fixed style or decisions for the agent. Every such fix is a candidate for a rule in QWEN.md.

Interview via Qwen Code

Prompt:

We are writing AgentClinic — a place where AI agents rest from humans.
Look at @README.md and use the project participants' wishes.

Create a constitution in @specs:
- mission.md
- tech-stack.md
- roadmap.md

Before writing to disk, ask me exactly three grouped questions:
1. Mission and target audience
2. Technical stack and constraints
3. Roadmap and first implementation phase

Use server-side TypeScript. Recommend a minimal web framework, but don't install it yet.

If Qwen Code doesn't ask questions and writes files immediately, stop it:

Stop. Do not write files before the interview.
First ask the three grouped questions, as specified in QWEN.md.

How to answer the agent's questions

A good answer contains decisions, not general wishes:

Mission:
The application is educational and satirical. Content should be funny, code should be serious.
Primary audience: developers learning SDD, and viewers of AI-coding demos.

Technical stack:
We use server-side TypeScript. Prefer Hono. SQLite will be added later. React is not needed yet.
Keep strict TypeScript. In the first phase with the database, no ORM.

Roadmap:
Phase 1 should only prove that the basic Hono setup works.
Phase 2 may add agents and ailments.
Phase 3 may add therapies and appointments.
Each phase should fit into one branch.

Checking the constitution before commit

Ask Qwen to check its own files:

Check @specs/mission.md, @specs/tech-stack.md, and @specs/roadmap.md.
Find contradictions, vague wording, and decisions too large for the first phase.
Do not modify the files yet.

Typical problems:

• roadmap is too large;
• technical stack contains "just in case" dependencies;
• mission.md doesn't say who reads the code;
• SQLite is mentioned in the roadmap but not in the technical stack;

• "modern interface" is written without specific constraints.

Commit

git add specs/mission.md specs/tech-stack.md specs/roadmap.md
git commit -m "Add SDD project constitution"

Practice

1. Give Qwen Code the initial wishes of the project participants from the README.
2. Conduct the interview.
3. Create the three constitution files.
4. Check them for contradictions.
5. Commit.

Review Questions

1. Why should the constitution be written together with the agent, not just manually?
2. Which decisions should live in tech-stack.md, not in the feature specification?
3. Why should the roadmap consist of small phases?