@activatus/code-standards 3.3.6 → 3.3.8
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/docs/Guides/setup.md +24 -4
- package/docs/Standards/eslint.md +18 -9
- package/docs/Standards/styling.md +4 -4
- package/docs/Standards/tech-stack.md +8 -4
- package/docs/Standards/working-with-agents.md +50 -1
- package/docs/Structure/api-routes.md +35 -0
- package/docs/Structure/folder-structure.md +13 -1
- package/docs/design-system-components.md +2 -0
- package/docs/ontology.md +12 -11
- package/docs/superpowers/plans/2026-11-17-agent-response-format.md +373 -0
- package/docs/superpowers/specs/2026-11-17-agent-response-format-design.md +48 -0
- package/docs/version-history.md +83 -1
- package/package.json +7 -7
- package/scripts/verifyStandards/checkRecordedAnswers.mjs +3 -1
- package/static/templates/AGENTS.md +21 -3
- package/static/templates/docs/development/coding-standards.md +1 -1
package/docs/Guides/setup.md
CHANGED
|
@@ -92,6 +92,7 @@ Tell me the numbers to skip or change, or say "all good".
|
|
|
92
92
|
15. Design System Components: every project builds the standard components with the same props
|
|
93
93
|
16. Imports: no circular imports, import from folders not files
|
|
94
94
|
17. API routes: one folder per route, kebab-case
|
|
95
|
+
17.1. Sitemap: a project with public pages keeps app/sitemap.ts in sync as it routes
|
|
95
96
|
18. Docs: every file in docs/ is a Decision Doc, shown at /docs by the docs site
|
|
96
97
|
19. Removed in version 3: commit messages are the project's own workflow
|
|
97
98
|
20. Removed in version 3: branch names are the project's own workflow
|
|
@@ -125,13 +126,15 @@ Then wait for the answer.
|
|
|
125
126
|
|
|
126
127
|
**Every path after `for` goes in backticks**: a `for` with none fails the check, because it would otherwise cover every file. **Start no other line under "Details" with a number.** The [standards check](#checking-a-project) reads a line that starts with a number as an exception to that standard, and fails on one it cannot read. Use bullet points for anything else. If nothing is different, write "No differences". Copy the file from `static/templates/docs/development/coding-standards.md` if it does not exist.
|
|
127
128
|
|
|
129
|
+
**Biome.** If the project already lints or formats with Biome, ask the person: keep Biome, or move to the standards' ESLint and Prettier? Keeping it is recorded as two exception lines, `6. ESLint — skipped` and `7. Prettier — skipped`, with the reason. A project that keeps Biome runs it by its own setup — the standards ship no Biome config. If the project has no Biome, use ours and ask nothing: do not offer Biome to a project that does not have it.
|
|
130
|
+
|
|
128
131
|
The list has nothing about branches or commit messages. Those are the project's own workflow. Ask the person how they work, and write it in the "Project workflow" section of `AGENTS.md`. See [Project workflow](/docs/Standards/agent-specs#project-workflow).
|
|
129
132
|
|
|
130
133
|
**Then go straight to step 4.** Setup is not finished until the person has answered it.
|
|
131
134
|
|
|
132
135
|
## 4. Working with the agent
|
|
133
136
|
|
|
134
|
-
Do this step every time, straight after step 3. Once the standards are agreed, offer the
|
|
137
|
+
Do this step every time, straight after step 3. Once the standards are agreed, offer the seven [Working with Agents](/docs/Standards/working-with-agents) options. All seven are optional: offer every one, every time, so the person can fill them in quickly and keep going.
|
|
135
138
|
|
|
136
139
|
First the **project links**. Find each one yourself, then ask the person to confirm it or say "None":
|
|
137
140
|
|
|
@@ -165,7 +168,24 @@ Would you like AI to tell you about each coding decision
|
|
|
165
168
|
it makes that the code standards do not cover? Yes or no?
|
|
166
169
|
```
|
|
167
170
|
|
|
168
|
-
**
|
|
171
|
+
Then **ship**. **Print this to the person exactly as it is written**:
|
|
172
|
+
|
|
173
|
+
```text
|
|
174
|
+
When you say "ship", should AI commit the change, push it and
|
|
175
|
+
open a Pull Request that describes what changed and why?
|
|
176
|
+
Yes or no?
|
|
177
|
+
```
|
|
178
|
+
|
|
179
|
+
Then the **response format**. **Print this to the person exactly as it is written**:
|
|
180
|
+
|
|
181
|
+
```text
|
|
182
|
+
Response format (optional). Want the agent to answer with a
|
|
183
|
+
clear structure — a short overview of the problem, results
|
|
184
|
+
in tables, numbered action steps, and what it needs from
|
|
185
|
+
you next? Yes or no?
|
|
186
|
+
```
|
|
187
|
+
|
|
188
|
+
**Record the answers** in the "Project workflow" section of `AGENTS.md`, from the template: each link they confirmed, and the status circles if they said yes. Delete the line for any link they said "None" to, and the status circles section if they said no. If they said yes to asking before committing, write under **Who commits**: "Ask the person before every commit and push, and wait for a clear yes to that specific action. A yes covers one action only." If they said no, write nothing about it: the agent uses its own judgement. If they said yes to being told about decisions, write under **Decisions**: "Tell the person about each coding decision you make that the code standards do not cover, in the summary at the end of the task." If they said no, delete the Decisions line. If they said yes to ship, write under **Ship**: "When the person says 'ship', commit the current change, push it, and open a Pull Request. 'Ship' is the yes for those three steps, for that change only. The Pull Request description says why the change was made, what changed, how it was checked, with the results, and what the reviewer should look at closely, and links the ticket." If they said no, delete the Ship line. If they said yes to the response format, write the **Response format** section from the template's Project workflow into `AGENTS.md`, under Project workflow, after the Status circles section, or at the end of Project workflow if there is none. If they said no, write nothing about it. Write all seven answers in `docs/development/coding-standards.md`, under "Details", on one line, so a later update knows not to ask again: `- Working with the agent: GitHub repo [link or None]; Linear project [project or None]; status circles [yes or no]; ask before every commit and push [yes or no]; told about decisions [yes or no]; ship [yes or no]; response format [yes or no] ([date]).` See [Working with Agents](/docs/Standards/working-with-agents).
|
|
169
189
|
|
|
170
190
|
## 5. Apply the standards
|
|
171
191
|
|
|
@@ -214,7 +234,7 @@ anything that is wrong.
|
|
|
214
234
|
|
|
215
235
|
The project's `AGENTS.md` has the same full version as the installed package, such as 3.2.2. There are no version changes to make.
|
|
216
236
|
|
|
217
|
-
1. **Check `docs/development/coding-standards.md`, under "Details",** for the [step 4](#4-working-with-the-agent) answers: the GitHub repo, the Linear project, the status circles, asking before committing
|
|
237
|
+
1. **Check `docs/development/coding-standards.md`, under "Details",** for the [step 4](#4-working-with-the-agent) answers: the GitHub repo, the Linear project, the status circles, asking before committing, being told about decisions, ship and the response format. Ask the person any that are not recorded, and record them as step 4 says.
|
|
218
238
|
2. **Run the [standards check](#checking-a-project)**, and fix what it finds.
|
|
219
239
|
3. **Tell the person** what you changed, or that the project was already up to date.
|
|
220
240
|
|
|
@@ -270,7 +290,7 @@ It reports, and never changes a file. Each finding gives the standard's number a
|
|
|
270
290
|
| 6 to 10 | `eslint.config.mjs`, `prettier.config.mjs`, `stylelint.config.mjs`, `.editorconfig` and `.envrc` match the templates; `eslint.overrides.mjs`, `.nvmrc` and the format scripts are in place |
|
|
271
291
|
| 12.1 | `lib/constants/` has `index.ts`, `routes.ts` and `strings.ts`, and no `unsortedValues.ts` is left waiting |
|
|
272
292
|
| 13 | `components/` holds only `ui/`, `layout/` and `shared/`, every sub-component sits flat in its root component's `components/` folder, and the homepage is in `app/(homepage)/` |
|
|
273
|
-
| 21 | `docs/development/coding-standards.md` records the
|
|
293
|
+
| 21 | `docs/development/coding-standards.md` records the seven agent answers under "Details", and every numbered line there is a well-formed exception |
|
|
274
294
|
| 11 | `docs/design/design-system.md` has a filled-in Colour palette table |
|
|
275
295
|
| 15 | Every `components/ui/` component is on the Design System Components list, or recorded under "Components for the standards" |
|
|
276
296
|
| 4 | Every file that exports a function or component has a test file beside it |
|
package/docs/Standards/eslint.md
CHANGED
|
@@ -1000,24 +1000,30 @@ Add scripts to `package.json`:
|
|
|
1000
1000
|
|
|
1001
1001
|
## Third-party code is exempt
|
|
1002
1002
|
|
|
1003
|
-
**The standards apply to code we write. They do not apply to packages we pull in.**
|
|
1003
|
+
**The standards apply to code we write. They do not apply to packages we pull in, or to files a tool generates and replaces wholesale.**
|
|
1004
1004
|
|
|
1005
|
-
| Code
|
|
1006
|
-
|
|
|
1007
|
-
| Our own code
|
|
1008
|
-
| `node_modules/`
|
|
1009
|
-
| `vendor/` (third-party code
|
|
1010
|
-
| Build output (`dist/`, `build/`, `.next/`)
|
|
1005
|
+
| Code | Linted? |
|
|
1006
|
+
| ------------------------------------------------------- | ------------------------------------ |
|
|
1007
|
+
| Our own code | ✅ Yes — every rule applies |
|
|
1008
|
+
| `node_modules/` | ❌ No — ESLint ignores it by default |
|
|
1009
|
+
| `vendor/` (third-party or generated code we never edit) | ❌ No — ignored by the config |
|
|
1010
|
+
| Build output (`dist/`, `build/`, `.next/`) | ❌ No — ignored by the config |
|
|
1011
1011
|
|
|
1012
1012
|
Third-party code that is copied into the repository lives in a `vendor/` folder, at any level. The configs ignore `**/vendor/**`, so it is never linted.
|
|
1013
1013
|
|
|
1014
|
-
|
|
1014
|
+
**Generated code lives in `vendor/` too.** A file a tool writes and rewrites is not ours any more than a copied-in package: nobody hand-edits it, and it is replaced wholesale each time it changes. The main case is **database types a CLI regenerates**, such as the Supabase types rewritten after every migration. They live in `vendor/`, at any level, and are never linted.
|
|
1015
|
+
|
|
1016
|
+
- **Do not fix lint errors in third-party or generated code.** It is not ours, and the fix would be lost the next time the tool runs.
|
|
1015
1017
|
- **Do not rename or restructure it** to match our naming or folder rules.
|
|
1016
1018
|
- **Do not add `eslint-disable` comments to it.** Put it in `vendor/` instead.
|
|
1017
1019
|
|
|
1020
|
+
### Code an AI agent writes is ours
|
|
1021
|
+
|
|
1022
|
+
**Who wrote the code does not matter — whether they edit it does.** Code an AI agent generates is our code, and every standard applies to it. The same goes for a script we write to drive a tool, such as a database migration or a seed script: we write it, we read it, we maintain it, so it is linted and held to the standards like any other file.
|
|
1023
|
+
|
|
1018
1024
|
### Copied-in code we maintain is ours
|
|
1019
1025
|
|
|
1020
|
-
`vendor/` is only for
|
|
1026
|
+
`vendor/` is only for code we **do not change** — third-party code copied in, and generated files the tool replaces wholesale.
|
|
1021
1027
|
|
|
1022
1028
|
Code that is copied into the project and then **owned and edited by us** is our code, and every standard applies to it. The main case is **shadcn/ui**: the CLI copies component source into the project, and from then on it is ours. It is converted to our standards and lives in `components/ui/`, never in `vendor/`. See [Adding a shadcn component](/docs/Guides/component-library-workflow#adding-a-shadcn-component).
|
|
1023
1029
|
|
|
@@ -1025,6 +1031,9 @@ Code that is copied into the project and then **owned and edited by us** is our
|
|
|
1025
1031
|
| --------------------------------------------------------- | ------- | ------------------------------------------ |
|
|
1026
1032
|
| A package installed with `pnpm add` | No | No |
|
|
1027
1033
|
| Third-party code copied in and left untouched (`vendor/`) | No | No |
|
|
1034
|
+
| Files a tool regenerates (`vendor/`) | No | No |
|
|
1035
|
+
| Code an AI agent writes | **Yes** | **Yes** |
|
|
1036
|
+
| A script we write to drive a tool | **Yes** | **Yes** |
|
|
1028
1037
|
| shadcn components added with the CLI | **Yes** | **Yes — convert them when they are added** |
|
|
1029
1038
|
| Code generated once and then edited by us | **Yes** | **Yes** |
|
|
1030
1039
|
|
|
@@ -29,7 +29,7 @@ export const Button = () => {
|
|
|
29
29
|
|
|
30
30
|
**Build every layout with flexbox.** Reach for `flex` first, and split the layout into child components so each one styles only itself.
|
|
31
31
|
|
|
32
|
-
**
|
|
32
|
+
**Use CSS grid only when it is genuinely the better tool — and say so when you do.** It is rare: almost everything is a one-dimensional run of boxes, and flexbox aligns it. When a layout is genuinely two-dimensional — a card grid, an aligned table of panels — use grid, and tell the person why grid fits this case. **The [Card Grid](/docs/design-system-components#cta-forms) Design System Component is the standing exception**: when the design asks for a Card Grid, that is the ask, and it uses grid.
|
|
33
33
|
|
|
34
34
|
### ✅ Flex parent, child components
|
|
35
35
|
|
|
@@ -96,13 +96,13 @@ export const PageHeader = () => {
|
|
|
96
96
|
- **The parent positions, the child styles itself.** A parent sets direction, spacing and alignment. Each child component owns its own padding, colour and typography.
|
|
97
97
|
- **Split into child components** rather than growing one long `className` or a deep tree of `div`s. Each child gets [its own folder](/docs/Structure/component-organization#nested-components).
|
|
98
98
|
- **Space with `gap`**, not margins on the children.
|
|
99
|
-
- **Grid only when
|
|
99
|
+
- **Grid only when it is the better tool.** Flexbox covers almost every layout. Use CSS grid when the layout is genuinely two-dimensional — a card grid, an aligned table of panels — and flag the choice: tell the person grid fits this case, or leave a comment saying why.
|
|
100
100
|
|
|
101
101
|
---
|
|
102
102
|
|
|
103
103
|
## ❌ Avoid These
|
|
104
104
|
|
|
105
|
-
- ❌ **CSS grid
|
|
105
|
+
- ❌ **CSS grid for a one-dimensional run of boxes** — flexbox aligns it; grid only when the layout is genuinely two-dimensional, with the choice flagged
|
|
106
106
|
|
|
107
107
|
- ❌ **Hard-coded colours** — hex, `rgb()` or named colours anywhere outside the theme
|
|
108
108
|
- ❌ **Arbitrary colour values** (`bg-[#3b82f6]`) — if the colour is not in the palette, it is not used
|
|
@@ -192,7 +192,7 @@ Tailwind's built-in colours are variables too — `white` is `var(--color-white)
|
|
|
192
192
|
### Tailwind utilities
|
|
193
193
|
|
|
194
194
|
- **Use for**: All component styling
|
|
195
|
-
- **Layout**: Flexbox first; grid
|
|
195
|
+
- **Layout**: Flexbox first; grid when it is genuinely the better tool, flagged to the person
|
|
196
196
|
- **Colours**: Global palette only — Tailwind colours and project colours from `@theme` — never arbitrary values
|
|
197
197
|
- **Long class lists**: Extract a component, not a CSS class
|
|
198
198
|
- **Conditional classes**: Use `clsx`
|
|
@@ -11,13 +11,17 @@ Standard technology choices for Activatus projects.
|
|
|
11
11
|
## 📋 Standard Stack
|
|
12
12
|
|
|
13
13
|
- **Framework**: Next.js 16 (App Router)
|
|
14
|
-
- **Language**: TypeScript 7
|
|
14
|
+
- **Language**: TypeScript, latest stable — 7 at the time of writing
|
|
15
15
|
- **Package Manager**: pnpm (monorepo: workspaces)
|
|
16
16
|
- **Styling**: Tailwind CSS
|
|
17
17
|
- **Node Version**: `^22.11 || ^24 || >=26`
|
|
18
18
|
- **Build Tool**: Turbopack (Next.js built-in)
|
|
19
19
|
|
|
20
|
-
### TypeScript
|
|
20
|
+
### The latest TypeScript
|
|
21
|
+
|
|
22
|
+
**A project uses the latest stable TypeScript.** The standards do not pin a
|
|
23
|
+
major: when a new one ships and the tooling around it has caught up, a project
|
|
24
|
+
moves up. The notes below describe 7, the latest at the time of writing.
|
|
21
25
|
|
|
22
26
|
TypeScript 7 is the compiler rewritten in Go. It is a drop-in replacement for
|
|
23
27
|
the JavaScript implementation for compiling and type-checking, but two things
|
|
@@ -134,7 +138,7 @@ See `package.json` for specific version requirements. Key dependencies:
|
|
|
134
138
|
|
|
135
139
|
## 🔧 Development Tools
|
|
136
140
|
|
|
137
|
-
- **Linting**: ESLint
|
|
141
|
+
- **Linting**: ESLint 10.4 or later — the standard config needs it
|
|
138
142
|
- **Formatting**: Prettier
|
|
139
143
|
- **Monorepo**: Turborepo
|
|
140
144
|
- **Documentation**: Docusaurus
|
|
@@ -152,6 +156,6 @@ See `package.json` for specific version requirements. Key dependencies:
|
|
|
152
156
|
|
|
153
157
|
### TypeScript
|
|
154
158
|
|
|
155
|
-
- **Version**:
|
|
159
|
+
- **Version**: the latest stable — 7 at the time of writing, run side by side with the TypeScript 6 API for linting until `typescript-eslint` supports 7 (see the [note on the ESLint page](/docs/Standards/eslint#installation))
|
|
156
160
|
- **Strict Mode**: Enabled
|
|
157
161
|
- **Target**: ES2022+
|
|
@@ -5,7 +5,7 @@ sidebar_label: "Working with Agents"
|
|
|
5
5
|
|
|
6
6
|
# Working with Agents
|
|
7
7
|
|
|
8
|
-
> How an AI agent links a project's work, reports on it, asks before committing
|
|
8
|
+
> How an AI agent links a project's work, reports on it, asks before committing, tells the person about its decisions, ships a change and answers in a readable shape. The GitHub repo, the Linear project, the status circles, asking before every commit and push, being told about decisions, ship and the response format are all optional. [Setup](/docs/Guides/setup#4-working-with-the-agent) offers all seven every time, so they take a moment to fill in, and a project can leave out any of them. They work the same with Claude Code, ChatGPT, Codex or any agent that reads `AGENTS.md`.
|
|
9
9
|
|
|
10
10
|
Whatever the project chooses is written into the **Project workflow** section of its `AGENTS.md`, from the [template](/docs/templates#agents), so every agent in the project follows it.
|
|
11
11
|
|
|
@@ -49,3 +49,52 @@ Optional. Setup asks: "Would you like AI to ask you before every commit and push
|
|
|
49
49
|
## Told about decisions
|
|
50
50
|
|
|
51
51
|
Optional. Setup asks: "Would you like AI to tell you about each coding decision it makes that the code standards do not cover?" The code standards are the base, and the agent builds freely from them, so it makes many calls of its own. A person who reads the code may want to hear each one; a person who does not may not care. A yes is written under **Decisions** in Project workflow: the agent lists each such decision in its summary at the end of the task. A no means nothing is written, and the agent decides without reporting.
|
|
52
|
+
|
|
53
|
+
## Ship
|
|
54
|
+
|
|
55
|
+
Optional. Setup asks: "When you say 'ship', should AI commit the change, push it and open a Pull Request that describes what changed and why?" It is a project workflow choice, not a code standard. A yes is written under **Ship** in Project workflow. When the person says "ship", the agent:
|
|
56
|
+
|
|
57
|
+
1. **Commits the current change**, with the project's commit message format.
|
|
58
|
+
2. **Pushes it** to its branch.
|
|
59
|
+
3. **Opens a Pull Request** whose description a reviewer can work from without asking:
|
|
60
|
+
- **Why:** the problem or ticket the change answers.
|
|
61
|
+
- **What changed:** each change, by area or file, in plain words.
|
|
62
|
+
- **How it was checked:** the commands run and their results, and anything tested by hand.
|
|
63
|
+
- **Look closely at:** anything risky, unfinished or worth a second opinion. "Nothing" if there is nothing.
|
|
64
|
+
- **The ticket**, linked, when there is one.
|
|
65
|
+
|
|
66
|
+
**"Ship" is the yes for those three steps, for the change in hand only.** It never carries over to the next change. A project that asks before every commit and push still does: "ship" is that yes. A no means the Ship line is deleted, and the person asks for each step themselves.
|
|
67
|
+
|
|
68
|
+
## Response format
|
|
69
|
+
|
|
70
|
+
Optional. Setup asks: "Want the agent to answer with a clear structure — a short overview of the problem, results in tables, numbered action steps, and what it needs from you next?" A yes is written as the **Response format** section in Project workflow. Then every substantive reply — anything with findings, results, options or a plan — follows the same shape, and a plain yes or no stays plain:
|
|
71
|
+
|
|
72
|
+
1. **The status line first**, when status circles are on: where the work is up to.
|
|
73
|
+
2. **An overview** — what happened or what was found, in a line or two.
|
|
74
|
+
3. **Each problem plainly** — what is wrong and why it matters.
|
|
75
|
+
4. **Results in tables** — one row per item.
|
|
76
|
+
5. **"How to fix it" as numbered steps.**
|
|
77
|
+
6. **The next action as a question.**
|
|
78
|
+
|
|
79
|
+
Emojis are welcome where they make the reply quicker to read — a ✅/❌ per row in a results table, 🎉 when something lands. The seven status circles appear only on a status line, never as decoration: a ✅/❌ tick in a results table marks pass and fail, not the circle's status meaning.
|
|
80
|
+
|
|
81
|
+
```md title="A reply in the response format"
|
|
82
|
+
🟣 Response format: template, setup and docs done; the checker is left.
|
|
83
|
+
|
|
84
|
+
I added the response format as a setup choice, like status circles. One problem: the recorded-answers check only knows six answers, so `standards:check` would pass a project that said yes without the answer recorded.
|
|
85
|
+
|
|
86
|
+
| File | Result |
|
|
87
|
+
| --- | --- |
|
|
88
|
+
| AGENTS.md template | ✅ Response format section added |
|
|
89
|
+
| Setup step 4 | ✅ Seventh offer added |
|
|
90
|
+
| working-with-agents.md | ✅ This section |
|
|
91
|
+
| checkRecordedAnswers.mjs | ❌ Missing the seventh answer |
|
|
92
|
+
|
|
93
|
+
How to fix it:
|
|
94
|
+
|
|
95
|
+
1. Add the response format to the checker's list of answers.
|
|
96
|
+
2. Update the checker's test to expect seven answers.
|
|
97
|
+
3. Run the tests and `pnpm standards:check`.
|
|
98
|
+
|
|
99
|
+
Want me to finish the checker now?
|
|
100
|
+
```
|
|
@@ -100,6 +100,31 @@ app/api/
|
|
|
100
100
|
|
|
101
101
|
---
|
|
102
102
|
|
|
103
|
+
## 🚪 Route handlers outside `app/api/`
|
|
104
|
+
|
|
105
|
+
**A `route.ts` anywhere in `app/` is a route handler**, not just under `app/api/`. Next.js gives every `route.ts` the URL its folder path describes, so a handler lives outside `app/api/` when its URL is not an API endpoint but a page-shaped stop on the way somewhere else. The main case is an **auth callback**: a URL the identity provider sends the browser back to, which reads the result and redirects on, like `app/sign-in/confirm/route.ts` serving `/sign-in/confirm`.
|
|
106
|
+
|
|
107
|
+
**The same rules apply outside `app/api/`**: kebab-case folders, the file is `route.ts`, and every other standard holds. A handler that returns JSON belongs under `app/api/`; a handler that redirects or rewrites belongs at the URL the outside world already expects, which is usually not under `app/api/`.
|
|
108
|
+
|
|
109
|
+
### Named exports
|
|
110
|
+
|
|
111
|
+
**Handlers are exported as named functions, never a default export.** Next.js wires the HTTP method by the export's name:
|
|
112
|
+
|
|
113
|
+
```typescript
|
|
114
|
+
// ✅ Correct — named export per HTTP method
|
|
115
|
+
export async function GET(request: Request) { … }
|
|
116
|
+
export async function POST(request: Request) { … }
|
|
117
|
+
|
|
118
|
+
// ❌ Incorrect — a default export does nothing
|
|
119
|
+
export default async function handler(request: Request) { … }
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
### Where a handler's helpers go
|
|
123
|
+
|
|
124
|
+
Functions written for one route handler follow the [utils ladder](/docs/Structure/folder-structure#-utils): a helper only this handler uses goes in that section's `utils/` folder, and a helper used across the app goes in the global `utils/`. Code that talks to an outside service goes in `lib/integrations/`, never in the handler file itself.
|
|
125
|
+
|
|
126
|
+
---
|
|
127
|
+
|
|
103
128
|
## 🔒 Security Best Practices
|
|
104
129
|
|
|
105
130
|
- **Validate input** - Use Zod schemas
|
|
@@ -111,6 +136,16 @@ app/api/
|
|
|
111
136
|
|
|
112
137
|
---
|
|
113
138
|
|
|
139
|
+
## 🗺️ The sitemap travels with the routes {#sitemap}
|
|
140
|
+
|
|
141
|
+
**A project with public pages keeps `app/sitemap.ts` in sync as it routes** — never as a cleanup at the end. When a public page is added, its URL goes into the sitemap in the same change; when one is renamed or removed, its line changes or goes in the same change. The sitemap is how search engines learn the pages exist, so a page that is routed but not listed is a page nobody is told about.
|
|
142
|
+
|
|
143
|
+
- **Build it with the routing, not after it.** Adding the page and updating `app/sitemap.ts` is one change, not two.
|
|
144
|
+
- **Public pages only.** Pages behind sign-in, API routes and route handlers that redirect are not listed.
|
|
145
|
+
- **A project with no public pages has no sitemap**, and that is correct — build one the day the first public page arrives.
|
|
146
|
+
|
|
147
|
+
---
|
|
148
|
+
|
|
114
149
|
## 📚 Related Documentation
|
|
115
150
|
|
|
116
151
|
- [Folder Structure](/docs/Structure/folder-structure) - Overall project structure
|
|
@@ -87,7 +87,7 @@ project-root/
|
|
|
87
87
|
│ │ ├── formatDate.test.ts
|
|
88
88
|
│ │ └── index.ts
|
|
89
89
|
│ └── index.ts # Exports every function
|
|
90
|
-
├── hooks/ # Custom React hooks
|
|
90
|
+
├── hooks/ # Custom React hooks used across the app
|
|
91
91
|
├── services/ # Business logic: what the app does
|
|
92
92
|
├── stores/ # State management stores
|
|
93
93
|
├── styles/ # Global styles
|
|
@@ -296,6 +296,18 @@ Add the export to `utils/index.ts` whenever you add a function.
|
|
|
296
296
|
- **Import from the `utils` folder**, never from the files inside it.
|
|
297
297
|
- **Keep UI files clean.** If a function could be written in another file, it does not belong in the component file. See [Writing a component](/docs/Structure/component-organization#-writing-a-component).
|
|
298
298
|
|
|
299
|
+
### Hooks live the same way {#hooks-live-the-same-way}
|
|
300
|
+
|
|
301
|
+
**A custom hook follows the same ladder as a util.** It starts in the component's `hooks/`, moves to the section's `hooks/` when another component in the section needs it, and moves to the global `hooks/` folder at the project root when anything outside the section needs it:
|
|
302
|
+
|
|
303
|
+
| Used by | Location | Example |
|
|
304
|
+
| ------------- | ------------------------------------------------ | ---------------------------------------------------------------- |
|
|
305
|
+
| The whole app | Global `hooks/` folder at the project root | `hooks/useMediaQuery/` |
|
|
306
|
+
| One section | A `hooks/` folder in that section's route group | `app/(billing)/hooks/useInvoiceTotals/` |
|
|
307
|
+
| One component | A `hooks/` folder inside that component's folder | `app/(billing)/components/invoiceTable/hooks/useSortedInvoices/` |
|
|
308
|
+
|
|
309
|
+
The folder shape is the same too: **one folder per hook**, named after it (`useUserData/useUserData.ts`), with the hook, its test file and an `index.ts`, and an `index.ts` in the `hooks/` folder that exports them all. A hook used by more than one component, or that wraps stateful logic a component should not hold itself, goes in a `hooks/` folder from the start, never inside the component file.
|
|
310
|
+
|
|
299
311
|
---
|
|
300
312
|
|
|
301
313
|
## 🔤 Constants: `r`, `s` and shared values {#constants}
|
|
@@ -100,6 +100,8 @@ This applies to everyone building components, **including AI agents**.
|
|
|
100
100
|
| 54 | **Button** | primary, secondary, ghost | link<br />size (small/medium/large)<br />icon<br />iconPosition<br />fullWidth (boolean) |
|
|
101
101
|
| 55 | **Cookie Banner** | — | text (richtext)<br />acceptLabel<br />rejectLabel<br />policyLink |
|
|
102
102
|
|
|
103
|
+
**There is no Select component.** A field where the person picks one option from a list is an **Input with `type: select`** (or `type: dropdown` or `type: auto-select`), with the choices passed through its `options` prop. Build it as an Input, never as a standalone component — a separate Select would duplicate Input's name, label, help text, validation and error states.
|
|
104
|
+
|
|
103
105
|
## Utility (low-level primitives)
|
|
104
106
|
|
|
105
107
|
| # | Component | Variants | Key props |
|
package/docs/ontology.md
CHANGED
|
@@ -60,17 +60,18 @@ The words stay the same everywhere. Only the casing changes, to match where the
|
|
|
60
60
|
|
|
61
61
|
### People and agents
|
|
62
62
|
|
|
63
|
-
| Term | Means
|
|
64
|
-
| --------------- |
|
|
65
|
-
| `human` | A person, as opposed to an agent
|
|
66
|
-
| `developer` | A human who writes code
|
|
67
|
-
| `agent` | An AI that writes or checks code, such as Claude Code. It follows every standard a developer does
|
|
68
|
-
| `agent_spec` | A project's `AGENTS.md` file: the first thing an agent reads, setting out how to work on that project. See [Agent Specs](/docs/Standards/agent-specs)
|
|
69
|
-
| `agent_harness` | Everything around an agent that runs it: the program it runs in (such as Claude Code), its instructions, the tools and permissions it has, and the rules it follows. The ontology says what words mean; the harness says how an agent behaves
|
|
70
|
-
| `context` | Everything an agent is given to read for its task: the agent spec, the docs and the code it is working on
|
|
71
|
-
| `tool` | One action an agent is allowed to take, such as editing a file or running the tests. Tools come from the agent harness or an MCP server
|
|
72
|
-
| `model` | The AI model an agent thinks with
|
|
73
|
-
| `
|
|
63
|
+
| Term | Means |
|
|
64
|
+
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
65
|
+
| `human` | A person, as opposed to an agent |
|
|
66
|
+
| `developer` | A human who writes code |
|
|
67
|
+
| `agent` | An AI that writes or checks code, such as Claude Code. It follows every standard a developer does |
|
|
68
|
+
| `agent_spec` | A project's `AGENTS.md` file: the first thing an agent reads, setting out how to work on that project. See [Agent Specs](/docs/Standards/agent-specs) |
|
|
69
|
+
| `agent_harness` | Everything around an agent that runs it: the program it runs in (such as Claude Code), its instructions, the tools and permissions it has, and the rules it follows. The ontology says what words mean; the harness says how an agent behaves |
|
|
70
|
+
| `context` | Everything an agent is given to read for its task: the agent spec, the docs and the code it is working on |
|
|
71
|
+
| `tool` | One action an agent is allowed to take, such as editing a file or running the tests. Tools come from the agent harness or an MCP server |
|
|
72
|
+
| `model` | The AI model an agent thinks with |
|
|
73
|
+
| `ship` | To commit the current change, push it, and open a Pull Request that says why the change was made, what changed, how it was checked and what to look at closely. Only in a project that said yes to it during setup, and only for that one change. See [Ship](/docs/Standards/working-with-agents#ship) |
|
|
74
|
+
| `mcp` | Model Context Protocol: the standard way to connect an agent to outside tools and data, such as Linear or GitHub. An MCP server offers tools, and the agent calls them |
|
|
74
75
|
|
|
75
76
|
### Code
|
|
76
77
|
|
|
@@ -0,0 +1,373 @@
|
|
|
1
|
+
# Agent Response Format Implementation Plan
|
|
2
|
+
|
|
3
|
+
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
|
4
|
+
|
|
5
|
+
**Goal:** Add an optional "Response format" setup choice so every dev agent answers with a structured reply — status line first, overview, problems plainly, tables, numbered steps, closing question.
|
|
6
|
+
|
|
7
|
+
**Architecture:** A new `### Response format` subsection in the AGENTS.md template's Project workflow (outside the managed markers), offered by setup step 4 as the seventh question, recorded like the other six answers, and validated by the recorded-answers checker. No version bump: the repo stays on 3.3.7.
|
|
8
|
+
|
|
9
|
+
**Tech Stack:** Markdown docs and templates, plain Node ESM scripts, `node --test`, Prettier.
|
|
10
|
+
|
|
11
|
+
**Standing rule for every commit step:** ask Tom "Ready to commit and push — want me to?" and wait for a clear yes to that specific action. Never commit without it.
|
|
12
|
+
|
|
13
|
+
**Spec:** `docs/superpowers/specs/2026-11-17-agent-response-format-design.md`
|
|
14
|
+
|
|
15
|
+
---
|
|
16
|
+
|
|
17
|
+
### Task 1: The `### Response format` section in the AGENTS.md template
|
|
18
|
+
|
|
19
|
+
**Files:**
|
|
20
|
+
|
|
21
|
+
- Modify: `static/templates/AGENTS.md` (insert after the Status circles section, which ends at line 76 with the "- Only what the person needs to act on..." list; before `## Environment variables` at line 78)
|
|
22
|
+
|
|
23
|
+
- [ ] **Step 1: Insert the section**
|
|
24
|
+
|
|
25
|
+
Between the end of `### Status circles` (after the line `- Only what the person needs to act on. Leave out what they already know.`) and `## Environment variables`, insert:
|
|
26
|
+
|
|
27
|
+
```markdown
|
|
28
|
+
### Response format
|
|
29
|
+
|
|
30
|
+
[Only if the person chose the response format during setup. Otherwise delete this section.]
|
|
31
|
+
|
|
32
|
+
Answer every substantive reply — anything with findings, results, options or a plan — in this shape. A plain acknowledgement of a yes or no stays plain.
|
|
33
|
+
|
|
34
|
+
1. **The status line first**, when status circles are on: where the work is up to, before anything else, in the format the Status circles section defines.
|
|
35
|
+
2. **An overview** — one or two lines: what happened or what was found, before any detail.
|
|
36
|
+
3. **Each problem named plainly** — what is wrong and why it matters, one per item, not buried in prose.
|
|
37
|
+
4. **Results and comparisons in tables** — check results, before and after, options — one row per item.
|
|
38
|
+
5. **"How to fix it" as numbered steps**, each concrete enough to action on its own.
|
|
39
|
+
6. **The next action as a question**, so the person only has to answer it.
|
|
40
|
+
|
|
41
|
+
**Emojis where they help, not everywhere.** Use them when they make the reply quicker to read than a slab of text — ✅/❌ per row in a results table, 🎉 when something lands, 🔧 for work in progress. The whole range is welcome; not every reply needs them. **Traffic-light circles are the exception:** the seven status circles (✅ 🟢 🟣 🟡 🟠 🔴 ⚪) carry one meaning each from the Status circles section and appear only on a status line. For flavour use other symbols. A ✅/❌ tick in a results table marks pass and fail, which is fine.
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
- [ ] **Step 2: Check formatting and the agent-files check**
|
|
45
|
+
|
|
46
|
+
Run: `pnpm format:check` and `node --test scripts/verifyStandards/checkAgentFiles.test.mjs`
|
|
47
|
+
Expected: both pass. The new section sits outside the `<!-- code-standards:start/end -->` markers, so `checkAgentFiles` must not report a template difference.
|
|
48
|
+
|
|
49
|
+
- [ ] **Step 3: Commit** (ask Tom first — see the standing rule)
|
|
50
|
+
|
|
51
|
+
```bash
|
|
52
|
+
git add static/templates/AGENTS.md
|
|
53
|
+
git commit -m "feat: response format section in the AGENTS.md template"
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
---
|
|
57
|
+
|
|
58
|
+
### Task 2: The seventh slot in the template's answers line
|
|
59
|
+
|
|
60
|
+
**Files:**
|
|
61
|
+
|
|
62
|
+
- Modify: `static/templates/docs/development/coding-standards.md:19`
|
|
63
|
+
|
|
64
|
+
- [ ] **Step 1: Extend the unfilled answers line**
|
|
65
|
+
|
|
66
|
+
Change line 19 from:
|
|
67
|
+
|
|
68
|
+
```markdown
|
|
69
|
+
- Working with the agent: GitHub repo [link or None]; Linear project [project or None]; status circles [yes or no]; ask before every commit and push [yes or no]; told about decisions [yes or no]; ship [yes or no] ([YYYY-MM-DD]).
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
to:
|
|
73
|
+
|
|
74
|
+
```markdown
|
|
75
|
+
- Working with the agent: GitHub repo [link or None]; Linear project [project or None]; status circles [yes or no]; ask before every commit and push [yes or no]; told about decisions [yes or no]; ship [yes or no]; response format [yes or no] ([YYYY-MM-DD]).
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
- [ ] **Step 2: Check formatting**
|
|
79
|
+
|
|
80
|
+
Run: `pnpm format:check`
|
|
81
|
+
Expected: passes
|
|
82
|
+
|
|
83
|
+
- [ ] **Step 3: Commit** (ask Tom first)
|
|
84
|
+
|
|
85
|
+
```bash
|
|
86
|
+
git add static/templates/docs/development/coding-standards.md
|
|
87
|
+
git commit -m "feat: response format slot in the template's recorded answers"
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
---
|
|
91
|
+
|
|
92
|
+
### Task 3: The checker learns the seventh answer (TDD)
|
|
93
|
+
|
|
94
|
+
**Files:**
|
|
95
|
+
|
|
96
|
+
- Modify: `scripts/verifyStandards/checkRecordedAnswers.test.mjs`
|
|
97
|
+
- Modify: `scripts/verifyStandards/checkRecordedAnswers.mjs`
|
|
98
|
+
|
|
99
|
+
- [ ] **Step 1: Update the failing test**
|
|
100
|
+
|
|
101
|
+
In `checkRecordedAnswers.test.mjs`, make these changes:
|
|
102
|
+
|
|
103
|
+
a. The `ALL_ANSWERS` constant becomes (the recorded line gains `; response format yes`):
|
|
104
|
+
|
|
105
|
+
```js
|
|
106
|
+
const ALL_ANSWERS = `## Details
|
|
107
|
+
|
|
108
|
+
- Working with the agent: GitHub repo https://github.com/example/site; Linear project None; status circles yes; ask before every commit and push yes; told about decisions no; ship yes; response format yes (2026-10-23).
|
|
109
|
+
|
|
110
|
+
## Related
|
|
111
|
+
`;
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
b. The test named `"passes all six answers and a filled-in palette"` is renamed to `"passes all seven answers and a filled-in palette"` (assert stays `[]`).
|
|
115
|
+
|
|
116
|
+
c. The template's unfilled answers line in `"flags the template's unfilled answers line"` gains the seventh slot, and the expected count goes from 6 to 7:
|
|
117
|
+
|
|
118
|
+
```js
|
|
119
|
+
const findings = check({
|
|
120
|
+
"docs/development/coding-standards.md":
|
|
121
|
+
"## Details\n\n- Working with the agent: GitHub repo [link or None]; Linear project [project or None]; status circles [yes or no]; ask before every commit and push [yes or no]; told about decisions [yes or no]; ship [yes or no]; response format [yes or no] ([YYYY-MM-DD]).\n",
|
|
122
|
+
"docs/design/design-system.md": PALETTE,
|
|
123
|
+
});
|
|
124
|
+
assert.equal(findings.length, 7);
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
d. The test named `"flags each missing agent answer"` expects one more finding (GitHub recorded, the other six missing), and the first finding's message stays the Linear project:
|
|
128
|
+
|
|
129
|
+
```js
|
|
130
|
+
assert.equal(findings.length, 6);
|
|
131
|
+
assert.match(findings[0].message, /the Linear project/);
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
e. Add a new test after `"flags a project set up before ship was asked"`:
|
|
135
|
+
|
|
136
|
+
```js
|
|
137
|
+
it("flags a project set up before the response format was asked", () => {
|
|
138
|
+
const findings = check({
|
|
139
|
+
"docs/development/coding-standards.md": ALL_ANSWERS.replace(
|
|
140
|
+
"; response format yes",
|
|
141
|
+
"",
|
|
142
|
+
),
|
|
143
|
+
"docs/design/design-system.md": PALETTE,
|
|
144
|
+
});
|
|
145
|
+
assert.equal(findings.length, 1);
|
|
146
|
+
assert.match(findings[0].message, /does not record the response format/);
|
|
147
|
+
});
|
|
148
|
+
```
|
|
149
|
+
|
|
150
|
+
- [ ] **Step 2: Run the test to verify it fails**
|
|
151
|
+
|
|
152
|
+
Run: `node --test scripts/verifyStandards/checkRecordedAnswers.test.mjs`
|
|
153
|
+
Expected: FAIL — the new test fails because the checker does not know the response format yet
|
|
154
|
+
|
|
155
|
+
- [ ] **Step 3: Implement the seventh answer**
|
|
156
|
+
|
|
157
|
+
In `checkRecordedAnswers.mjs`, change the header comment from "the six agent answers" to "the seven agent answers", and add the seventh entry to `AGENT_ANSWERS` after the ship entry:
|
|
158
|
+
|
|
159
|
+
```js
|
|
160
|
+
// What setup asks the person and writes down: the seven agent answers
|
|
161
|
+
// (standard 21) and the colour palette (standard 11).
|
|
162
|
+
```
|
|
163
|
+
|
|
164
|
+
```js
|
|
165
|
+
{ name: "ship", pattern: /\bship\b/i },
|
|
166
|
+
{ name: "the response format", pattern: /response format/i },
|
|
167
|
+
];
|
|
168
|
+
```
|
|
169
|
+
|
|
170
|
+
- [ ] **Step 4: Run the test to verify it passes**
|
|
171
|
+
|
|
172
|
+
Run: `node --test scripts/verifyStandards/checkRecordedAnswers.test.mjs`
|
|
173
|
+
Expected: PASS, all tests green
|
|
174
|
+
|
|
175
|
+
- [ ] **Step 5: Run the whole test suite**
|
|
176
|
+
|
|
177
|
+
Run: `pnpm test`
|
|
178
|
+
Expected: passes
|
|
179
|
+
|
|
180
|
+
- [ ] **Step 6: Commit** (ask Tom first)
|
|
181
|
+
|
|
182
|
+
```bash
|
|
183
|
+
git add scripts/verifyStandards/checkRecordedAnswers.mjs scripts/verifyStandards/checkRecordedAnswers.test.mjs
|
|
184
|
+
git commit -m "feat: recorded-answers check learns the response format"
|
|
185
|
+
```
|
|
186
|
+
|
|
187
|
+
---
|
|
188
|
+
|
|
189
|
+
### Task 4: Setup offers the seventh question
|
|
190
|
+
|
|
191
|
+
**Files:**
|
|
192
|
+
|
|
193
|
+
- Modify: `docs/Guides/setup.md` (lines 134, 168–176, 225, 281)
|
|
194
|
+
|
|
195
|
+
- [ ] **Step 1: Update the section count at line 134**
|
|
196
|
+
|
|
197
|
+
Change:
|
|
198
|
+
|
|
199
|
+
```markdown
|
|
200
|
+
Do this step every time, straight after step 3. Once the standards are agreed, offer the six [Working with Agents](/docs/Standards/working-with-agents) options. All six are optional: offer every one, every time, so the person can fill them in quickly and keep going.
|
|
201
|
+
```
|
|
202
|
+
|
|
203
|
+
to:
|
|
204
|
+
|
|
205
|
+
```markdown
|
|
206
|
+
Do this step every time, straight after step 3. Once the standards are agreed, offer the seven [Working with Agents](/docs/Standards/working-with-agents) options. All seven are optional: offer every one, every time, so the person can fill them in quickly and keep going.
|
|
207
|
+
```
|
|
208
|
+
|
|
209
|
+
- [ ] **Step 2: Add the printed offer after the ship offer**
|
|
210
|
+
|
|
211
|
+
After the ship offer's code block (which ends with `Yes or no?` and the closing fence, before the "Record the answers" paragraph), insert:
|
|
212
|
+
|
|
213
|
+
````markdown
|
|
214
|
+
Then the **response format**. **Print this to the person exactly as it is written**:
|
|
215
|
+
|
|
216
|
+
```text
|
|
217
|
+
Response format (optional). Want the agent to answer with a
|
|
218
|
+
clear structure — a short overview of the problem, results
|
|
219
|
+
in tables, numbered action steps, and what it needs from
|
|
220
|
+
you next? Yes or no?
|
|
221
|
+
```
|
|
222
|
+
````
|
|
223
|
+
|
|
224
|
+
- [ ] **Step 3: Extend the "Record the answers" paragraph**
|
|
225
|
+
|
|
226
|
+
Two changes in the paragraph at line 176:
|
|
227
|
+
|
|
228
|
+
a. After the sentence about ship ("If they said no, delete the Ship line."), insert:
|
|
229
|
+
|
|
230
|
+
```markdown
|
|
231
|
+
If they said yes to the response format, write the **Response format** section from the template's Project workflow into `AGENTS.md`, under Project workflow, after the Status circles section. If they said no, write nothing about it.
|
|
232
|
+
```
|
|
233
|
+
|
|
234
|
+
b. Change `Write all six answers` to `Write all seven answers`, and extend the recorded line:
|
|
235
|
+
|
|
236
|
+
```markdown
|
|
237
|
+
`- Working with the agent: GitHub repo [link or None]; Linear project [project or None]; status circles [yes or no]; ask before every commit and push [yes or no]; told about decisions [yes or no]; ship [yes or no]; response format [yes or no] ([date]).`
|
|
238
|
+
```
|
|
239
|
+
|
|
240
|
+
- [ ] **Step 4: Update "Already on this version" step 1 (line 225)**
|
|
241
|
+
|
|
242
|
+
Change the answer list to include the new one:
|
|
243
|
+
|
|
244
|
+
```markdown
|
|
245
|
+
1. **Check `docs/development/coding-standards.md`, under "Details",** for the [step 4](#4-working-with-the-agent) answers: the GitHub repo, the Linear project, the status circles, asking before committing, being told about decisions, ship and the response format. Ask the person any that are not recorded, and record them as step 4 says.
|
|
246
|
+
```
|
|
247
|
+
|
|
248
|
+
- [ ] **Step 5: Update the check table row (line 281)**
|
|
249
|
+
|
|
250
|
+
Change `records the six agent answers` to `records the seven agent answers`.
|
|
251
|
+
|
|
252
|
+
- [ ] **Step 6: Check formatting**
|
|
253
|
+
|
|
254
|
+
Run: `pnpm format:check`
|
|
255
|
+
Expected: passes
|
|
256
|
+
|
|
257
|
+
- [ ] **Step 7: Commit** (ask Tom first)
|
|
258
|
+
|
|
259
|
+
```bash
|
|
260
|
+
git add docs/Guides/setup.md
|
|
261
|
+
git commit -m "docs: setup offers the response format as the seventh question"
|
|
262
|
+
```
|
|
263
|
+
|
|
264
|
+
---
|
|
265
|
+
|
|
266
|
+
### Task 5: The Working with Agents docs section
|
|
267
|
+
|
|
268
|
+
**Files:**
|
|
269
|
+
|
|
270
|
+
- Modify: `docs/Standards/working-with-agents.md` (intro at line 8, new section after Ship)
|
|
271
|
+
|
|
272
|
+
- [ ] **Step 1: Update the intro**
|
|
273
|
+
|
|
274
|
+
Change line 8 from:
|
|
275
|
+
|
|
276
|
+
```markdown
|
|
277
|
+
> How an AI agent links a project's work, reports on it, asks before committing, tells the person about its decisions and ships a change. The GitHub repo, the Linear project, the status circles, asking before every commit and push, being told about decisions and ship are all optional. [Setup](/docs/Guides/setup#4-working-with-the-agent) offers all six every time, so they take a moment to fill in, and a project can leave out any of them. They work the same with Claude Code, ChatGPT, Codex or any agent that reads `AGENTS.md`.
|
|
278
|
+
```
|
|
279
|
+
|
|
280
|
+
to:
|
|
281
|
+
|
|
282
|
+
```markdown
|
|
283
|
+
> How an AI agent links a project's work, reports on it, asks before committing, tells the person about its decisions, ships a change and answers in a readable shape. The GitHub repo, the Linear project, the status circles, asking before every commit and push, being told about decisions, ship and the response format are all optional. [Setup](/docs/Guides/setup#4-working-with-the-agent) offers all seven every time, so they take a moment to fill in, and a project can leave out any of them. They work the same with Claude Code, ChatGPT, Codex or any agent that reads `AGENTS.md`.
|
|
284
|
+
```
|
|
285
|
+
|
|
286
|
+
- [ ] **Step 2: Add the Response format section at the end of the file**
|
|
287
|
+
|
|
288
|
+
After the Ship section (end of file), append:
|
|
289
|
+
|
|
290
|
+
````markdown
|
|
291
|
+
## Response format
|
|
292
|
+
|
|
293
|
+
Optional. Setup asks: "Would you like the agent to answer with a clear structure — a short overview of the problem, results in tables, numbered action steps, and what it needs from you next?" A yes is written as the **Response format** section in Project workflow. Then every substantive reply — anything with findings, results, options or a plan — follows the same shape, and a plain acknowledgement of a yes or no stays plain:
|
|
294
|
+
|
|
295
|
+
1. **The status line first**, when status circles are on: where the work is up to.
|
|
296
|
+
2. **An overview** — what happened or what was found, in a line or two.
|
|
297
|
+
3. **Each problem plainly** — what is wrong and why it matters.
|
|
298
|
+
4. **Results in tables** — one row per item.
|
|
299
|
+
5. **"How to fix it" as numbered steps.**
|
|
300
|
+
6. **The next action as a question.**
|
|
301
|
+
|
|
302
|
+
Emojis are welcome where they make the reply quicker to read — a ✅/❌ per row in a results table, 🎉 when something lands. The seven status circles appear only on a status line, never as decoration.
|
|
303
|
+
|
|
304
|
+
```md title="A reply in the response format"
|
|
305
|
+
🟣 Response format: template, setup and docs done; the checker is left.
|
|
306
|
+
|
|
307
|
+
I added the response format as a setup choice, like status circles. One problem: the recorded-answers check only knows six answers, so `standards:check` would pass a project that said yes without the answer recorded.
|
|
308
|
+
|
|
309
|
+
| File | Result |
|
|
310
|
+
| --- | --- |
|
|
311
|
+
| AGENTS.md template | ✅ Response format section added |
|
|
312
|
+
| Setup step 4 | ✅ Seventh offer added |
|
|
313
|
+
| working-with-agents.md | ✅ This section |
|
|
314
|
+
| checkRecordedAnswers.mjs | ❌ Missing the seventh answer |
|
|
315
|
+
|
|
316
|
+
How to fix it:
|
|
317
|
+
|
|
318
|
+
1. Add the response format to the checker's list of answers.
|
|
319
|
+
2. Update the checker's test to expect seven answers.
|
|
320
|
+
3. Run the tests and `pnpm standards:check`.
|
|
321
|
+
|
|
322
|
+
Want me to finish the checker now?
|
|
323
|
+
```
|
|
324
|
+
````
|
|
325
|
+
|
|
326
|
+
- [ ] **Step 3: Check formatting**
|
|
327
|
+
|
|
328
|
+
Run: `pnpm format:check`
|
|
329
|
+
Expected: passes
|
|
330
|
+
|
|
331
|
+
- [ ] **Step 4: Commit** (ask Tom first)
|
|
332
|
+
|
|
333
|
+
```bash
|
|
334
|
+
git add docs/Standards/working-with-agents.md
|
|
335
|
+
git commit -m "docs: response format in Working with Agents, with a worked example"
|
|
336
|
+
```
|
|
337
|
+
|
|
338
|
+
---
|
|
339
|
+
|
|
340
|
+
### Task 6: Full verification and the left-to-do note
|
|
341
|
+
|
|
342
|
+
**Files:**
|
|
343
|
+
|
|
344
|
+
- Modify: `docs/superpowers/specs/2026-11-17-agent-response-format-design.md` (no change expected — this task only verifies it matches what was built)
|
|
345
|
+
|
|
346
|
+
- [ ] **Step 1: Run the repo checks**
|
|
347
|
+
|
|
348
|
+
```bash
|
|
349
|
+
pnpm test
|
|
350
|
+
pnpm format:check
|
|
351
|
+
pnpm typecheck
|
|
352
|
+
```
|
|
353
|
+
|
|
354
|
+
Expected: all pass
|
|
355
|
+
|
|
356
|
+
- [ ] **Step 2: Run `pnpm devtest`** (the standards are not ready until it passes)
|
|
357
|
+
|
|
358
|
+
Run: `pnpm devtest`
|
|
359
|
+
Expected: passes — it lints and formats every template the way a project does
|
|
360
|
+
|
|
361
|
+
- [ ] **Step 3: Self-review against the spec**
|
|
362
|
+
|
|
363
|
+
Read the spec's Changes table row by row and point at the change in the working tree for each. Confirm:
|
|
364
|
+
|
|
365
|
+
- The template section sits outside the managed markers and `checkAgentFiles` still passes.
|
|
366
|
+
- "six" appears nowhere in the step-4 flow except the historical version-history entry (line 79 of `docs/version-history.md`, which stays untouched).
|
|
367
|
+
- The worked example's status line comes first and uses no traffic-light circle beyond the status line.
|
|
368
|
+
|
|
369
|
+
- [ ] **Step 4: Leave a note for the release**
|
|
370
|
+
|
|
371
|
+
The next version release (3.3.8 or later, whichever ships first) must add a version-history entry, same shape as ship's at `docs/version-history.md:79`: "A seventh setup question, the response format…", plus "records the seven agent answers" in its era of the check table. Record this as a leftover in the handover summary to Tom, not in a released version entry — the repo stays on 3.3.7.
|
|
372
|
+
|
|
373
|
+
- [ ] **Step 5: Commit anything left** (ask Tom first, per the standing rule)
|
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
# Agent Response Format — Design
|
|
2
|
+
|
|
3
|
+
**Status:** Decided · **Updated:** 2026-11-17
|
|
4
|
+
|
|
5
|
+
## Decision
|
|
6
|
+
|
|
7
|
+
Add an optional **Response format** choice to project setup, recorded in each project's `AGENTS.md` so every dev agent (Claude Code, Codex, ChatGPT, any agent that reads `AGENTS.md`) answers with the same clear structure Claude gives: an overview of the problem, results in tables, numbered action steps, a status line, and a closing question.
|
|
8
|
+
|
|
9
|
+
The choice works like status circles: setup offers it, and only a yes writes the section. It is a project-workflow choice, not a numbered code standard, so it never sits inside the managed code-standards markers. The repo stays on version 3.3.7 for now: the version-history entry (same shape as ship's "sixth setup question" entry) is written when the next version goes out, and that release is also what asks existing projects the seventh question.
|
|
10
|
+
|
|
11
|
+
## The format
|
|
12
|
+
|
|
13
|
+
When the section is present, every **substantive reply** uses it — anything with findings, results, options or a plan. A plain acknowledgement of a yes/no stays plain. The reply:
|
|
14
|
+
|
|
15
|
+
1. **Opens with the status line** when status circles are on — "here's where we're up to" comes before anything else.
|
|
16
|
+
2. **Then an overview** — one or two lines saying what happened or what was found, before any detail.
|
|
17
|
+
3. **Names each problem plainly** — what is wrong and why it matters, one per item, not buried in prose.
|
|
18
|
+
4. **Puts results and comparisons in tables** — check results, before/after, options — one row per item.
|
|
19
|
+
5. **Gives "how to fix it" as numbered steps**, each concrete enough to action on its own.
|
|
20
|
+
6. **Closes with the next action as a question**, such as "Want me to build it on a new branch?"
|
|
21
|
+
|
|
22
|
+
**Emojis where they help, not everywhere.** Use them when they make a response quicker to read than a slab of text — ✅/❌ per row in a results table, 🎉 when something lands, 🔧 for work in progress. The whole range is welcome; not every response needs them. They are seasoning, never decoration.
|
|
23
|
+
|
|
24
|
+
**Traffic-light circles belong to the status line only.** The seven status circles (✅ 🟢 🟣 🟡 🟠 🔴 ⚪) each carry one meaning from the Status circles system, and they appear only on a status line, in the format that section defines. For general flavour, use other symbols — 🎉, 🔧, 🚀 — never a bare traffic-light circle. A plain ✅/❌ tick in a results table is fine: it marks pass/fail, which reads unambiguously. Where a response reports ticket status, it does it through a status line at the start, not circles scattered through the prose; the two systems never blend.
|
|
25
|
+
|
|
26
|
+
## Changes
|
|
27
|
+
|
|
28
|
+
| File | Change |
|
|
29
|
+
| ----------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
30
|
+
| `static/templates/AGENTS.md` | New `### Response format` subsection under Project workflow, after `### Status circles`, with the standard "only if chosen during setup, otherwise delete" placeholder and the rules above. Outside the managed markers |
|
|
31
|
+
| `static/templates/docs/development/coding-standards.md` | The template's unfilled answers line gains `; response format [yes or no]` |
|
|
32
|
+
| `docs/Guides/setup.md` | Step 4 gains a seventh printed offer: "Response format (optional). Want the agent to answer with a clear structure — a short overview of the problem, results in tables, numbered action steps, and what it needs from you next?" A yes writes the section; a no writes nothing. The recorded-answers one-liner gains `response format [yes or no]`, and "all six answers" becomes seven |
|
|
33
|
+
| `docs/Standards/working-with-agents.md` | New "Response format" section documenting the choice, with a worked example response (genericised from the ESLint check-results example: status line first, overview, results table with ✅/❌, "how to fix it" steps, closing question) |
|
|
34
|
+
| `scripts/verifyStandards/checkRecordedAnswers.mjs` (+ test) | Learns the seventh answer, `response format`, so `standards:check` validates it like the other six |
|
|
35
|
+
|
|
36
|
+
## Rollout for existing projects
|
|
37
|
+
|
|
38
|
+
No migration work in this change, and no version bump: the repo stays on 3.3.7. New projects get the choice straight away, because setup and the templates change immediately. Existing projects run `standards:check` from their installed package version, so nothing changes for them until the next version goes out — its release adds the version-history entry (like ship's), and the update flow's standing step, "ask any Working with the agent question whose answer is not recorded", then asks them the seventh question.
|
|
39
|
+
|
|
40
|
+
## Why
|
|
41
|
+
|
|
42
|
+
Claude's structured answers make results readable at a glance; other dev agents answer in terse slabs, and the person re-reads everything to find what needs action. Encoding the format in `AGENTS.md` reaches every agent, since `AGENTS.md` is the one file they all read — Codex reads it natively. Making it a setup choice keeps the rollout gentle: no project has the section forced on it by a version bump.
|
|
43
|
+
|
|
44
|
+
## Related
|
|
45
|
+
|
|
46
|
+
- [Working with Agents](../../Standards/working-with-agents.md)
|
|
47
|
+
- [Setup — step 4](../../Guides/setup.md)
|
|
48
|
+
- [AGENTS.md template](https://github.com/activatus-life/code-standards/blob/main/static/templates/AGENTS.md)
|
package/docs/version-history.md
CHANGED
|
@@ -70,10 +70,92 @@ Anyone changing the standards adds a version, alongside the change:
|
|
|
70
70
|
|
|
71
71
|
## Version 3
|
|
72
72
|
|
|
73
|
-
**Released:** 2026-10-17 · **Updates from:** version 2 · **Latest:** 3.3.
|
|
73
|
+
**Released:** 2026-10-17 · **Updates from:** version 2 · **Latest:** 3.3.7
|
|
74
74
|
|
|
75
75
|
Install it with `pnpm add -D @activatus/code-standards@latest`. Do change 1 first: it says which parts of the project's `AGENTS.md` are now the project's own to write.
|
|
76
76
|
|
|
77
|
+
## Version 3.3.8 — not released yet
|
|
78
|
+
|
|
79
|
+
Do not apply this version yet. Changes are added to it over time.
|
|
80
|
+
|
|
81
|
+
**Fixes in 3.3.8.** If the project already applied 3.3.7, check these:
|
|
82
|
+
|
|
83
|
+
- **The version contradictions are fixed.** The Tech Stack page said "Linting: ESLint 9+" while the standard config needs ESLint 10.4 or later, and said "TypeScript 7" in its stack list while its version requirements said "5.0+". Both now agree. **What to do:** nothing — this fixes the site's words, not any config a project copies.
|
|
84
|
+
|
|
85
|
+
- **TypeScript is "latest stable", not a pinned major.** The stack said "TypeScript 7", which read as a mandate for a major the linting ecosystem had not caught up with. Now said: **a project uses the latest stable TypeScript** — 7 at the time of writing — and moves up when a new major ships and its tooling has caught up. A project that stays on an older major records it as an exception with the reason. **What to do:** nothing, if the project is on the latest stable that its tooling supports. If it is on an older major on purpose, record the exception; if it can move up, do.
|
|
86
|
+
|
|
87
|
+
- **Grid is allowed when it is genuinely better — flagged.** The rule was "only use CSS grid when it is specifically asked for", which read as a ban, but some layouts are genuinely two-dimensional and grid is the right tool for them. Now said: **flexbox first, always; use grid when the layout is genuinely two-dimensional — a card grid, an aligned table of panels — and say so when you do**, to the person or in a comment. The [Card Grid](/docs/design-system-components#cta-forms) Design System Component is the standing exception: a design that asks for one is the ask. See [Layout: Flexbox First](/docs/Standards/styling#-layout-flexbox-first).
|
|
88
|
+
|
|
89
|
+
**What to do:** nothing — this loosens the rule, so no project has anything to unwind. The `AGENTS.md` copy from 3.3.7 carries the new wording into the project.
|
|
90
|
+
|
|
91
|
+
- **A new standard, 17.1: the sitemap travels with the routes.** A project with public pages keeps `app/sitemap.ts` in sync as it routes: a public page added, renamed or removed changes the sitemap in the same change, never as a cleanup at the end. Public pages only — pages behind sign-in, API routes and redirecting handlers are not listed. A project with no public pages has no sitemap until the first one arrives. See [The sitemap travels with the routes](/docs/Structure/api-routes#sitemap).
|
|
92
|
+
|
|
93
|
+
**What to do:** if the project has public pages, check `app/sitemap.ts` exists and lists every one of them; build or complete it if not. If it has none, nothing. The `AGENTS.md` copy from 3.3.7 carries the rule into the project.
|
|
94
|
+
|
|
95
|
+
- **Setup asks about Biome when the project already has it.** A project that already lints or formats with Biome is asked at setup: keep Biome, or move to the standards' ESLint and Prettier? Keeping it is recorded as `6. ESLint — skipped` and `7. Prettier — skipped`, with the reason, and it runs by its own setup — the standards ship no Biome config. A project with no Biome gets no question: it uses ours. See [Agree the standards](/docs/Guides/setup#3-agree-the-standards).
|
|
96
|
+
|
|
97
|
+
**What to do:** for a project set up before this version that uses Biome, check the two exception lines are recorded in `docs/development/coding-standards.md`; ask and record them if not. Every other project: nothing.
|
|
98
|
+
|
|
99
|
+
**How to check:** `pnpm standards:check` passes, or lists only recorded exceptions; a project with public pages has an `app/sitemap.ts` that lists them; a project using Biome has its two exception lines recorded.
|
|
100
|
+
|
|
101
|
+
## Version 3.3.9 — not released yet
|
|
102
|
+
|
|
103
|
+
Do not apply this version yet. Changes are added to it over time.
|
|
104
|
+
|
|
105
|
+
- **A second package in the repo.** The standards and `pnpm standards:check` only look at the project root, so a second package — a Cloudflare Worker beside the app, a second app in a monorepo — is uncharted. A future version says when a repo carries a second package, what follows the standards and what gets a recorded exception. Requested by a project whose repo carries a worker beside the app.
|
|
106
|
+
|
|
107
|
+
**Fixes in 3.3.7.** If the project already applied 3.3.6, check these:
|
|
108
|
+
|
|
109
|
+
- **A new word, "ship", and a sixth setup question.** "Ship" means: commit the current change, push it, and open a Pull Request whose description says why the change was made, what changed, how it was checked, with the results, and what the reviewer should look at closely, and links the ticket. It is the yes for those three steps, for that one change only. It is a project workflow choice, not a code standard, so setup now asks it in [step 4](/docs/Guides/setup#4-working-with-the-agent) beside the other five, and `pnpm standards:check` reports a project whose answers do not include it. See [Ship](/docs/Standards/working-with-agents#ship) and the [ontology](/docs/ontology).
|
|
110
|
+
|
|
111
|
+
**What to do:**
|
|
112
|
+
|
|
113
|
+
1. **Print this to the person exactly as it is written**:
|
|
114
|
+
|
|
115
|
+
```text
|
|
116
|
+
When you say "ship", should AI commit the change, push it and
|
|
117
|
+
open a Pull Request that describes what changed and why?
|
|
118
|
+
Yes or no?
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
2. If they say yes, add the **Ship** line from the `AGENTS.md` template to the project's Project workflow section, filled in as setup step 4 says.
|
|
122
|
+
3. Add `ship [yes or no]` to the "Working with the agent" line under "Details" in `docs/development/coding-standards.md`, before the date.
|
|
123
|
+
|
|
124
|
+
- **Generated code has a home in `vendor/`, and AI-written code is ours.** `vendor/` was described as only for third-party code. A file a tool generates and replaces wholesale — such as the database types the Supabase CLI rewrites after every migration — is not ours either: nobody hand-edits it, and the next run of the tool replaces it. It now lives in `vendor/`, at any level, and is never linted, by the same `**/vendor/**` ignore that was already in every config. The other side is now written down too: **code an AI agent writes is our code**, and so is a script we write to drive a tool, such as a database migration — every standard applies to both. See [Third-party code is exempt](/docs/Standards/eslint#third-party-code-is-exempt).
|
|
125
|
+
|
|
126
|
+
**What to do:** find files a tool generates that the project keeps outside `vendor/` (search for the file the project's tool rewrites, such as a `database.types.ts`), move them into `vendor/`, and fix their imports. Check nothing hand-written went with them: a file with our edits in it is ours and comes back out. Then copy the `AGENTS.md` template over the project's `AGENTS.md`, keeping the project's own sections, and re-record any answers in the Project workflow section.
|
|
127
|
+
|
|
128
|
+
- **Custom hooks follow the utils ladder.** The standards said where utils live at every level — global, section, component — and where components live, but never said where hooks go beyond a root `hooks/` folder, so every hook placement was a guess. Now said: **a hook follows the same ladder as a util.** It starts in the component's `hooks/`, moves to the section's `hooks/` when another component in the section needs it, and moves to the global `hooks/` when anything outside the section needs it. One folder per hook, named after it, with its test and an `index.ts`. See [Hooks live the same way](/docs/Structure/folder-structure#hooks-live-the-same-way).
|
|
129
|
+
|
|
130
|
+
**What to do:** if the project already keeps hooks at section or component level, nothing — that placement is now the rule, not an accident. Record nothing. A hook sitting loose in a component file or in a guessed folder moves to the ladder spot its users say. The `AGENTS.md` copy from the previous change carries the rule into the project.
|
|
131
|
+
|
|
132
|
+
- **Route handlers outside `app/api/` are covered.** The standards only described handlers under `app/api/`, but Next.js gives every `route.ts` in `app/` a URL, so a project's auth callback — a URL the identity provider sends the browser back to, which reads the result and redirects on — was uncharted. Now said: a handler that returns JSON belongs under `app/api/`; a handler that redirects belongs at the URL the outside world already expects. Same rules apply there, handlers are **named exports** (`export async function GET`), never a default export, and their helpers follow the utils ladder. See [Route handlers outside `app/api/`](/docs/Structure/api-routes#-route-handlers-outside-appapi).
|
|
133
|
+
|
|
134
|
+
**What to do:** nothing, if the project's handlers already use named exports. Check any handler outside `app/api/` for a default export and convert it. Check its helpers are not sitting in the handler file itself.
|
|
135
|
+
|
|
136
|
+
- **There is no Select component.** The Design System Components list has Input with `type: select` in its variants, but nothing said so in words, and a project built Select as its own component, duplicating Input's name, label, help text, validation and error states. Now said in words under the list: **a field where the person picks one option from a list is an Input with `type: select`** (or `dropdown` or `auto-select`), with the choices passed through its `options` prop. Never a standalone component.
|
|
137
|
+
|
|
138
|
+
**What to do:** if the project built a standalone Select, rebuild it as an Input type, or record it as a deliberate exception in `docs/development/coding-standards.md` under "Details". The `AGENTS.md` copy from the previous change carries the rule into the project.
|
|
139
|
+
|
|
140
|
+
- **A seventh, optional question: the response format.** Like ship, this is a project workflow choice, not a code standard, so setup asks it in [step 4](/docs/Guides/setup#4-working-with-the-agent) beside the other six. A yes writes a **Response format** section into the project's `AGENTS.md`: every substantive reply — anything with findings, results, options or a plan — opens with the status line, then an overview, names each problem plainly, puts results in tables, gives fixes as numbered steps, and closes with the next action as a question. A plain yes or no stays plain. `pnpm standards:check` reports a project whose recorded answers do not include it, and the setup guide's update flow asks any answer that is not recorded. See [Setup, step 4](/docs/Guides/setup#4-working-with-the-agent).
|
|
141
|
+
|
|
142
|
+
**What to do:**
|
|
143
|
+
|
|
144
|
+
1. Copy the `AGENTS.md` template over the project's `AGENTS.md`, keeping the project's own sections.
|
|
145
|
+
2. **Print this to the person exactly as it is written**:
|
|
146
|
+
|
|
147
|
+
```text
|
|
148
|
+
Response format (optional). Want the agent to answer with a
|
|
149
|
+
status line, an overview, problems named, results in tables,
|
|
150
|
+
numbered fixes, and the next action as a question?
|
|
151
|
+
Yes or no?
|
|
152
|
+
```
|
|
153
|
+
|
|
154
|
+
3. If they say yes, add the **Response format** section from the template to the project's Project workflow section, filled in as setup step 4 says.
|
|
155
|
+
4. Add `response format [yes or no]` to the "Working with the agent" line under "Details" in `docs/development/coding-standards.md`, before the date.
|
|
156
|
+
|
|
157
|
+
**How to check:** `pnpm standards:check` passes, or lists only recorded exceptions; the "Working with the agent" line records ship and the response format; if the answer was yes, `AGENTS.md` has a Ship line and a Response format section under Project workflow; generated files live in `vendor/` and their imports work; every hook sits at its ladder spot; every handler is a named export; any standalone Select is rebuilt or recorded.
|
|
158
|
+
|
|
77
159
|
**Fixes in 3.3.6.** If the project already applied 3.3.5, check these:
|
|
78
160
|
|
|
79
161
|
- **The templates are now formatted with the template Prettier config.** The import sorting added in 3.3.3 reordered the imports in the four `eslint.config.mjs` templates, so after `pnpm format` a project's copy no longer matched the template, and `pnpm standards:check` failed standard 6. `pageLayout.visual.ts`, the docs site's `index.tsx`, and the tables in the `ontology.md` and `design-system.md` templates changed the same way. Every template is now already formatted, and the code standards check this before each release, so `pnpm format` leaves a copied template as it is.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@activatus/code-standards",
|
|
3
|
-
"version": "3.3.
|
|
3
|
+
"version": "3.3.8",
|
|
4
4
|
"description": "The Activatus code standards: the rules as Markdown, and the config files to copy. Install it so an AI agent can read the standards from node_modules.",
|
|
5
5
|
"repository": {
|
|
6
6
|
"type": "git",
|
|
@@ -34,15 +34,15 @@
|
|
|
34
34
|
"@ianvs/prettier-plugin-sort-imports": "^4.7.1",
|
|
35
35
|
"@mdx-js/react": "^3.0.0",
|
|
36
36
|
"clsx": "^2.0.0",
|
|
37
|
-
"eslint": "^10.
|
|
38
|
-
"eslint-config-next": "^16.4.
|
|
37
|
+
"eslint": "^10.15.0",
|
|
38
|
+
"eslint-config-next": "^16.4.6",
|
|
39
39
|
"eslint-config-prettier": "^10.1.8",
|
|
40
40
|
"eslint-import-resolver-typescript": "^4.4.5",
|
|
41
|
-
"eslint-plugin-import-x": "^4.
|
|
41
|
+
"eslint-plugin-import-x": "^4.18.1",
|
|
42
42
|
"eslint-plugin-react": "^7.37.5",
|
|
43
43
|
"eslint-plugin-react-hooks": "^7.1.1",
|
|
44
|
-
"eslint-plugin-unicorn": "^
|
|
45
|
-
"globals": "^17.
|
|
44
|
+
"eslint-plugin-unicorn": "^80.0.0",
|
|
45
|
+
"globals": "^17.14.0",
|
|
46
46
|
"next": "^16.4.2",
|
|
47
47
|
"pagefind": "^1.3.0",
|
|
48
48
|
"prettier": "^3.9.10",
|
|
@@ -53,7 +53,7 @@
|
|
|
53
53
|
"react-dom": "^18.3.1",
|
|
54
54
|
"tailwindcss": "^4.3.3",
|
|
55
55
|
"typescript": "~5.6.2",
|
|
56
|
-
"typescript-eslint": "^8.72.
|
|
56
|
+
"typescript-eslint": "^8.72.2"
|
|
57
57
|
},
|
|
58
58
|
"browserslist": {
|
|
59
59
|
"production": [
|
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
// What setup asks the person and writes down: the
|
|
1
|
+
// What setup asks the person and writes down: the seven agent answers
|
|
2
2
|
// (standard 21) and the colour palette (standard 11).
|
|
3
3
|
import {
|
|
4
4
|
CODING_STANDARDS_PATH,
|
|
@@ -16,6 +16,8 @@ const AGENT_ANSWERS = [
|
|
|
16
16
|
name: "being told about decisions",
|
|
17
17
|
pattern: /told about decisions/i,
|
|
18
18
|
},
|
|
19
|
+
{ name: "ship", pattern: /\bship\b/i },
|
|
20
|
+
{ name: "the response format", pattern: /response format/i },
|
|
19
21
|
];
|
|
20
22
|
// The template's unfilled line: "[link or None]", "[yes or no]".
|
|
21
23
|
const UNFILLED_ANSWER_PATTERN = /\[[^\]]+ or [^\]]+\]/;
|
|
@@ -43,6 +43,7 @@
|
|
|
43
43
|
|
|
44
44
|
- **Who commits**: [whether AI agents may commit, push or make branches, and when. If the person said yes to asking before committing during setup: "Ask the person before every commit and push, and wait for a clear yes to that specific action. A yes covers one action only." If they said no, leave the asking rule out]
|
|
45
45
|
- **Decisions**: [Optional. If the person said yes to being told about decisions during setup: "Tell the person about each coding decision you make that the code standards do not cover, in the summary at the end of the task." Delete this line if they said no]
|
|
46
|
+
- **Ship**: [Optional. If the person said yes to ship during setup: "When the person says 'ship', commit the current change, push it, and open a Pull Request. 'Ship' is the yes for those three steps, for that change only. The Pull Request description says why the change was made, what changed, how it was checked, with the results, and what the reviewer should look at closely, and links the ticket." Delete this line if they said no]
|
|
46
47
|
- **Branches**: [how branches are named]
|
|
47
48
|
- **Commit messages**: [the commit message format]
|
|
48
49
|
- **Pull requests**: [review and CI requirements, and where Pull Requests merge to]
|
|
@@ -74,6 +75,21 @@ Example: `🟢 [ABC-12](https://linear.app/[workspace]/issue/ABC-12) Short title
|
|
|
74
75
|
- Work with no ticket is just the circle and a short title.
|
|
75
76
|
- Only what the person needs to act on. Leave out what they already know.
|
|
76
77
|
|
|
78
|
+
### Response format
|
|
79
|
+
|
|
80
|
+
[Only if the person chose the response format during setup. Otherwise delete this section.]
|
|
81
|
+
|
|
82
|
+
Answer every substantive reply — anything with findings, results, options or a plan — in this shape. A plain yes or no stays plain.
|
|
83
|
+
|
|
84
|
+
1. **The status line first**, when status circles are on: where the work is up to, before anything else, in the format the Status circles section defines.
|
|
85
|
+
2. **An overview** — one or two lines: what happened or what was found, before any detail.
|
|
86
|
+
3. **Each problem named plainly** — what is wrong and why it matters, one per item, not buried in prose.
|
|
87
|
+
4. **Results and comparisons in tables** — check results, before and after, options — one row per item.
|
|
88
|
+
5. **"How to fix it" as numbered steps**, each concrete enough to action on its own.
|
|
89
|
+
6. **The next action as a question**, so the person only has to answer it.
|
|
90
|
+
|
|
91
|
+
**Emojis where they help, not everywhere.** Use them when they make the reply quicker to read than a slab of text — ✅/❌ per row in a results table, 🎉 when something lands, 🔧 for work in progress. The whole range is welcome; not every reply needs them. **Traffic-light circles are the exception:** the seven status circles (✅ 🟢 🟣 🟡 🟠 🔴 ⚪) carry one meaning each from the Status circles section and appear only on a status line. For flavour use other symbols. A ✅/❌ tick in a results table marks pass and fail, not the circle's status meaning — that is fine.
|
|
92
|
+
|
|
77
93
|
## Environment variables
|
|
78
94
|
|
|
79
95
|
| Variable | Required | Description |
|
|
@@ -138,16 +154,18 @@ Follow these rules in every change:
|
|
|
138
154
|
- **A component's children sit flat in its own `components/` folder**, `accordion/components/item/` and `accordion/components/ctaArrow/`, even when one child is only used by another. Never a `components/` folder inside a child: two levels at most.
|
|
139
155
|
- **Component file order**: imports, component, variables, state, `useMemo` values, `useCallback` functions, effects, render. No inline functions in render.
|
|
140
156
|
- **Reusable functions live in a `utils/` folder** — global, section or component level — one folder per function, with an `index.ts`. A function that sorts, finds, gets, filters or formats the data passed to it goes in a `utils/` folder the first time it is written. Move a function up a level when a second user needs it.
|
|
157
|
+
- **Custom hooks live in a `hooks/` folder the same way** — global, section or component level — one folder per hook, named after it, with its test and an `index.ts`. Move a hook up a level when a second user needs it. Never a hook inside the component file.
|
|
141
158
|
- **Components live where they are used:** Design System Components in `components/ui/`, plus any props-only component not on the list yet, recorded under "Components for the standards" in `docs/development/coding-standards.md`; the site frame (navigation, header, footer) in `components/layout/`; the homepage's components in `app/(homepage)/components/`; components used on three or more pages in `components/shared/`; components used by three or more pages in one section in that section's route group (`app/(billing)/components/`); everything else in its page's `components/` folder. Start a new component beside its page. When a second page needs it, copy it there: one copy only, and each copy has a comment naming the other. When a third page needs it, merge the copies into one shared component, with props designed from all three uses. No `components/features/` folder.
|
|
142
159
|
- **Code file names are camelCase**; component files are PascalCase. **Anything that becomes a URL is kebab-case**: route folders and documentation folders and files (`docs/architecture/background-jobs.md`). CSS variables are kebab-case too.
|
|
143
|
-
- **
|
|
160
|
+
- **The sitemap travels with the routes.** When a public page is added, renamed or removed, its line in `app/sitemap.ts` changes in the same change — never as a cleanup at the end. Public pages only: pages behind sign-in, API routes and redirecting handlers are not listed. A project with no public pages has no sitemap until the first one arrives.
|
|
161
|
+
- **Lay out with flexbox first**, and split layouts into child components. **Use CSS grid only when it is genuinely the better tool** — a card grid, two-dimensional alignment — and say so when you do: tell the person grid fits this case. The Card Grid Design System Component is the standing exception: when the design asks for one, that is the ask.
|
|
144
162
|
- **Style with Tailwind.** Colours come from the global colour palette in `app/globals.css` only — never a hard-coded or arbitrary colour. The design decisions are in `docs/design/design-system.md`.
|
|
145
163
|
- **Comments explain why, not what.** Never leave commented-out code. Mark unfinished work with `// TODO: Message` (`{/* TODO: Message */}` in JSX).
|
|
146
164
|
- **Error messages say what happened and what to do.**
|
|
147
165
|
|
|
148
|
-
**Third-party code is exempt.** Code in `node_modules/` and `vendor/` belongs to someone else: do not lint it, do not reformat it, do not edit it to meet these rules.
|
|
166
|
+
**Third-party and generated code is exempt.** Code in `node_modules/` and `vendor/` belongs to someone else: do not lint it, do not reformat it, do not edit it to meet these rules. **Files a tool generates and replaces wholesale** — such as database types the Supabase CLI rewrites after every migration — belong in `vendor/` too, never hand-edited. **Code an AI agent writes is ours**, and so is a script we write to drive a tool, such as a migration: every standard applies.
|
|
149
167
|
|
|
150
|
-
**shadcn components are not third-party.** Code the shadcn CLI copies into the project is ours. Convert it to these standards in the same change that adds it — its own camelCase folder, one component per file, `types.ts`, `index.ts` and a test — keep only the parts that are used, and never put it in `vendor/`. **Do not change a component's props or behaviour** — only its styling. Components work identically in every Activatus project.
|
|
168
|
+
**shadcn components are not third-party.** Code the shadcn CLI copies into the project is ours. Convert it to these standards in the same change that adds it — its own camelCase folder, one component per file, `types.ts`, `index.ts` and a test — keep only the parts that are used, and never put it in `vendor/`. **Do not change a component's props or behaviour** — only its styling. Components work identically in every Activatus project. **There is no Select component**: a pick-one-option field is an Input with `type: select`, through its `options` prop.
|
|
151
169
|
|
|
152
170
|
**Look before you build a component.** Check the project's `components/ui/`, then the Design System Components in the code standards, then other Activatus projects, then shadcn. Build to the props listed in the Design System Components; never invent new prop names for a component that is already listed. A component in `components/ui/` takes everything through props and never imports from features, services, stores or `app/`.
|
|
153
171
|
|
|
@@ -16,7 +16,7 @@ Every Activatus project follows the same standards, so people and agents can mov
|
|
|
16
16
|
|
|
17
17
|
[For each standard this project skips or changes, at setup or later, one line: its number and name from the setup list, "skipped" or "changed", why, and the date the person agreed. For example: "7. Prettier — skipped: the project uses Biome for formatting (2026-10-23)." An exception for only some files names them in backticks after "for": "4. Every function and component has a test file — changed for `app/api/**`: legacy routes, tested when replaced (2026-10-27)." Start no other line here with a number: `pnpm standards:check` reads every numbered line as an exception. Every rule in `eslint.overrides.mjs` has an entry here. If nothing differs, write "No differences".]
|
|
18
18
|
|
|
19
|
-
- Working with the agent: GitHub repo [link or None]; Linear project [project or None]; status circles [yes or no]; ask before every commit and push [yes or no]; told about decisions [yes or no] ([YYYY-MM-DD]).
|
|
19
|
+
- Working with the agent: GitHub repo [link or None]; Linear project [project or None]; status circles [yes or no]; ask before every commit and push [yes or no]; told about decisions [yes or no]; ship [yes or no]; response format [yes or no] ([YYYY-MM-DD]).
|
|
20
20
|
|
|
21
21
|
## Components for the standards
|
|
22
22
|
|