project-spec 0.11.1 → 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
|
|
27
|
-
|
|
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
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "project-spec",
|
|
3
|
-
"version": "0.11.
|
|
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",
|
|
@@ -60,7 +60,7 @@ Write vault content in English unless the user asks for another language, whatev
|
|
|
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
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
|
|
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.
|
|
@@ -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
|
|
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
|
|