scaffold-agent-specs 0.1.4 → 0.1.8

package/README.md

@@ -6,33 +6,7 @@ A deliberately small, dependency-free CLI for **spec-driven agentic coding**. It
 
 Node.js 20 or newer and npm (for installation or `npx`). The scaffolded repository itself can use **any** programming language or framework.
 
-## Use locally before publishing
-
-Download and extract this project, then run:
-
-```sh
-cd scaffold-agent-specs
-npm test
-node bin/scaffold-agent-specs.js --help
-
-# Preview what will be created in any repo:
-node bin/scaffold-agent-specs.js init --dir /path/to/your/repo --dry-run
-
-# Actually initialize the repo:
-node bin/scaffold-agent-specs.js init --dir /path/to/your/repo
-```
-
-Or use `npm link` from this package directory to install the development command into your PATH:
-
-```sh
-npm link
-cd /path/to/your/repo
-scaffold-agent-specs init
-```
-
-Unlink later with `npm unlink -g scaffold-agent-specs`.
-
-## After publishing to npm
+## Usage
 
 From the root of any project:
 
@@ -46,7 +20,7 @@ When the user and agent have discussed a feature and the user **explicitly accep
 npx scaffold-agent-specs feature "User statistics page" --approved
 ```
 
-This would create `docs/features/feature-001-user-statistics-page/` with these files:
+This creates `docs/features/feature-001-user-statistics-page/` with these files:
 
 - `PLAN.md` for the approved scope, constraints, requirements and proposed approach.
 - `ACCEPTANCE_MATRIX.md` for objective acceptance criteria and verification evidence.
@@ -115,6 +89,16 @@ There is intentionally no `implement` command: an agent should follow `AGENTS.md
 
 ## Develop
 
+To run the CLI from a clone of this repository:
+
+```sh
+npm test
+node bin/scaffold-agent-specs.js --help
+node bin/scaffold-agent-specs.js init --dir /path/to/your/repo --dry-run
+```
+
+Or use `npm link` to put the development command on your PATH, and `npm unlink -g scaffold-agent-specs` to remove it later.
+
 ```sh
 npm test                # Built-in Node.js test runner
 npm run format          # Format scaffold Markdown with Prettier
@@ -123,7 +107,7 @@ npm run pack:check      # Preview npm-published file manifest
 npm pack                # Produce local npm tarball for testing
 ```
 
-For publication instructions, see [`PUBLISHING.md`](PUBLISHING.md).
+For the release steps, see [`PUBLISHING.md`](PUBLISHING.md).
 
 ## License
 

package/lib/released-fingerprints.json

