scaffold-agent-specs 0.1.6 → 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

@@ -39,7 +39,8 @@
     "bc70d6dee9f3f76affb0636ff804a112885b0973aaa2753ac970fc83d0260b5e",
     "a09404a3dce7e2c1f7aa0efce59c5b075943ad768a02b62dc51e08e44a050318",
     "53776f37c6f55ece45c4b4d32d2a48749031c90e77047d9a730c3f150af0d79f",
-    "3753a29898a4209208fdbb8f1e9a3de206d845d95e60d8c543f48c2c239780bf"
+    "3753a29898a4209208fdbb8f1e9a3de206d845d95e60d8c543f48c2c239780bf",
+    "78e89555d30c751816a523575b57aca8d8f2421b478769134bf31c1a16967a04"
   ],
   "CLAUDE.md": [
     "272bcb5a9f136af56c1c93203c21976e02a09ed0a59d2515fad23d24b6c34408"
@@ -50,7 +51,8 @@
     "9dd7762484311d7a2a59620d4e89c61e4eb68688d9ebe1b3e2f2ac6d114373fd",
     "049b5a682f613a0bb2dab7bd39e79645860eb30202d358ed9a879dbe238e84bc",
     "8f66846159f0f049af2035fd71be7b289cc999099ad2ac6c1aa3b61745754745",
-    "4e12aed278f410305dc640a9f9cb0fa5135e28b0963c2a9bc4a8b7810e4af63f"
+    "4e12aed278f410305dc640a9f9cb0fa5135e28b0963c2a9bc4a8b7810e4af63f",
+    "3c2f525236c4b45addd5d62ffa3466b93d6502829082c1248da35a504d186e8a"
   ],
   "docs/adr/README.md": [
     "2f27a4a5ecfb92725875c0b859194588b0ed367ac87b7d321ba063062abf25d5"

package/package.json

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

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.
 

package/scaffold/docs/WORKFLOW.md

@@ -8,6 +8,7 @@ This document expands the feature lifecycle required by [`AGENTS.md`](../AGENTS.
 - 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.
 
@@ -21,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.
@@ -32,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.
@@ -51,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.
 
@@ -60,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.
@@ -68,6 +72,7 @@ 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. 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.