project-spec 0.9.0 → 0.9.2
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/README.md
CHANGED
|
@@ -1,157 +1,45 @@
|
|
|
1
1
|
# Project Spec Skills
|
|
2
2
|
|
|
3
|
-
**Turn a repository into
|
|
3
|
+
**Turn a repository into a spec people can read: one page per feature, every business rule numbered.**
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
Agent skills for the moment after you built fast with AI and now need to know what the product really does. The agent reads the code you already have and writes down how it works. You read the result in a local viewer, question it, and change the product starting from it.
|
|
6
6
|
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
- an **as-built spec**: exactly how the code is implemented now, derived only from source. Each feature has one page: what it is for, how it works, its fields and its business rules, every rule with a number you can quote. What people or agents agreed in chats is not part of it.
|
|
10
|
-
- a **gap queue**: the agent's guesses about what is missing, doubtful or worth adding, one question per page. People re-check each gap and decide it, with a separate discussion and decision for every item.
|
|
11
|
-
|
|
12
|
-
To read it there is a small **local viewer**: one command opens the spec as a plain document in your browser, straight from the files on disk, and turns what you read into a request for your agent. [See how it works](#read-the-spec-then-work-from-it). Obsidian works too and is optional. The other skills work with ordinary repository files, with or without a vault.
|
|
7
|
+
This is an early project. It has been used on a few real repositories; [VALIDATION.md](VALIDATION.md) says what was checked and what was not.
|
|
13
8
|
|
|
14
9
|

|
|
15
10
|
|
|
16
|
-
##
|
|
17
|
-
|
|
18
|
-
| For | Skill | What you get |
|
|
19
|
-
| --- | --- | --- |
|
|
20
|
-
| Understand | [project-knowledge](skills/project-knowledge/SKILL.md) | An as-built spec of capabilities and behavior and a separate queue of individually tracked gaps. It also audits written requirements against the code, answers one question or re-checks one gap, keeps the spec in step with Git history and reconciles concurrent vault updates. It never changes application code. |
|
|
21
|
-
| Change (experimental) | [spec-change](skills/spec-change/SKILL.md) | A source-grounded plan with decision gates and observable acceptance criteria, or the change itself: you edit the spec on a branch, the agent reviews the diff and asks its questions before any code, then implements it and checks each changed statement against the code. |
|
|
22
|
-
|
|
23
|
-
Each skill is independently usable. A useful sequence is:
|
|
24
|
-
|
|
25
|
-
```mermaid
|
|
26
|
-
flowchart LR
|
|
27
|
-
A[Map the project] --> B[Read it in the viewer]
|
|
28
|
-
B --> C[Audit a spec or re-check a gap]
|
|
29
|
-
C --> D[A person decides, then plan]
|
|
30
|
-
B --> E[Edit the spec: spec-change]
|
|
31
|
-
D --> F[Implement and verify]
|
|
32
|
-
E --> F
|
|
33
|
-
F --> A
|
|
34
|
-
```
|
|
35
|
-
|
|
36
|
-
`project-knowledge` never changes application code; `spec-change` is the one that does, and only after it has asked its questions. Reading a test establishes what it expects; only running it produces a test result.
|
|
37
|
-
|
|
38
|
-
## Read the spec, then work from it
|
|
39
|
-
|
|
40
|
-
The vault is plain Markdown: easy for an agent to write, tiring for a person to read file by file. The viewer is the reading side. It is one local page that reads the vault from disk every time it loads, so there is nothing to build first.
|
|
41
|
-
|
|
42
|
-
It is made for one loop:
|
|
43
|
-
|
|
44
|
-
1. **Read.** A tree lists the areas and the features in each. A feature page says in plain words what the feature is for and how it works, then lists its fields and its numbered business rules; the source files and the properties are folded away. A breadcrumb, Back and Forward and a "You are here" card say where you are, and the related pages are listed beside the text.
|
|
45
|
-
2. **Find.** Search (Cmd/Ctrl+K) covers pages, gaps and the text of the files the pages cite. A rule number such as `BR-CANCEL-02` finds its page.
|
|
46
|
-
3. **Ask.** "Copy for AI" on any page turns the page and your own words into a request for your agent that names the page file. For a gap: recheck it, record a check you did yourself, record your decision, lay out the options, plan it. For any page: change the behavior, ask a question, or remove a page that is only noise. Each choice says what will happen, and you see the exact text before you copy it.
|
|
47
|
-
4. **Let the agent work.** Paste the brief into your agent. With `spec-change` it asks its questions first, edits the spec on a branch, builds the change and checks every changed statement against the code.
|
|
48
|
-
5. **See what moved.** Recent changes lists the pages whose cited sources changed since the last review, the pages not committed yet, and the vault's Git history with what each summary said before and after.
|
|
49
|
-
|
|
50
|
-
| Search | Copy for AI |
|
|
51
|
-
| --- | --- |
|
|
52
|
-
|  |  |
|
|
53
|
-
| **Recent changes** | **Gap queue** |
|
|
54
|
-
|  |  |
|
|
55
|
-
|
|
56
|
-

|
|
11
|
+
## Start
|
|
57
12
|
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
### Open it with one command
|
|
61
|
-
|
|
62
|
-
With the [package](#with-npm) installed in your project, add a script to `package.json`:
|
|
63
|
-
|
|
64
|
-
```json
|
|
65
|
-
{
|
|
66
|
-
"scripts": {
|
|
67
|
-
"spec": "project-spec serve"
|
|
68
|
-
}
|
|
69
|
-
}
|
|
70
|
-
```
|
|
71
|
-
|
|
72
|
-
`npm run spec` then opens the viewer for that project. Without the package, the command is the helper itself, where `<skill>` is the `project-knowledge` folder (`~/.claude/skills/project-knowledge`, `~/.codex/skills/project-knowledge`, or a copy kept inside the repository):
|
|
13
|
+
You need an agent that can read your repository (Claude Code or Codex), Python 3.10+, Git, and Node 18+ for the `npx` commands.
|
|
73
14
|
|
|
74
15
|
```sh
|
|
75
|
-
|
|
16
|
+
npx project-spec install --claude # or --codex
|
|
76
17
|
```
|
|
77
18
|
|
|
78
|
-
|
|
19
|
+
Ask your agent:
|
|
79
20
|
|
|
80
|
-
```
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
```sh
|
|
86
|
-
alias spec='python3 ~/.claude/skills/project-knowledge/scripts/knowledge.py serve --open --repo'
|
|
21
|
+
```text
|
|
22
|
+
Use the project-knowledge skill to build a knowledge vault for this repository.
|
|
23
|
+
Describe only what the code does: one page per feature with its business rules,
|
|
24
|
+
and every doubt as its own gap.
|
|
87
25
|
```
|
|
88
26
|
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
### Show it on a server
|
|
92
|
-
|
|
93
|
-
`serve` is for your own machine. To let the rest of the team read the spec on a development or staging server, write the viewer as one file and let your application return it:
|
|
27
|
+
Then read what it wrote:
|
|
94
28
|
|
|
95
29
|
```sh
|
|
96
|
-
project-spec
|
|
97
|
-
--source-url 'https://github.com/OWNER/REPO/blob/{commit}'
|
|
30
|
+
npx project-spec serve
|
|
98
31
|
```
|
|
99
32
|
|
|
100
|
-
|
|
33
|
+
There is also a Claude Code plugin, a manual install and a way to pin one version for a team: see [Install and update](docs/install.md).
|
|
101
34
|
|
|
102
|
-
|
|
103
|
-
| --- | --- |
|
|
104
|
-
| `--out FILE` | Where to write the page. It must be outside the vault: nothing is generated into the vault. |
|
|
105
|
-
| `--source-url URL` | Where a cited file can be read. The file's path in the repository is added to this address, and `{commit}` becomes the commit the page was built from. Without it, cited files are shown as names. |
|
|
106
|
-
| `--with-sources` | Put the text of the cited files into the page, as `serve` does, so they open inside the viewer. Leave it out when people who may not read the repository can open the page. |
|
|
107
|
-
| `--allow-missing-sources` | Do not stop when a cited file is not there. For a build that sees only part of the repository, such as a Docker build whose `.dockerignore` leaves files out. The command lists the files it did not find. |
|
|
108
|
-
|
|
109
|
-
The spec describes how the product works inside, and with `--with-sources` it carries source code. So treat the file like the repository:
|
|
110
|
-
|
|
111
|
-
- Keep it out of folders the web server publishes by itself (`public/`, `static/`). Return it from a route that checks who is asking.
|
|
112
|
-
- Build it only for the environments that should have it, and make the route answer 404 everywhere else.
|
|
113
|
-
- If your application sets a `Content-Security-Policy`, the page needs inline scripts and styles and nothing else.
|
|
114
|
-
|
|
115
|
-
For example, a route in a Next.js application (a sketch: put your own sign-in check where `signedIn()` is):
|
|
116
|
-
|
|
117
|
-
```ts
|
|
118
|
-
// src/app/development/spec/route.ts
|
|
119
|
-
import { readFile } from "node:fs/promises";
|
|
120
|
-
import path from "node:path";
|
|
121
|
-
|
|
122
|
-
export const dynamic = "force-dynamic";
|
|
123
|
-
|
|
124
|
-
export async function GET() {
|
|
125
|
-
if (process.env.SPEC_PAGE !== "on" || !(await signedIn())) {
|
|
126
|
-
return new Response("Not found", { status: 404 });
|
|
127
|
-
}
|
|
128
|
-
const page = await readFile(path.join(process.cwd(), "build/spec.html"));
|
|
129
|
-
return new Response(page, {
|
|
130
|
-
headers: {
|
|
131
|
-
"Content-Type": "text/html; charset=utf-8",
|
|
132
|
-
"Cache-Control": "no-store",
|
|
133
|
-
"X-Robots-Tag": "noindex",
|
|
134
|
-
"Content-Security-Policy":
|
|
135
|
-
"default-src 'none'; script-src 'unsafe-inline'; style-src 'unsafe-inline'; base-uri 'none'; form-action 'none'",
|
|
136
|
-
},
|
|
137
|
-
});
|
|
138
|
-
}
|
|
139
|
-
```
|
|
35
|
+
## What you get
|
|
140
36
|
|
|
141
|
-
|
|
37
|
+
A folder of plain Markdown in your repository (it also opens in Obsidian) with two layers that stay apart:
|
|
142
38
|
|
|
143
|
-
|
|
39
|
+
- **The as-built spec.** How the code works now, taken only from the source. Each feature has one page: what it is for, how it works, its fields and its numbered rules. What people agreed in chats is not part of it.
|
|
40
|
+
- **The gap queue.** The agent's questions about what is missing, doubtful or worth adding, one per page. People re-check each one and decide it. The agent never records a decision nobody made.
|
|
144
41
|
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
| Section | What it holds |
|
|
148
|
-
| --- | --- |
|
|
149
|
-
| Opening | What the feature is for, who uses it and where it is found. |
|
|
150
|
-
| `How it works` | What happens, step by step, in the product's words. |
|
|
151
|
-
| `Fields` | One row per input: whether it is required, its rule, the message when it is refused. |
|
|
152
|
-
| `Business rules` | One numbered row per rule, with the values from the code. |
|
|
153
|
-
|
|
154
|
-
This is the page in the screenshot above, as the agent wrote it:
|
|
42
|
+
A page looks like this:
|
|
155
43
|
|
|
156
44
|
```markdown
|
|
157
45
|
# Only requested pickups are currently cancellable
|
|
@@ -159,11 +47,6 @@ This is the page in the screenshot above, as the agent wrote it:
|
|
|
159
47
|
A customer who no longer needs a pickup cancels it, and the service lets that
|
|
160
48
|
happen only before anyone has started work on it.
|
|
161
49
|
|
|
162
|
-
## How it works
|
|
163
|
-
|
|
164
|
-
`cancel_pickup` in the service first runs the ownership check, then looks at the
|
|
165
|
-
pickup's state. A pickup that passes both is set to `cancelled` and returned.
|
|
166
|
-
|
|
167
50
|
## Business rules
|
|
168
51
|
|
|
169
52
|
| ID | Rule |
|
|
@@ -172,226 +55,59 @@ pickup's state. A pickup that passes both is set to `cancelled` and returned.
|
|
|
172
55
|
| BR-CANCEL-02 | In any other state the cancellation is refused with "Only requested pickups can be cancelled" and nothing is changed. |
|
|
173
56
|
```
|
|
174
57
|
|
|
175
|
-
A rule
|
|
176
|
-
|
|
177
|
-
Things the code registers in one place and no single feature owns (background jobs, emails, routes, roles, plan limits) are listed in reference pages: one table with every item. A page cites the one to five files that decide its behavior. When one of them changes, the page is marked "Code changed since the last check" until someone re-reads it.
|
|
178
|
-
|
|
179
|
-
### Big features and several apps
|
|
180
|
-
|
|
181
|
-
A feature that is too big for one page (more than about twenty rules, or several kinds of use, such as direct, group and support chats) has **parts**. The vault then has three levels: the area, the feature, and its parts. The feature's page says what it is for and lists its parts; each part is a page of the same shape with its own rules. The viewer shows the parts under their feature.
|
|
182
|
-
|
|
183
|
-
When the product has several clients, such as a web app and a mobile app, a feature page has one more section, `## Where the apps differ`: a table with what each client does, one row per difference.
|
|
184
|
-
|
|
185
|
-
### How deep the first map goes
|
|
186
|
-
|
|
187
|
-
The first map starts with an inventory: every page or screen, every server procedure, every job and email, counted from the place that registers them. The agent then takes one feature at a time and finishes it before starting the next. A page whose feature was not read to the end is marked **Partial** and says what is left. A first map of a large project is therefore a number of finished features and a list of the ones not started, not a thin page about everything.
|
|
188
|
-
|
|
189
|
-
One command shows what is still missing, by reading the code and the pages:
|
|
190
|
-
|
|
191
|
-
```sh
|
|
192
|
-
project-spec coverage # every folder, the least covered first
|
|
193
|
-
project-spec coverage --path src/features/chat # one feature: each message and limit no page mentions
|
|
194
|
-
```
|
|
195
|
-
|
|
196
|
-
Without the package: `python3 <skill>/scripts/coverage.py --repo .`. For each folder it prints how many files a page cites, and how many messages a person can see and how many named limits are on no page. It is a list of places to read, not a score: some of what it lists is left out of the spec on purpose.
|
|
197
|
-
|
|
198
|
-
## Why use this?
|
|
199
|
-
|
|
200
|
-
- **Onboarding:** follow a workflow across UI, API, policy, persistence and tests without rediscovering the same paths every session.
|
|
201
|
-
- **Change planning:** see which rules and related areas a change can affect before writing code.
|
|
202
|
-
- **Rules you can point at:** a reviewer, a tester or a support person can say "BR-CANCEL-02 is wrong" instead of describing a screen.
|
|
203
|
-
- **Useful gap reports:** each doubt is its own page, typed as a missing capability, outdated documentation, an unverified scenario, a conflict or an undecided product proposal, and carries who re-checked it and who decided it.
|
|
204
|
-
- **Team memory:** commit the notes with the project. A manual sync reviews changes from all contributors since the last reviewed commit, including older commits and merges.
|
|
58
|
+
A rule keeps its number for good, so a reviewer, a tester or a support person can say "BR-CANCEL-02 is wrong" instead of describing a screen. When a file a page relies on changes, the page is marked for re-reading.
|
|
205
59
|
|
|
206
|
-
|
|
60
|
+
## The viewer
|
|
207
61
|
|
|
208
|
-
|
|
62
|
+
One local page, read from the files on disk. Nothing is built or uploaded.
|
|
209
63
|
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
The package is [`project-spec`](https://www.npmjs.com/package/project-spec) on the npm registry, with one command of the same name. It needs Node 18+ in addition to Python. Nothing has to be installed first:
|
|
215
|
-
|
|
216
|
-
```sh
|
|
217
|
-
npx project-spec install --claude # or --codex, or --dir knowledge/tooling
|
|
218
|
-
npx project-spec serve # the viewer for the project in the current folder
|
|
219
|
-
npx project-spec build --out FILE # the same viewer as one file, to show on a server
|
|
220
|
-
npx project-spec coverage # what the code has that no spec page mentions yet
|
|
221
|
-
```
|
|
222
|
-
|
|
223
|
-
Then ask your agent to use the `project-knowledge` skill ([example prompts](#example-prompts)).
|
|
224
|
-
|
|
225
|
-
To pin one version for everyone on a project, add it as a development dependency:
|
|
226
|
-
|
|
227
|
-
```sh
|
|
228
|
-
npm install --save-dev project-spec
|
|
229
|
-
```
|
|
230
|
-
|
|
231
|
-
The lockfile then pins the version, and `npm update project-spec` moves it forward. The command keeps every copy of the skills in step with that version:
|
|
232
|
-
|
|
233
|
-
```sh
|
|
234
|
-
npx project-spec status # where the copies are and whether each is current
|
|
235
|
-
npx project-spec update # refresh every copy that status lists
|
|
236
|
-
```
|
|
237
|
-
|
|
238
|
-
`status` and `update` look in `~/.claude/skills`, `~/.codex/skills` and the usual folders of the current project (`knowledge/tooling`, `.claude/skills`, `.codex/skills`, `.agents/skills`). `update` refreshes what is there and adds nothing new; `install` adds. A copy you edited by hand is not replaced unless you pass `--force`, and the old files are kept under `~/.project-spec/backups` first. `--skills project-knowledge` limits an install to the skills you name.
|
|
239
|
-
|
|
240
|
-
To run the unreleased version from this repository, use `npx github:WorldStoryCm/project-spec-skills status` in place of `npx project-spec status`.
|
|
241
|
-
|
|
242
|
-
### Claude Code plugin
|
|
243
|
-
|
|
244
|
-
The repository is also a plugin marketplace for Claude Code. Inside Claude Code:
|
|
245
|
-
|
|
246
|
-
```text
|
|
247
|
-
/plugin marketplace add WorldStoryCm/project-spec-skills
|
|
248
|
-
/plugin install project-spec@project-spec-skills
|
|
249
|
-
```
|
|
64
|
+
1. **Read** a feature page: its purpose, its flow, its rules.
|
|
65
|
+
2. **Find** anything with search, including a rule number.
|
|
66
|
+
3. **Ask**: "Copy for AI" turns the page and your own words into a request for your agent.
|
|
67
|
+
4. **See what moved**: the pages whose code changed since they were last checked.
|
|
250
68
|
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
|
|
255
|
-
|
|
256
|
-
|
|
257
|
-
```text
|
|
258
|
-
Install these skills from WorldStoryCm/project-spec-skills:
|
|
259
|
-
skills/project-knowledge
|
|
260
|
-
skills/spec-change
|
|
261
|
-
```
|
|
262
|
-
|
|
263
|
-
If you already have a skill with the same name, compare versions before replacing it. The installer in Codex handles its own destination. In Codex you can name a skill with `$name`, for example `$spec-change`.
|
|
264
|
-
|
|
265
|
-
### Claude Code, by hand
|
|
266
|
-
|
|
267
|
-
Copy the whole skill folder (it contains the references and helper scripts) to one of:
|
|
268
|
-
|
|
269
|
-
- `~/.claude/skills/<name>/` to use it in all your projects, or
|
|
270
|
-
- `.claude/skills/<name>/` inside one project.
|
|
271
|
-
|
|
272
|
-
```sh
|
|
273
|
-
git clone https://github.com/WorldStoryCm/project-spec-skills.git
|
|
274
|
-
mkdir -p ~/.claude/skills
|
|
275
|
-
cp -R project-spec-skills/skills/project-knowledge ~/.claude/skills/
|
|
276
|
-
cp -R project-spec-skills/skills/spec-change ~/.claude/skills/
|
|
277
|
-
```
|
|
278
|
-
|
|
279
|
-
Then ask in plain language, or invoke a skill by name with `/<name>`, for example `/spec-change`. Claude Code finds a skill from its description, so an ordinary request often picks the right one.
|
|
280
|
-
|
|
281
|
-
### Example prompts
|
|
282
|
-
|
|
283
|
-
These work in any host; use `$name` or `/name` where your host supports it, or just say which skill you mean.
|
|
284
|
-
|
|
285
|
-
```text
|
|
286
|
-
Use the project-knowledge skill to build an English knowledge vault for this repository.
|
|
287
|
-
Describe only what the code does: one page per feature with its business rules,
|
|
288
|
-
each claim linked to source, and every doubt as its own gap.
|
|
289
|
-
```
|
|
290
|
-
|
|
291
|
-
```text
|
|
292
|
-
Use the project-knowledge skill to audit docs/checkout.md against the checkout implementation.
|
|
293
|
-
Prioritize real mismatches; record each as a separate open gap.
|
|
294
|
-
```
|
|
295
|
-
|
|
296
|
-
```text
|
|
297
|
-
Use the project-knowledge skill to re-check the gap "cancelled order still reserves stock".
|
|
298
|
-
Read the call path and relevant tests, write the result into the gap's Recheck
|
|
299
|
-
section, and leave the decision to me.
|
|
300
|
-
```
|
|
301
|
-
|
|
302
|
-
```text
|
|
303
|
-
Use the spec-change skill to plan the accepted gap "reservation-release".
|
|
304
|
-
Include affected modules, concurrency checks and acceptance criteria. Plan only.
|
|
305
|
-
```
|
|
306
|
-
|
|
307
|
-
```text
|
|
308
|
-
Use the spec-change skill. I edited the spec on this branch; the diff against main
|
|
309
|
-
is the change request. Ask your questions first, then implement it and show me
|
|
310
|
-
which statement is covered by which check.
|
|
311
|
-
```
|
|
312
|
-
|
|
313
|
-
### Any agent with repository access
|
|
314
|
-
|
|
315
|
-
Clone this repository, then ask the agent to read the chosen `skills/<name>/SKILL.md` and follow it in your target project. Keep that skill's directory intact so its references and scripts resolve. Use your host's documented installation mechanism if it supports skills. Hosts other than Codex and Claude Code have not been integration-tested, and the format change described in [VALIDATION.md](VALIDATION.md) has not yet been tested with an agent on any host.
|
|
69
|
+
| Search | Copy for AI |
|
|
70
|
+
| --- | --- |
|
|
71
|
+
|  |  |
|
|
72
|
+
| **Recent changes** | **Gap queue** |
|
|
73
|
+
|  |  |
|
|
316
74
|
|
|
317
|
-
|
|
75
|
+
[The viewer](docs/viewer.md) describes every screen, and how to show the spec on a development server for the rest of the team.
|
|
318
76
|
|
|
319
|
-
|
|
77
|
+
## The two skills
|
|
320
78
|
|
|
321
|
-
|
|
322
|
-
|
|
323
|
-
|
|
324
|
-
|
|
325
|
-
```
|
|
79
|
+
| Skill | What it does |
|
|
80
|
+
| --- | --- |
|
|
81
|
+
| [project-knowledge](skills/project-knowledge/SKILL.md) | Writes and maintains the spec and the gap queue. Audits written requirements against the code, answers one question, re-checks one gap, follows Git history. It never changes application code. |
|
|
82
|
+
| [spec-change](skills/spec-change/SKILL.md) (experimental) | Changes the product starting from the spec: you edit the spec on a branch, the agent asks its questions, then implements the change and checks each changed statement against the code. |
|
|
326
83
|
|
|
327
|
-
|
|
84
|
+
## Commands
|
|
328
85
|
|
|
329
86
|
```sh
|
|
330
|
-
|
|
331
|
-
|
|
332
|
-
|
|
333
|
-
|
|
334
|
-
|
|
335
|
-
To use Obsidian, choose **Open folder as vault** and select `examples/parcel-desk/knowledge/parcel-desk`. Open `00-index`, then **Graph view: Open graph view** from the command palette (Cmd/Ctrl+G). In graph settings, **Existing files only** hides unresolved source links outside the vault. Pages cluster around their area because each page links to it; run pages carry no links, so they do not pull the clusters together. To see the spec alone, put `-path:gaps -path:plans -path:runs` in the graph's search filter, and add a color group per folder (`path:areas`, `path:notes`, `path:gaps`) under **Groups**. **Open local graph** shows only the neighbours of the page you are reading. Gap properties are searchable, for example `[decision:open]` or `[kind:verification-gap]`. See [Obsidian's graph guide](https://help.obsidian.md/plugins/graph).
|
|
336
|
-
|
|
337
|
-
Source links point outside the vault into the repository. Some hosts do not open these paths; the note's `sources` property gives the repository-relative path for your editor. All example application data is invented.
|
|
338
|
-
|
|
339
|
-
## Keep knowledge current
|
|
340
|
-
|
|
341
|
-
```text
|
|
342
|
-
Use the project-knowledge skill to sync: review all integrated changes since the last
|
|
343
|
-
reviewed checkpoint, update the affected spec notes, and revisit gaps whose
|
|
344
|
-
sources changed.
|
|
87
|
+
npx project-spec serve # read the spec in the browser
|
|
88
|
+
npx project-spec coverage # what the code has that no page mentions yet
|
|
89
|
+
npx project-spec build --out FILE # the viewer as one file, to show on a server
|
|
90
|
+
npx project-spec status # where the skills are installed and whether they are current
|
|
91
|
+
npx project-spec update # refresh the installed skills
|
|
345
92
|
```
|
|
346
93
|
|
|
347
|
-
|
|
348
|
-
|
|
349
|
-
```text
|
|
350
|
-
Ask project-knowledge to explore permissions and deepen the access-control notes.
|
|
351
|
-
Ask project-knowledge to work the gaps: re-verify open ones against the current code
|
|
352
|
-
and list which are waiting for my decision.
|
|
353
|
-
Ask project-knowledge to check links and source freshness.
|
|
354
|
-
```
|
|
355
|
-
|
|
356
|
-
The agent researches and writes the claims. The Python helpers validate structure, track source fingerprints and render views; running a helper alone does not understand your code. A scan identifies candidate changes, and fingerprints are accepted and the Git checkpoint advanced only after review. See the [sync workflow](skills/project-knowledge/references/sync.md). If part of the range cannot be accepted yet, for example because another contributor has uncommitted edits to a file, mark it `deferred`: the rest is accepted, the checkpoint stays where it is and the helper exits with status 3 (not 0, and not 2, which is a usage error).
|
|
357
|
-
|
|
358
|
-
If `check` fails on a vault written before the spec/gap split, follow the [migration guide](skills/project-knowledge/references/migrate.md). The same guide has the regroup pass for a vault whose feature pages lack the sections above, or whose rules were spread over separate table pages per kind.
|
|
94
|
+
## Read more
|
|
359
95
|
|
|
360
|
-
|
|
361
|
-
|
|
362
|
-
|
|
363
|
-
|
|
364
|
-
|
|
365
|
-
|
|
366
|
-
|
|
367
|
-
|
|
368
|
-
|
|
369
|
-
|
|
370
|
-
|
|
371
|
-
|
|
372
|
-
|
|
373
|
-
|
|
374
|
-
|
|
375
|
-
|
|
376
|
-
|
|
377
|
-
|
|
378
|
-
## What the files mean
|
|
379
|
-
|
|
380
|
-
```text
|
|
381
|
-
knowledge/<project>/
|
|
382
|
-
00-index.md start here
|
|
383
|
-
areas/ maps of related capabilities (spec)
|
|
384
|
-
notes/ one page per feature, plus reference lists (spec)
|
|
385
|
-
gaps/ one question per page (gap)
|
|
386
|
-
plans/ one plan per accepted gap (gap)
|
|
387
|
-
runs/ review history and evidence limits
|
|
388
|
-
.knowledge/ sources.json (reviewed fingerprints), review.json (reviewed Git checkpoint)
|
|
389
|
-
```
|
|
390
|
-
|
|
391
|
-
Spec pages never link to gaps; a gap links to the spec notes it is about. A gap that needs attention is a reason to look, not a defect list: it can mean unverified behavior, an unmet requirement or an undecided proposal. The [format contract](skills/project-knowledge/references/format.md) explains the page types, properties and evidence model. Helpers support this format; they are not a general Obsidian vault importer.
|
|
392
|
-
|
|
393
|
-
## Contributing and verification
|
|
394
|
-
|
|
395
|
-
See [CONTRIBUTING.md](CONTRIBUTING.md) for the checks, skill boundaries and expectations for examples. [VALIDATION.md](VALIDATION.md) records the actual release checks and limitations. Small, evidence-backed improvements are welcome, especially reproducible cases where a skill confuses intended behavior, implemented behavior and runtime evidence.
|
|
396
|
-
|
|
397
|
-
The shipped skills and examples are original work, licensed under [MIT](LICENSE). This is an independent project; Obsidian and the agent hosts are not its sponsors. No third-party skill collection is bundled.
|
|
96
|
+
| Page | What is in it |
|
|
97
|
+
| --- | --- |
|
|
98
|
+
| [Install and update](docs/install.md) | npm, the Claude Code plugin, Codex, a manual copy, keeping copies current. |
|
|
99
|
+
| [The viewer](docs/viewer.md) | Every screen, a short command to open it, and the spec on a server. |
|
|
100
|
+
| [What the spec contains](docs/spec.md) | The sections of a feature page, big features and several apps, how deep the first map goes, the coverage report, the files in the vault. |
|
|
101
|
+
| [Working with the skills](docs/workflows.md) | Example prompts, the example project, keeping the spec current, deciding gaps, two people updating the vault. |
|
|
102
|
+
| [Parcel Desk](examples/parcel-desk/README.md) | A small fictional project with a ready-made vault to try the viewer on. |
|
|
103
|
+
| [VALIDATION.md](VALIDATION.md) | What was actually checked for each release, and the limits. |
|
|
104
|
+
| [CONTRIBUTING.md](CONTRIBUTING.md) | Checks, skill boundaries and how releases are made. |
|
|
105
|
+
|
|
106
|
+
## What it does not do
|
|
107
|
+
|
|
108
|
+
- The agent writes the claims. The helpers check structure and track which files changed; a helper alone does not understand your code.
|
|
109
|
+
- The spec says what the code does. It does not prove that the deployed application works.
|
|
110
|
+
- Nothing runs by itself: no schedule, no hooks, no commits or pushes. You share the Markdown through your normal Git workflow.
|
|
111
|
+
- No MCP server, cloud service, paid API or Obsidian plugin is needed.
|
|
112
|
+
|
|
113
|
+
The skills and examples are original work under the [MIT license](LICENSE). This is an independent project; Obsidian and the agent hosts are not its sponsors.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "project-spec",
|
|
3
|
-
"version": "0.9.
|
|
3
|
+
"version": "0.9.2",
|
|
4
4
|
"description": "Agent skills that read a repository and keep a spec people can read: one page per feature, every business rule numbered. Local viewer and one command to install and update the skills.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"agent-skills",
|
|
@@ -38,7 +38,7 @@ The full property list, section layout and example are in [gaps.md](references/g
|
|
|
38
38
|
|
|
39
39
|
Natural-language requests are fine; these are modes, not a required CLI.
|
|
40
40
|
|
|
41
|
-
- **map** (a new vault): take the inventory of what the product has, then go through its features one at a time and finish each before starting the next ([Research before writing](#research-before-writing)). A first map is measured by how many features are finished, not by how many pages exist: thirty finished features and a list of forty not started is a better first map than seventy thin pages. A pass that runs out of time
|
|
41
|
+
- **map** (a new vault): take the inventory of what the product has, then go through its features one at a time and finish each before starting the next ([Research before writing](#research-before-writing)). A first map is measured by how many features are finished, not by how many pages exist: thirty finished features and a list of forty not started is a better first map than seventy thin pages. The inventory is kept in a file in the vault ([The inventory file](#the-inventory-file)), which is also where a pass that was interrupted continues. A pass that runs out of time leaves that file saying which features are finished, which one is in progress and which were not started, and never calls itself full.
|
|
42
42
|
- **update**: revisit claims affected since the previous run, preserve manually written knowledge, add discoveries, and fill in what the pages you touch are missing (see [Leave each page better](#leave-each-page-better)).
|
|
43
43
|
- **sync**: reconcile changes from all contributors since the last reviewed Git checkpoint. Read [the sync workflow](references/sync.md); a sync with work you cannot accept yet (for example another contributor's uncommitted files) uses `deferred` and ends as a partial finish with exit status 3 and the checkpoint unmoved.
|
|
44
44
|
- **merge**: reconcile two contributors' vault updates from their common Git base. Read [the merge workflow](references/merge.md).
|
|
@@ -58,11 +58,21 @@ Write vault content in English unless the user asks for another language, whatev
|
|
|
58
58
|
|
|
59
59
|
1. Read the repository's instructions and any task coordination they require. Preserve existing edits. Record the exact revision and whether you read uncommitted files. Application source is read-only: this skill writes only inside the vault.
|
|
60
60
|
2. Inspect manifests, entrypoints, routes, schema and migrations, services and tests. Skip dependencies, build output, credential files, raw logs and customer data. Never use the vault itself as evidence about the application.
|
|
61
|
-
3. **Take the inventory before writing a page.** List what the product has from the places that register it, every item and not a sample: the pages or screens of every client (web, mobile, admin), the API procedures or endpoints, the jobs, the emails. Count them. Run `coverage` (below) for the size of each folder. Group the items into features and write that list
|
|
61
|
+
3. **Take the inventory before writing a page.** List what the product has from the places that register it, every item and not a sample: the pages or screens of every client (web, mobile, admin), the API procedures or endpoints, the jobs, the emails. Count them. Run `coverage` (below) for the size of each folder. Group the items into features and write that list into [the inventory file](#the-inventory-file) with each feature's size: its entry points, its folders, its lines. This list is the plan and the checklist of the whole map. A directory name establishes neither a feature nor a behavior, so check a group against what its entry points do.
|
|
62
62
|
4. **Split a big feature before writing it.** One page holds what a person reads in one sitting: about twenty rules. A feature with more than about eight entry points, more than about 2,000 lines of its own code, or several kinds of user or flow (direct, group and support chats) will not fit, and squeezing it into one page is how fifty rules become thirteen. Give it a feature note and one note per part ("A feature with parts" under [Write the spec](#write-the-spec)).
|
|
63
63
|
5. **Go deep before going wide.** Take one feature and finish it before starting the next. Read every one of its entry points on every client and follow each to the file that decides the behavior (the schema, the service, the policy, the component). Read its rules off the code: a `max(60)` in a schema, a `disabled={items.length === 0}` on a button, a `CHECK` constraint, a default value, a permission check, every `throw` and every refusal. Read the words a person sees too, the labels, the error messages and what an empty list says, and quote them. For the things the code registers in one place (the queue and cron registrations, the route table, the email templates, the roles, the flags), enumerate from that place, every item.
|
|
64
64
|
6. **Read each client.** When the product has more than one client, read the feature in each of them. Two clients calling the same server procedure does not make them the same: one may lack a screen, a check or a confirmation. Write what differs on the feature's page ([Write the spec](#write-the-spec)); a difference that looks unintended is also a gap.
|
|
65
|
-
7. Track what was read, merely discovered, excluded or changing in
|
|
65
|
+
7. Track what was read, merely discovered, excluded or changing in the inventory file, as you go and not from memory at the end. Discovery is not review, and a note count is not completeness. When the session will not cover everything, stop at the end of a feature, not in the middle of all of them.
|
|
66
|
+
|
|
67
|
+
### The inventory file
|
|
68
|
+
|
|
69
|
+
`$VAULT/.knowledge/inventory.md` is the checklist of the whole map and the place a later session continues from ([format](references/format.md#the-inventory-file)). No helper writes or reads it: keeping it true is your job, and it is what stops a large map from losing a feature or being started again from nothing.
|
|
70
|
+
|
|
71
|
+
- **First pass: the list.** Start from what the repository is made of: every app and package (workspaces, manifests, folders with their own entry file). For each one list its entry points from the place that registers them, then group them into features. A feature gets a heading with its state (`not started`, `in progress`, `finished`), its folders, and one checkbox per entry point. Something that is not part of the product (a developer tool, a component gallery, generated code) goes under "Left out" with the reason, so nobody takes it for forgotten. Write the whole file before the first page.
|
|
72
|
+
- **Second pass: one feature at a time.** Take the first feature that is not finished. Set it to `in progress` before reading it, tick an entry point once you have followed it to the code that decides the behavior, and set the feature to `finished` with the paths of its pages when [it is finished](#when-a-feature-is-finished). While a feature is `in progress` its pages are `partial`. Save the file after every feature and whenever you stop: a session can end at any moment, and what is not in the file is lost.
|
|
73
|
+
- **A new find goes into the list at once.** An entry point, a package or a whole feature the list does not have is added the moment you see it, unticked or `not started`, even in the middle of another feature. Do not keep it in your head, and do not leave your feature to read it out of turn.
|
|
74
|
+
- **Last pass: check the list against the code.** When no feature is `not started` or `in progress`, or when the session is about to end: list the entry points again from the places that register them and compare with the file; run `coverage` for the whole repository and look at the folders at the top of the report, each of which is a feature missing from the list, a part of one, or something for "Left out"; confirm that no `finished` feature has an unticked entry point or a `partial` page. Whatever this turns up goes into the list and is worked like the rest.
|
|
75
|
+
- **Continuing.** When the file exists, read it before anything else in **map**, **explore** and **update**. Go on with the feature that is `in progress`, its unticked entry points first, then with the first `not started` one. Do not retake the inventory from nothing and do not rewrite the pages of finished features. If the code moved since the revision the file names, add the entry points that are new and remove the ones that are gone; files that changed under existing pages are the business of **sync**. A vault that has no such file (it was made by an earlier version) gets one the first time you map or explore it: take the inventory, and give a feature that already has pages `in progress` until you have checked it as above.
|
|
66
76
|
|
|
67
77
|
### When a feature is finished
|
|
68
78
|
|
|
@@ -149,10 +159,11 @@ Before handing over, read what you wrote as the person who will use it, not as i
|
|
|
149
159
|
- Is each rule one numbered row a person could quote, with its value, and did every rule that was already there keep its number?
|
|
150
160
|
- Could someone answer "how long may a name be", "when is this button disabled" or "which jobs run at night" from the page without opening the code? If the answer is in the code you read but not on the page, add it.
|
|
151
161
|
- Did `coverage --path` for the feature's folders end with only things the spec leaves out on purpose? Is every page whose feature is not finished marked `partial`, with what is left?
|
|
162
|
+
- Does the inventory file say what is true now: each feature you finished with its pages, the one you stopped in as `in progress` with what is left, and everything you came across on the way listed?
|
|
152
163
|
- Does a feature with more than about twenty rules have parts, and does a product with several clients say on each feature page where they differ?
|
|
153
164
|
- Is everything about one feature on its own page, or does the reader have to collect it from several?
|
|
154
165
|
- Would a person who never opens the code understand every sentence? Would the page survive a file being renamed?
|
|
155
166
|
- Does the area page only map, with its missing lists named?
|
|
156
167
|
- Is every doubt a gap about the product, and nothing in the queue a to-do of the vault itself?
|
|
157
168
|
|
|
158
|
-
Then validate and, when tools allow, open the viewer. Report real counts: how many features of the inventory are finished,
|
|
169
|
+
Then validate and, when tools allow, open the viewer. Report real counts: how many features of the inventory file are finished, in progress and not started, what is under "Left out", the first lines of the `coverage` report for the whole repository, the checks you ran and how to open the result. Do not describe a map as full or complete while the inventory has features that are not finished. Keep structural validation, application tests and GUI checks separate. Committing and pushing are left to the user.
|
|
@@ -247,8 +247,8 @@
|
|
|
247
247
|
background: var(--paper);
|
|
248
248
|
}
|
|
249
249
|
.icon-btn {
|
|
250
|
-
width:
|
|
251
|
-
height:
|
|
250
|
+
width: 36px;
|
|
251
|
+
height: 36px;
|
|
252
252
|
display: grid;
|
|
253
253
|
place-items: center;
|
|
254
254
|
border: 1px solid var(--line-strong);
|
|
@@ -310,11 +310,11 @@
|
|
|
310
310
|
font-weight: 600;
|
|
311
311
|
}
|
|
312
312
|
.btn {
|
|
313
|
-
height:
|
|
313
|
+
height: 36px;
|
|
314
314
|
display: inline-flex;
|
|
315
315
|
align-items: center;
|
|
316
316
|
gap: 8px;
|
|
317
|
-
padding: 0
|
|
317
|
+
padding: 0 14px;
|
|
318
318
|
border: 1px solid var(--line-strong);
|
|
319
319
|
border-radius: 999px;
|
|
320
320
|
background: var(--paper);
|
|
@@ -330,9 +330,8 @@
|
|
|
330
330
|
background: var(--accent);
|
|
331
331
|
}
|
|
332
332
|
.btn.large {
|
|
333
|
-
height:
|
|
334
|
-
padding: 0
|
|
335
|
-
font-size: 15px;
|
|
333
|
+
height: 40px;
|
|
334
|
+
padding: 0 18px;
|
|
336
335
|
}
|
|
337
336
|
.pillrow {
|
|
338
337
|
display: flex;
|
|
@@ -340,15 +339,15 @@
|
|
|
340
339
|
gap: 8px;
|
|
341
340
|
}
|
|
342
341
|
.pill {
|
|
343
|
-
height:
|
|
342
|
+
height: 34px;
|
|
344
343
|
display: inline-flex;
|
|
345
344
|
align-items: center;
|
|
346
|
-
gap:
|
|
347
|
-
padding: 0
|
|
345
|
+
gap: 7px;
|
|
346
|
+
padding: 0 13px;
|
|
348
347
|
border: 1px solid var(--line-strong);
|
|
349
348
|
border-radius: 999px;
|
|
350
349
|
background: var(--paper);
|
|
351
|
-
font: 600
|
|
350
|
+
font: 600 13px/1 var(--sans);
|
|
352
351
|
}
|
|
353
352
|
.pill[aria-pressed="true"] {
|
|
354
353
|
border-color: var(--ink);
|
|
@@ -360,12 +359,25 @@
|
|
|
360
359
|
opacity: 0.75;
|
|
361
360
|
}
|
|
362
361
|
select {
|
|
363
|
-
height:
|
|
364
|
-
padding: 0
|
|
362
|
+
height: 34px;
|
|
363
|
+
padding: 0 12px;
|
|
365
364
|
border: 1px solid var(--line-strong);
|
|
366
365
|
border-radius: 999px;
|
|
367
366
|
background: var(--paper);
|
|
368
|
-
font-size:
|
|
367
|
+
font-size: 13px;
|
|
368
|
+
}
|
|
369
|
+
/* A finger needs more room than a mouse pointer. */
|
|
370
|
+
@media (pointer: coarse) {
|
|
371
|
+
.btn,
|
|
372
|
+
.pill,
|
|
373
|
+
select {
|
|
374
|
+
height: 44px;
|
|
375
|
+
}
|
|
376
|
+
.icon-btn,
|
|
377
|
+
.xbtn {
|
|
378
|
+
width: 44px;
|
|
379
|
+
height: 44px;
|
|
380
|
+
}
|
|
369
381
|
}
|
|
370
382
|
|
|
371
383
|
/* Page */
|
|
@@ -421,6 +433,48 @@
|
|
|
421
433
|
gap: 24px;
|
|
422
434
|
max-width: 860px;
|
|
423
435
|
}
|
|
436
|
+
.stack.wide {
|
|
437
|
+
max-width: 1100px;
|
|
438
|
+
}
|
|
439
|
+
.area-grid {
|
|
440
|
+
display: grid;
|
|
441
|
+
grid-template-columns: repeat(auto-fill, minmax(300px, 1fr));
|
|
442
|
+
gap: 16px;
|
|
443
|
+
}
|
|
444
|
+
.area-card h2 button {
|
|
445
|
+
border: 0;
|
|
446
|
+
padding: 0;
|
|
447
|
+
background: none;
|
|
448
|
+
font: inherit;
|
|
449
|
+
text-align: left;
|
|
450
|
+
}
|
|
451
|
+
.area-card h2 button:hover {
|
|
452
|
+
text-decoration: underline;
|
|
453
|
+
}
|
|
454
|
+
.area-card .names {
|
|
455
|
+
display: flex;
|
|
456
|
+
flex-direction: column;
|
|
457
|
+
gap: 6px;
|
|
458
|
+
margin-top: 4px;
|
|
459
|
+
}
|
|
460
|
+
.area-card .names button {
|
|
461
|
+
border: 0;
|
|
462
|
+
padding: 0;
|
|
463
|
+
background: none;
|
|
464
|
+
font-size: 14px;
|
|
465
|
+
text-align: left;
|
|
466
|
+
overflow: hidden;
|
|
467
|
+
text-overflow: ellipsis;
|
|
468
|
+
white-space: nowrap;
|
|
469
|
+
}
|
|
470
|
+
.area-card .names button:hover {
|
|
471
|
+
color: var(--accent-ink);
|
|
472
|
+
text-decoration: underline;
|
|
473
|
+
}
|
|
474
|
+
.area-card .names button.more {
|
|
475
|
+
color: var(--muted);
|
|
476
|
+
font-size: 13px;
|
|
477
|
+
}
|
|
424
478
|
.page {
|
|
425
479
|
display: flex;
|
|
426
480
|
flex-wrap: wrap;
|
|
@@ -490,20 +544,20 @@
|
|
|
490
544
|
.badge {
|
|
491
545
|
display: inline-flex;
|
|
492
546
|
align-items: center;
|
|
493
|
-
gap:
|
|
494
|
-
min-height:
|
|
495
|
-
padding: 0
|
|
547
|
+
gap: 6px;
|
|
548
|
+
min-height: 24px;
|
|
549
|
+
padding: 0 10px;
|
|
496
550
|
border-radius: 999px;
|
|
497
551
|
background: var(--soft);
|
|
498
552
|
color: var(--ink);
|
|
499
|
-
font-size:
|
|
553
|
+
font-size: 12px;
|
|
500
554
|
font-weight: 600;
|
|
501
555
|
white-space: nowrap;
|
|
502
556
|
}
|
|
503
557
|
.badge::before {
|
|
504
558
|
content: "";
|
|
505
|
-
width:
|
|
506
|
-
height:
|
|
559
|
+
width: 6px;
|
|
560
|
+
height: 6px;
|
|
507
561
|
border-radius: 999px;
|
|
508
562
|
background: var(--subtle);
|
|
509
563
|
}
|
|
@@ -546,10 +600,10 @@
|
|
|
546
600
|
gap: 8px;
|
|
547
601
|
}
|
|
548
602
|
.chip {
|
|
549
|
-
min-height:
|
|
603
|
+
min-height: 32px;
|
|
550
604
|
display: inline-flex;
|
|
551
605
|
align-items: center;
|
|
552
|
-
padding:
|
|
606
|
+
padding: 4px 13px;
|
|
553
607
|
border: 1px solid var(--line);
|
|
554
608
|
border-radius: 999px;
|
|
555
609
|
background: var(--paper);
|
|
@@ -897,8 +951,8 @@
|
|
|
897
951
|
}
|
|
898
952
|
.xbtn {
|
|
899
953
|
flex: none;
|
|
900
|
-
width:
|
|
901
|
-
height:
|
|
954
|
+
width: 36px;
|
|
955
|
+
height: 36px;
|
|
902
956
|
display: grid;
|
|
903
957
|
place-items: center;
|
|
904
958
|
border: 0;
|
|
@@ -1281,7 +1335,7 @@
|
|
|
1281
1335
|
min-height: 32px;
|
|
1282
1336
|
}
|
|
1283
1337
|
.copy-card .btn {
|
|
1284
|
-
height:
|
|
1338
|
+
height: 36px;
|
|
1285
1339
|
}
|
|
1286
1340
|
@media (max-width: 820px) {
|
|
1287
1341
|
.copy-card {
|
|
@@ -2554,18 +2608,38 @@
|
|
|
2554
2608
|
};
|
|
2555
2609
|
|
|
2556
2610
|
// --- Views ---------------------------------------------------------------------------------------
|
|
2611
|
+
// The overview is a map of the areas, not every feature of every area: a card says what the area
|
|
2612
|
+
// covers, how much is in it and names a few features; the area's own page has the full list.
|
|
2613
|
+
const HOME_NAMES = 5;
|
|
2614
|
+
function areaCard(a) {
|
|
2615
|
+
const card = el("section", null, "card pad area-card"),
|
|
2616
|
+
h = el("h2", null, "h2"),
|
|
2617
|
+
features = featuresOf(a),
|
|
2618
|
+
count = nodes.filter((n) => isFeature(n) && primaryArea(n) === a.id).length,
|
|
2619
|
+
open = nodes.filter((g) => isGap(g) && inArea(g, a.id) && ["needs-recheck", "needs-decision"].includes(stateOf(g))).length;
|
|
2620
|
+
h.append(button(a.title, null, () => openNode(a)));
|
|
2621
|
+
card.append(h);
|
|
2622
|
+
if (str(a.summary).trim()) card.append(el("p", a.summary, "muted"));
|
|
2623
|
+
card.append(el("p", [plural(count, "page"), open && plural(open, "open question")].filter(Boolean).join(" · "), "muted small"));
|
|
2624
|
+
const names = el("div", null, "names");
|
|
2625
|
+
features.slice(0, HOME_NAMES).forEach((f) => {
|
|
2626
|
+
const b = button(f.title, null, () => openNode(f));
|
|
2627
|
+
b.title = f.title;
|
|
2628
|
+
names.append(b);
|
|
2629
|
+
});
|
|
2630
|
+
if (features.length > HOME_NAMES)
|
|
2631
|
+
names.append(button("All " + features.length + " features", "more", () => openNode(a)));
|
|
2632
|
+
if (features.length) card.append(names);
|
|
2633
|
+
return card;
|
|
2634
|
+
}
|
|
2557
2635
|
function viewHome(view) {
|
|
2558
|
-
const box = el("div", null, "stack");
|
|
2636
|
+
const box = el("div", null, "stack wide");
|
|
2559
2637
|
box.append(header("Overview", projectTitle, "What the product does today, area by area."));
|
|
2560
|
-
areas.
|
|
2561
|
-
const
|
|
2562
|
-
|
|
2563
|
-
|
|
2564
|
-
|
|
2565
|
-
if (str(a.summary).trim()) section.append(el("p", a.summary, "muted"));
|
|
2566
|
-
section.append(featureList(featuresOf(a)));
|
|
2567
|
-
box.append(section);
|
|
2568
|
-
});
|
|
2638
|
+
if (areas.length) {
|
|
2639
|
+
const grid = el("div", null, "area-grid");
|
|
2640
|
+
areas.forEach((a) => grid.append(areaCard(a)));
|
|
2641
|
+
box.append(grid);
|
|
2642
|
+
}
|
|
2569
2643
|
const loose = looseFeatures();
|
|
2570
2644
|
if (loose.length) {
|
|
2571
2645
|
const section = el("section");
|
|
@@ -2618,6 +2692,22 @@
|
|
|
2618
2692
|
box.append(list);
|
|
2619
2693
|
}
|
|
2620
2694
|
}
|
|
2695
|
+
// A gap is a question about something: the features it links to, then its areas.
|
|
2696
|
+
if (isGap(n)) {
|
|
2697
|
+
const about = neighbours(n, "spec"),
|
|
2698
|
+
own = (n.areas || []).map((id) => byId.get(id)).filter((a) => a && a.type === "area"),
|
|
2699
|
+
pages = [...new Set([...about.filter((r) => r.type === "note"), ...about.filter((r) => r.type !== "note"), ...own])];
|
|
2700
|
+
if (pages.length) {
|
|
2701
|
+
const list = el("div", null, "recent");
|
|
2702
|
+
list.append(el("div", "This gap is about", "mono-label"));
|
|
2703
|
+
pages.forEach((r) => {
|
|
2704
|
+
const b = button(r.title, null, () => openNode(r));
|
|
2705
|
+
if (r.type !== "note") b.append(el("span", " · area", "muted"));
|
|
2706
|
+
list.append(b);
|
|
2707
|
+
});
|
|
2708
|
+
box.append(list);
|
|
2709
|
+
}
|
|
2710
|
+
}
|
|
2621
2711
|
const others = recent.filter((id) => id !== n.id).slice(0, 5);
|
|
2622
2712
|
if (others.length) {
|
|
2623
2713
|
const list = el("div", null, "recent");
|
|
@@ -2660,13 +2750,8 @@
|
|
|
2660
2750
|
|
|
2661
2751
|
if (isGap(n)) {
|
|
2662
2752
|
main.append(gapHeader(n));
|
|
2663
|
-
|
|
2664
|
-
|
|
2665
|
-
if (refs.length) {
|
|
2666
|
-
const chips = el("div", null, "chips");
|
|
2667
|
-
refs.forEach((r) => chips.append(button(r.title, "chip", () => openNode(r))));
|
|
2668
|
-
main.append(el("div", "Refers to", "mono-label"), chips);
|
|
2669
|
-
}
|
|
2753
|
+
// The pages the gap is about are listed beside the text ("This gap is about"), as on spec pages.
|
|
2754
|
+
const plan = planOf(n);
|
|
2670
2755
|
if (plan)
|
|
2671
2756
|
main.append(
|
|
2672
2757
|
linkBlock("Plan", [
|
|
@@ -3647,15 +3732,33 @@
|
|
|
3647
3732
|
function applyBox() {
|
|
3648
3733
|
graph.setAttribute("viewBox", `${box.x} ${box.y} ${box.w} ${box.h}`);
|
|
3649
3734
|
}
|
|
3650
|
-
|
|
3651
|
-
|
|
3652
|
-
|
|
3653
|
-
|
|
3654
|
-
|
|
3735
|
+
// f below 1 zooms in. (cx, cy) is the point of the map that stays where it is, as a share of the
|
|
3736
|
+
// view: the middle for the buttons, the pointer for the wheel. Zoom stops at 8x in and 4x out.
|
|
3737
|
+
function zoom(f, cx = 0.5, cy = 0.5) {
|
|
3738
|
+
const w = Math.min(Math.max(box.w * f, initialBox.w / 8), initialBox.w * 4),
|
|
3739
|
+
k = w / box.w,
|
|
3740
|
+
h = box.h * k;
|
|
3741
|
+
box.x += (box.w - w) * cx;
|
|
3742
|
+
box.y += (box.h - h) * cy;
|
|
3655
3743
|
box.w = w;
|
|
3656
3744
|
box.h = h;
|
|
3657
3745
|
applyBox();
|
|
3658
3746
|
}
|
|
3747
|
+
graph.addEventListener(
|
|
3748
|
+
"wheel",
|
|
3749
|
+
(e) => {
|
|
3750
|
+
if (!e.deltaY) return;
|
|
3751
|
+
e.preventDefault(); // the map takes the wheel; the page beside it still scrolls
|
|
3752
|
+
const rect = graph.getBoundingClientRect(),
|
|
3753
|
+
share = (v, size) => (size ? Math.min(Math.max(v / size, 0), 1) : 0.5);
|
|
3754
|
+
zoom(
|
|
3755
|
+
Math.exp(Math.max(-60, Math.min(60, e.deltaY)) * 0.004),
|
|
3756
|
+
share(e.clientX - rect.left, rect.width),
|
|
3757
|
+
share(e.clientY - rect.top, rect.height),
|
|
3758
|
+
);
|
|
3759
|
+
},
|
|
3760
|
+
{ passive: false },
|
|
3761
|
+
);
|
|
3659
3762
|
$("#zoom-in").addEventListener("click", () => zoom(0.8));
|
|
3660
3763
|
$("#zoom-out").addEventListener("click", () => zoom(1.25));
|
|
3661
3764
|
$("#reset").addEventListener("click", () => {
|
|
@@ -14,7 +14,8 @@ knowledge/<project>/
|
|
|
14
14
|
gaps/ one question per page (gap)
|
|
15
15
|
plans/ one plan per accepted gap (gap)
|
|
16
16
|
runs/ review history and evidence limits
|
|
17
|
-
.knowledge/ sources.json (reviewed fingerprints), review.json (reviewed Git checkpoint)
|
|
17
|
+
.knowledge/ sources.json (reviewed fingerprints), review.json (reviewed Git checkpoint),
|
|
18
|
+
inventory.md (the checklist of the map)
|
|
18
19
|
```
|
|
19
20
|
|
|
20
21
|
Nothing in the vault is generated for reading: every file is a page someone wrote or the reviewed state under `.knowledge/`. The local reports of a sync scan (`sync.html`, `.knowledge/sync-plan.json`, `.knowledge/sync-status.md`) are ignored by Git and are not part of the vault's content. The viewer shows the spec and the gap queue from the pages themselves.
|
|
@@ -165,6 +166,44 @@ The validator enforces these body rules:
|
|
|
165
166
|
5. A gap has six `##` sections with exactly these headings, each once: `Current behavior`, `Gap`, `Evidence`, `Recheck`, `Discussion`, `Decision`. Headings inside code fences do not count.
|
|
166
167
|
6. When `decision` is not `open`, `Decision` needs text; when `recheck` is not `not-checked`, `Recheck` needs text.
|
|
167
168
|
|
|
169
|
+
## The inventory file
|
|
170
|
+
|
|
171
|
+
`.knowledge/inventory.md` is the checklist of a map: what the product has, and how far the spec has got with it. The agent writes it before the first page and keeps it true afterwards ([the rules](../SKILL.md#the-inventory-file)); no helper reads it, and like everything under `.knowledge/` it is not a page of the vault. It is committed with the vault, which is how a second session, or a second person, continues where the first one stopped.
|
|
172
|
+
|
|
173
|
+
```markdown
|
|
174
|
+
# Inventory
|
|
175
|
+
|
|
176
|
+
Taken at `4f2a9c1` on 2026-11-18. Apps and packages: web-app, mobile-app, packages/api, packages/jobs.
|
|
177
|
+
|
|
178
|
+
## Chats: in progress
|
|
179
|
+
|
|
180
|
+
Folders: web-app/src/features/messages, mobile-app/src/features/messages, packages/api/src/chat
|
|
181
|
+
Pages: notes/chats, notes/chats-group
|
|
182
|
+
Left: the support chat screens, the mobile app
|
|
183
|
+
|
|
184
|
+
- [x] web /messages
|
|
185
|
+
- [x] web /messages/[id]
|
|
186
|
+
- [ ] mobile ChatScreen
|
|
187
|
+
- [x] api chat.send
|
|
188
|
+
- [ ] job chat-digest
|
|
189
|
+
|
|
190
|
+
## Reviews: not started
|
|
191
|
+
|
|
192
|
+
Folders: web-app/src/features/reviews
|
|
193
|
+
|
|
194
|
+
- [ ] web /products/[id]/reviews
|
|
195
|
+
- [ ] api review.create
|
|
196
|
+
|
|
197
|
+
## Left out
|
|
198
|
+
|
|
199
|
+
- packages/storybook: a component gallery for developers, no behavior of the product
|
|
200
|
+
```
|
|
201
|
+
|
|
202
|
+
- A feature's heading is its name and one of three states: `not started`, `in progress`, `finished`. A feature with parts is still one heading; its parts are among its pages.
|
|
203
|
+
- One checkbox per entry point: the client or kind (`web`, `mobile`, `admin`, `api`, `job`, `email`) and the name the code registers it under. A box is ticked when the entry point was followed to the code that decides its behavior, not when it was seen.
|
|
204
|
+
- `Pages` names the feature's pages by path. `Left` says in words what is not read yet, and is the same thing the `partial` page says in its last line. A `finished` feature has every box ticked and no `Left` line.
|
|
205
|
+
- "Left out" holds what was looked at and is not part of the product, each with its reason.
|
|
206
|
+
|
|
168
207
|
## Helper
|
|
169
208
|
|
|
170
209
|
Four scripts in `$SKILL_DIR/scripts/`; see [SKILL.md](../SKILL.md) for the variables.
|