project-spec 0.11.0 → 0.11.1

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
@@ -118,6 +118,15 @@ npx project-spec instructions --file AGENTS.md # or CLAUDE.md, GEMINI.md, .
118
118
 
119
119
  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
120
 
121
+ ## Upgrading
122
+
123
+ ```sh
124
+ npx project-spec@latest update # refresh every installed copy of the skill
125
+ npx project-spec@latest check # an older spec still passes; this lists anything to fix
126
+ ```
127
+
128
+ 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.
129
+
121
130
  ## Commands
122
131
 
123
132
  ```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.1",
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,7 +59,7 @@ 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.
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
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.
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.
@@ -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.