@@ -3,7 +3,9 @@
     "6bdd5aa7149e0e3a53ddf1ff3fc067c3797e0c9942844cbb00b34c228204183c"
   ],
   ".agent-specs/templates/conventions/CONVENTION.md": [
-    "462a9cbf6c502f6692c9813a2da02e796a3547d02fb58058e2153bf4e3dc91d3"
+    "462a9cbf6c502f6692c9813a2da02e796a3547d02fb58058e2153bf4e3dc91d3",
+    "636e0b91189004f35c12da1d31bca6a26d5b6e6460547ac7b052f6dcfe4122c8",
+    "6f048a218b8fa094fe8d12ee1978d0600849db4d8142ca56502e986b5af7dfaa"
   ],
   ".agent-specs/templates/feature/ACCEPTANCE_MATRIX.md": [
     "0efef77a6c06737d224289611ab9cd7640a987395bcb526fff4f4b5f86295753"
@@ -36,7 +38,9 @@
     "c08f3412d558b6992b0a2e003d5be0de201502846453c2b2da70c2d682d5815a",
     "bc70d6dee9f3f76affb0636ff804a112885b0973aaa2753ac970fc83d0260b5e",
     "a09404a3dce7e2c1f7aa0efce59c5b075943ad768a02b62dc51e08e44a050318",
-    "53776f37c6f55ece45c4b4d32d2a48749031c90e77047d9a730c3f150af0d79f"
+    "53776f37c6f55ece45c4b4d32d2a48749031c90e77047d9a730c3f150af0d79f",
+    "3753a29898a4209208fdbb8f1e9a3de206d845d95e60d8c543f48c2c239780bf",
+    "78e89555d30c751816a523575b57aca8d8f2421b478769134bf31c1a16967a04"
   ],
   "CLAUDE.md": [
     "272bcb5a9f136af56c1c93203c21976e02a09ed0a59d2515fad23d24b6c34408"
@@ -45,7 +49,10 @@
     "0712abf011e6632fcdaee95c9b0c7bcad39808b5d28678c25aa0c05d281f795f",
     "637e83ce425e97ee9751a8500f5928d1f1ed2536e8d1a02b85bf6e11bc937192",
     "9dd7762484311d7a2a59620d4e89c61e4eb68688d9ebe1b3e2f2ac6d114373fd",
-    "049b5a682f613a0bb2dab7bd39e79645860eb30202d358ed9a879dbe238e84bc"
+    "049b5a682f613a0bb2dab7bd39e79645860eb30202d358ed9a879dbe238e84bc",
+    "8f66846159f0f049af2035fd71be7b289cc999099ad2ac6c1aa3b61745754745",
+    "4e12aed278f410305dc640a9f9cb0fa5135e28b0963c2a9bc4a8b7810e4af63f",
+    "3c2f525236c4b45addd5d62ffa3466b93d6502829082c1248da35a504d186e8a"
   ],
   "docs/adr/README.md": [
     "2f27a4a5ecfb92725875c0b859194588b0ed367ac87b7d321ba063062abf25d5"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "scaffold-agent-specs",
-  "version": "0.1.4",
+  "version": "0.1.8",
   "description": "A tiny, spec-driven workflow scaffold for AI coding agents",
   "type": "module",
   "license": "MIT",

package/scaffold/.agent-specs/templates/conventions/CONVENTION.md

@@ -1,6 +1,6 @@
 # [Topic] Conventions
 
-> **Optional project document.** When a stable convention applies across multiple features, copy this template to `docs/conventions/[topic].md`. Keep concrete rules here, not generic agent-process instructions. Prefer existing formatters, linters, and tooling as the source of truth for mechanically enforced rules.
+> **Optional project document.** When a stable convention applies across multiple features, copy this template to `docs/conventions/[topic].md`. Keep concrete rules here, not generic agent-process instructions or decisions specific to one feature (record those in an ADR and link it). Prefer existing formatters, linters, and tooling as the source of truth for mechanically enforced rules.
 
 ## Scope
 
@@ -17,3 +17,5 @@
 ## Exceptions and evolution
 
 [Known exceptions, how to propose changes, and links to relevant ADRs or tooling.]
+
+Rules specific to one feature belong in that feature's plan or an ADR; link them here instead of restating them.

package/scaffold/AGENTS.md

@@ -16,7 +16,7 @@ These are the shared instructions for AI coding agents working in this repositor
 For **new features**, follow this sequence:
 
 1. **Discover:** Discuss the idea with the user. Understand the problem, users, expected behavior, constraints, boundaries, and unresolved questions. Do not implement the feature or create its feature directory during discovery.
-2. **Propose:** Present a concise scope summary covering the goal, in-scope and out-of-scope behavior, important acceptance outcomes, assumptions, and consequential open questions. Explicitly offer **accept / revise / discard**.
+2. **Propose:** Present a concise scope summary covering the goal, in-scope and out-of-scope behavior, important acceptance outcomes, assumptions, and consequential open questions. If the scope holds parts that can be built and verified on their own, propose splitting it into several features. Explicitly offer **accept / revise / discard**.
 3. **Get approval:** Treat only a clear, affirmative user response as scope approval. If the user revises the proposal, summarize the revised scope and seek approval again. If discarded, do not create feature artifacts.
 4. **Specify:** After approval, create `docs/features/feature-NNN-kebab-case/` and populate `PLAN.md`, `ACCEPTANCE_MATRIX.md`, and `TASKS.md` from `.agent-specs/templates/feature/`, following the steps in [`docs/WORKFLOW.md`](docs/WORKFLOW.md) (Phase 3). Add `DESIGN.md` for substantial UX/technical design and `RESEARCH.md` for findings worth preserving, only when needed. Create `HANDOFF.md` when a real session handoff is useful. Record the approved scope faithfully. Mark proposed technical choices as proposed, not approved.
 5. **Stop at the spec boundary:** After writing the feature documents, summarize what was created and stop. **Do not start implementation** until the user explicitly requests it, possibly in a later session.
@@ -27,7 +27,7 @@ Existing-feature work and ordinary fixes should follow the user's requested scop
 
 ### Scope changes and technical decisions
 
-- An approved feature scope is the baseline. Ask for renewed approval before materially changing promised behavior, exclusions, or acceptance criteria.
+- An approved feature scope is the baseline. Ask for renewed approval before materially changing promised behavior, exclusions, or acceptance criteria, and before adding user-visible behavior the scope doesn't include, however small.
 - Technical implementation details can evolve within that scope. Surface decisions that introduce major dependencies, migrations that modify or delete existing data, security implications, substantial complexity, or broad architectural consequences before committing to them.
 - Keep proposed decisions in the feature `PLAN.md`. Add a project-wide ADR **when a significant architectural decision has actually been adopted**, typically after implementation. For consequential decisions adopted earlier, record the ADR at adoption rather than losing the rationale. Never turn an unimplemented proposal into an accepted ADR.
 
@@ -50,7 +50,7 @@ Existing-feature work and ordinary fixes should follow the user's requested scop
 - Do not write speculative ADRs during feature discovery or initial specification. Capture proposed approaches and uncertainties in `PLAN.md` instead.
 - Keep docs concise and accurate; remove stale claims rather than merely appending new text.
 - Practice **progressive documentation**: create an optional document only to solve a concrete problem. Prefer updating an existing source of truth over producing redundant or empty files.
-- If maintained, keep `docs/ARCHITECTURE.md` aligned with the _implemented_ system, `docs/GLOSSARY.md` aligned with shared domain language, and `docs/conventions/` aligned with stable project-specific practices. Create them only when useful, from `.agent-specs/templates/project/` or `.agent-specs/templates/conventions/`. When closing a feature, check whether one has become useful and propose it to the user (see [`docs/WORKFLOW.md`](docs/WORKFLOW.md), Phase 5). An adopted architecture decision still belongs in an ADR.
+- If maintained, keep `docs/ARCHITECTURE.md` aligned with the _implemented_ system, `docs/GLOSSARY.md` aligned with shared domain language, and `docs/conventions/` aligned with stable project-specific practices. Create them only when useful, from `.agent-specs/templates/project/` or `.agent-specs/templates/conventions/`. When closing a feature, check whether one has become useful and report your recommendation to the user (see [`docs/WORKFLOW.md`](docs/WORKFLOW.md), Phase 5). An adopted architecture decision still belongs in an ADR.
 
 ## Verification and completion
 

package/scaffold/docs/WORKFLOW.md

@@ -5,8 +5,10 @@ This document expands the feature lifecycle required by [`AGENTS.md`](../AGENTS.
 ## Phase 1: Discover (conversation only)
 
 - Read existing code and documentation when relevant, then explore the user's idea collaboratively.
+- Check for overlap with existing features: list `docs/features/` and judge by folder names. Open a feature's `PLAN.md` only when its name suggests related scope, and read its summary and approved scope rather than the whole folder. If scope overlaps, say so in the proposal and settle with the user which feature owns it.
 - Ask focused clarifying questions, using the agent's interactive question interface where available or normal chat otherwise. Prefer small, purposeful batches over long questionnaires.
 - Establish the problem, target users, expected behaviors, important edge cases, constraints, dependencies, and exclusions.
+- Ask how the user wants the feature verified when that affects effort or tooling, for example browser end-to-end tests or checks on a device or service the agent can't reach. If the project already has a test approach, follow it instead of asking.
 - Offer sensible defaults and surface tradeoffs; do not silently make consequential product decisions.
 - Do **not** create a feature directory, commit a spec, or implement the feature yet.
 
@@ -20,6 +22,8 @@ Present a readable summary with:
 4. **Acceptance expectations**: how success will be recognized.
 5. **Assumptions, risks, and open questions**: especially choices that affect cost or design.
 
+**Size the feature.** A feature is one increment the user can review and verify in one sitting. If the scope contains parts that can be built and verified on their own, or would need more than about ten acceptance criteria, propose splitting it into several features: list them in build order with their dependencies, and let the user choose between the split and a single feature. Each feature gets its own directory; one approval can cover the whole set.
+
 Ask the user to **accept, revise, or discard**.
 
 - **Accept:** proceed to specification.
@@ -31,7 +35,7 @@ Ask the user to **accept, revise, or discard**.
 
 Create the feature directory by hand:
 
-1. **Number:** find the highest `NNN` among the existing `docs/features/feature-NNN-*` directories and add one (start at `001`). Never reuse a number.
+1. **Number:** find the highest `NNN` among the existing `docs/features/feature-NNN-*` directories and add one (start at `001`). Never reuse a number. If the user re-scopes or splits a feature before any of it is implemented, restructure its documents in a new commit; it may keep its number and take a new slug.
 2. **Name:** `docs/features/feature-NNN-kebab-case/`, where `kebab-case` is a short slug of the feature title (for example `feature-007-user-statistics-page`).
 3. **Copy:** `PLAN.md`, `ACCEPTANCE_MATRIX.md`, and `TASKS.md` from `.agent-specs/templates/feature/`, plus any optional templates needed (see the table below).
 4. **Fill identifiers:** in every copied file, replace `feature-NNN-kebab-case` with the directory name, the `NNN` in `Feature NNN:` with the number, `[Feature title]` with the title, and `[YYYY-MM-DD]` with today's date.
@@ -50,7 +54,7 @@ Required and optional documents:
 | `RESEARCH.md`          | Durable findings from meaningful investigation                                 | Optional       |
 | `HANDOFF.md`           | Short-lived context for work that will resume elsewhere                        | Only if useful |
 
-Write the approved scope into `PLAN.md`. Draft acceptance criteria and tasks that correspond to that scope. Cross-reference IDs where practical. Put unresolved technical questions in the plan, rather than inventing answers. Add `DESIGN.md` only for substantial design detail, and `RESEARCH.md` only when research findings are worth retaining. Do not write an ADR for an unimplemented option.
+Write the approved scope into `PLAN.md`. Draft acceptance criteria and tasks that correspond to that scope. Cross-reference IDs where practical. State each criterion's verification method as the observable check (for example "journey completes in a browser at 360 px width"), not a specific test tool, unless the user or the project has already chosen one; tooling is an implementation choice. Put unresolved technical questions in the plan, rather than inventing answers. Add `DESIGN.md` only for substantial design detail, and `RESEARCH.md` only when research findings are worth retaining. Do not write an ADR for an unimplemented option.
 
 **Then stop.** Tell the user what was scaffolded, identify open decisions or blockers, and wait for an explicit implementation request. Feature approval is **not** implementation authorization.
 
@@ -59,6 +63,7 @@ Write the approved scope into `PLAN.md`. Draft acceptance criteria and tasks tha
 - Re-read the active feature's plan, acceptance matrix, and tasks, plus any optional design/research documents; inspect relevant code and applicable `docs/conventions/` documentation.
 - Check readiness: requirements coherent, blockers identified, implementation direction sensible, verification approach practical. Record any blockers under "Dependencies and blockers" in `TASKS.md`, then set its status to `Ready`, and to `In progress` once work starts.
 - Seek human input before significant new dependencies, migrations that modify or delete existing data, security-sensitive choices, or changes to approved behavior. Purely additive migrations (for example, a new table or store that leaves existing data untouched) need no prior approval, but record them in the plan and report them. Technical refinement that stays within scope usually needs no additional approval.
+- Treat user-visible behavior beyond the approved requirements as a scope change, however small (for example, undoing an action or an extra management capability): ask before building it, then add it to the plan's requirements and scope change log. Supporting work that leaves behavior unchanged, such as operator scripts or security hardening, needs no approval but belongs in the plan's technical approach.
 - Work through `TASKS.md`, updating checked items to reflect reality. Keep plan notes synchronized when implementation choices change.
 - Add or update tests and record concrete results in `ACCEPTANCE_MATRIX.md`.
 - If interrupted, add or refresh `HANDOFF.md` with the current task, blockers, commands run, and the next actionable step.
@@ -67,8 +72,9 @@ Write the approved scope into `PLAN.md`. Draft acceptance criteria and tasks tha
 
 - Review each acceptance criterion against observable evidence. Use `Pass`, `Fail`, `Blocked`, or `Not run`; never invent a result. If a criterion is waived or removed, record the user's approval and update scope accordingly.
 - Run applicable checks and document anything not run.
+- Reconcile `PLAN.md` with what shipped: its technical approach, assumptions, and references (ADRs, related features) must describe the implementation, with no stale claims left, and any behavior added during implementation must appear in its requirements.
 - Update affected user/developer/project documentation in the same change. Maintain `docs/ARCHITECTURE.md`, `docs/GLOSSARY.md`, and `docs/conventions/` when they exist and are affected by the change.
-- Check whether a missing project document has become useful. If this feature relied on a rule that earlier features also relied on and that the code doesn't make obvious (one whose violation would be a silent bug), propose recording it in `docs/conventions/`. If domain terms are now used across several features, propose `docs/GLOSSARY.md`. Propose rather than create, and include the proposal in your report.
+- Check whether a missing project document has become useful. Consider `docs/conventions/` for a rule that earlier features also relied on and that the code doesn't make obvious (one whose violation would be a silent bug), and `docs/GLOSSARY.md` for domain terms used across several features or easily confused with each other. **Always include the outcome in your report**: name each candidate and say whether you recommend it and why, even if you recommend against it. The user decides; don't create the document until they agree.
 - Create ADRs for meaningful architectural decisions **actually adopted**. Normally do this after the implementation is known; for a consequential choice adopted earlier, record it at that point.
 - Report what shipped, what was validated, any limitations, and whether the feature is complete. A feature is not complete while required acceptance criteria remain failing, blocked, or unverified.
 - Set the `TASKS.md` status to `Complete` only when that holds; otherwise use `Implemented (verification pending)` and list what remains.
@@ -82,6 +88,6 @@ Write the approved scope into `PLAN.md`. Draft acceptance criteria and tasks tha
 - `RESEARCH.md`, if present, preserves meaningful investigation and uncertainty, not decisions.
 - `HANDOFF.md`, if present, is a snapshot for resumption and may be deleted once unnecessary.
 - ADRs document _adopted_, broadly relevant architecture decisions; feature plans retain proposals and feature-local tradeoffs.
-- `docs/ARCHITECTURE.md` describes the implemented system; `docs/GLOSSARY.md` defines shared domain terminology; `docs/conventions/` records reusable project practices. Create these documents only when they provide value. Templates are under `.agent-specs/templates/`.
+- `docs/ARCHITECTURE.md` describes the implemented system; `docs/GLOSSARY.md` defines shared domain terminology; `docs/conventions/` records reusable project practices, not decisions specific to one feature (those belong in an ADR or the feature's plan; link them instead of restating them). Create these documents only when they provide value. Templates are under `.agent-specs/templates/`.
 
 Approved scope changes must be brought back to the user before being incorporated as commitments. Keep artifacts understandable to someone resuming the project without the original chat history. **Progressive documentation:** do not create an optional document just because a template exists; prefer updating a single authoritative source over duplicating content.