project-spec 0.11.0 → 0.11.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
@@ -23,8 +23,9 @@ npx project-spec install --claude # or --codex
23
23
  ```text
24
24
  Use the project-knowledge skill to build a knowledge vault for this repository.
25
25
 
26
- First take the inventory: every app and package, every screen, API endpoint,
27
- job and email. Write it to the inventory file before any page.
26
+ First take the inventory: every app and package, and every way into each one:
27
+ what a person can open, what another system can call, what runs on its own and
28
+ what the product sends out. Write it to the inventory file before any page.
28
29
 
29
30
  Then go one feature at a time and finish each before the next. Describe only
30
31
  what the code does: one page per feature with numbered business rules, and
@@ -118,6 +119,15 @@ npx project-spec instructions --file AGENTS.md # or CLAUDE.md, GEMINI.md, .
118
119
 
119
120
  This writes a short block into the file your agent reads at the start of a session (Codex, Cursor, Claude Code, Gemini CLI, GitHub Copilot). It asks the agent to read a feature's page before changing it and to correct the changed rules afterwards. Run it again after an update and it replaces the block and leaves the rest of the file alone.
120
121
 
122
+ ## Upgrading
123
+
124
+ ```sh
125
+ npx project-spec@latest update # refresh every installed copy of the skill
126
+ npx project-spec@latest check # an older spec still passes; this lists anything to fix
127
+ ```
128
+
129
+ Your spec needs no conversion: every release since 0.7.0 only added optional things to it. Two releases changed what is installed. 0.11.0 removed the `spec-change` skill; `update` deletes its copies and keeps a backup, and a request that named it now names `project-knowledge`. 0.10.0 stopped copying the viewer into your project; open it with `npx project-spec serve`. [Upgrading from an earlier version](docs/install.md#upgrading-from-an-earlier-version) has the steps for each release.
130
+
121
131
  ## Commands
122
132
 
123
133
  ```sh
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "project-spec",
3
- "version": "0.11.0",
3
+ "version": "0.11.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",
@@ -59,8 +59,8 @@ Write vault content in English unless the user asks for another language, whatev
59
59
  ## Research before writing
60
60
 
61
61
  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.
62
- 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.
63
- 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
+ 2. Inspect manifests, entrypoints, routes, schema and migrations, services and tests. **Read the tests; do not run them.** The spec is read from the code, and a test file is one more thing to read: what it expects is evidence, whether it passes today is not something a spec page states. So a map, an explore, a sync or a recorded change runs nothing but this skill's helpers: no test suite, no build, no application. Running them for every feature costs time and money and adds nothing to a page. Run a check of the application only when the person asks for it, or in **investigate** and **recheck** when reading cannot settle the question, and then the smallest one that does. Skip dependencies, build output, credential files, raw logs and customer data. Never use the vault itself as evidence about the application.
63
+ 3. **Take the inventory before writing a page.** List every way into the product from the places that register them, every item and not a sample. There are four kinds, and what they are called depends on the product: what a person can open (the pages or screens of every client: web, mobile, admin; the commands of a command-line tool), what another system can call (API procedures, endpoints, webhooks, the public functions of a library), what runs on its own (jobs, schedules, queue consumers, triggers) and what the product sends out (emails, notifications, exports, calls to other services). These names are examples, not the list: if this product has a kind of its own (a bot command, a report, a device message), it belongs in the inventory too. 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.
64
64
  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)).
65
65
  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.
66
66
  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.
@@ -126,7 +126,7 @@ Write for the person who asks "what does this do, and what are its rules", not f
126
126
  - **The summary says what the feature is for**, in one or two plain sentences, as a person who never opens the code would say it: no file names, symbols, status codes or words like "verified", and not a rule picked from the page ("The form accepts 1-120 characters" is a rule, not a summary). The viewer shows it under the title and in every list. It is still a claim about the code: it says no more than the page proves. Do not infer design rationale; cite a comment or ADR in the source, or say it is unknown.
127
127
  - **A reference note** is a list of things the code registers in one place and that belong to no single feature: the background jobs, the emails and notifications, the routes, the roles and what each may do, the plan limits, the flags, the states of a record. It is one table, one row per item, every item, with the count and where the list comes from ("all 7 jobs registered in `worker/index.ts`"), so a later sync can tell when one is added; put that place in `sources`. A cell holds a value in a few words, two short sentences at most; an item that needs more has a feature note, and the row links to it. Do not write a list note for form fields or for the actions on a screen (they are in the feature's note), for a kind the area has only one or two of, or for a kind it does not have. Each rule is written once: in the feature's note when it belongs to a feature, in the list when it does not.
128
128
  - **Cite the few files that decide the behavior.** `sources` holds the files where the page's rules are written (the schema, the service, the component): every file a rule on the page was read from, and no others. That is often one to five; it is not a limit, and a rule read from a sixth file makes that file a source. A page that needs many more is usually a feature that should have parts. Every source is a tripwire: when it changes, the page is marked for re-reading. So leave out shared plumbing (the router, a layout, the base client), files that merely sit on the path, and tests unless a test is what the claim rests on. In the text, name the symbol a rule comes from (`INVITE_TTL_DAYS`) and link a file where it helps, without line numbers: a line number points at the wrong line after the next edit, a name still finds the place. When files are renamed or split, `check` reports the missing path; point `sources` at where the rule lives now and re-read the page.
129
- - **What you ran goes on the run page**, not in the note: commands, PASS, FAIL or NOT RUN, the revision. A note has no "Verification" section and no line naming its area (the frontmatter has it and the viewer shows it). Reading a test does not mean it passes today, so do not write that it does.
129
+ - **What you ran goes on the run page**, not in the note: commands, PASS, FAIL or NOT RUN, the revision. For most passes that is the helpers only, and `NOT RUN` beside the application's tests is the expected entry, not a hole to fill. A note has no "Verification" section and no line naming its area (the frontmatter has it and the viewer shows it). Reading a test does not mean it passes today, so do not write that it does.
130
130
  - Link related spec pages with `[[notes/example|label]]` in the sentence that needs them, and say how they relate (depends on, constrains, produces, supersedes). A note belongs to one area; give it a second only when both areas' readers would look for it there. Every substantive page needs an area and a path from the index. Add cross-area links for a reason, not for graph density.
131
131
  - A requirements document or ticket is documented intent. It can be quoted in a gap's `Evidence`; it is not a source for what the code does, so never list it in a spec page's `sources` or describe its labels in spec text.
132
132
 
@@ -182,4 +182,4 @@ Before handing over, read what you wrote as the person who will use it, not as i
182
182
  - Does the area page only map, with its missing lists named?
183
183
  - Is every doubt a gap about the product, and nothing in the queue a to-do of the vault itself?
184
184
 
185
- 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.
185
+ 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 helper 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.
@@ -200,7 +200,7 @@ Folders: web-app/src/features/reviews
200
200
  ```
201
201
 
202
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.
203
+ - One checkbox per entry point: the client or kind and the name the code registers it under. Use the product's own kinds; `web`, `mobile`, `admin`, `api`, `job`, `email`, `webhook` and `command` are common ones, not a fixed list. A box is ticked when the entry point was followed to the code that decides its behavior, not when it was seen.
204
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
205
  - "Left out" holds what was looked at and is not part of the product, each with its reason.
206
206