project-spec 0.9.1 → 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/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "project-spec",
3
- "version": "0.9.1",
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 says on the run page which features are finished, which are partial and which were not started, and never calls itself full.
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 on the run page with each feature's size: its entry points, its folders, its lines. This list is the plan and the ledger of the whole map. A directory name establishes neither a feature nor a behavior, so check a group against what its entry points do.
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 each area. 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.
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, partial and not started, 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.
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.
@@ -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.