scaffold-agent-specs 0.1.2 → 0.1.3

package/README.md

@@ -62,6 +62,8 @@ npx scaffold-agent-specs feature "Account dashboard" --approved --design --resea
 
 **Important:** The CLI copies and personalizes headings, IDs, titles, and dates. It **does not invent a feature spec**. Your coding agent must populate the remaining placeholders from the approved conversation, then **stop** until you separately authorize implementation. The `--approved` flag is an acknowledgment; the CLI cannot verify the conversation itself.
 
+The `feature` command is a convenience for people. Agents are told to create feature directories by copying the templates themselves, following the steps in `docs/WORKFLOW.md`, so they don't depend on the CLI being installed or reachable from a sandbox.
+
 ## `init` installs
 
 ```text

package/lib/released-fingerprints.json

@@ -33,20 +33,24 @@
   ],
   "AGENTS.md": [
     "70196e937a5782962f69c2c0735929059fac6c60b724977ebbfea9d0e4c84b20",
-    "c08f3412d558b6992b0a2e003d5be0de201502846453c2b2da70c2d682d5815a"
+    "c08f3412d558b6992b0a2e003d5be0de201502846453c2b2da70c2d682d5815a",
+    "bc70d6dee9f3f76affb0636ff804a112885b0973aaa2753ac970fc83d0260b5e",
+    "a09404a3dce7e2c1f7aa0efce59c5b075943ad768a02b62dc51e08e44a050318"
   ],
   "CLAUDE.md": [
     "272bcb5a9f136af56c1c93203c21976e02a09ed0a59d2515fad23d24b6c34408"
   ],
   "docs/WORKFLOW.md": [
     "0712abf011e6632fcdaee95c9b0c7bcad39808b5d28678c25aa0c05d281f795f",
-    "637e83ce425e97ee9751a8500f5928d1f1ed2536e8d1a02b85bf6e11bc937192"
+    "637e83ce425e97ee9751a8500f5928d1f1ed2536e8d1a02b85bf6e11bc937192",
+    "9dd7762484311d7a2a59620d4e89c61e4eb68688d9ebe1b3e2f2ac6d114373fd"
   ],
   "docs/adr/README.md": [
     "2f27a4a5ecfb92725875c0b859194588b0ed367ac87b7d321ba063062abf25d5"
   ],
   "docs/features/README.md": [
     "a46ffb46dc49d5304db438179e6b090665d706d2f09c50c56bb2a0c09c92b5da",
-    "3fb7c6fa1177a5cb940e8066d18624ce0d32c76b945a9b1f183d8809f40a7275"
+    "3fb7c6fa1177a5cb940e8066d18624ce0d32c76b945a9b1f183d8809f40a7275",
+    "ddf40d2b1fd1fb821799e59df15c4ab9ce9edf1e231b3fce5776ff3635c3ffaf"
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "scaffold-agent-specs",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "A tiny, spec-driven workflow scaffold for AI coding agents",
   "type": "module",
   "license": "MIT",
@@ -31,5 +31,13 @@
     "claude-code",
     "codex"
   ],
-  "author": "rob-pasc"
+  "author": "rob-pasc",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rob-pasc/scaffold-agent-specs.git"
+  },
+  "homepage": "https://github.com/rob-pasc/scaffold-agent-specs#readme",
+  "bugs": {
+    "url": "https://github.com/rob-pasc/scaffold-agent-specs/issues"
+  }
 }

package/scaffold/AGENTS.md

@@ -18,7 +18,7 @@ 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**.
 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/`. You may run `npx scaffold-agent-specs feature "Title" --approved` to create the files (if the command is unavailable, copy the templates by hand); the CLI does not write the approved requirements for you. 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.
+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.
 6. **Implement and verify:** On an explicit implementation request, review the feature documents and relevant code. Resolve blockers, surface consequential technical choices, then execute tasks, validate acceptance criteria, and keep the documents current.
 7. **Finish:** Update related documentation, capture architectural decisions actually adopted, report verification evidence and remaining limitations, and mark the feature complete only when acceptance criteria are satisfied or exceptions explicitly accepted by the user.
@@ -28,7 +28,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.
-- Technical implementation details can evolve within that scope. Surface decisions that introduce major dependencies, migrations, security implications, substantial complexity, or broad architectural consequences before committing to them.
+- 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.
 
 ## Feature documentation contracts
@@ -61,7 +61,7 @@ Existing-feature work and ordinary fixes should follow the user's requested scop
 
 ## Git commits
 
-Commit your work as you go, at points you judge sensible, without waiting to be asked. Good points include written feature specs, a completed task or coherent group of tasks, and a fix that resolves a verified problem.
+Commit your work as you go, without waiting to be asked. Commit approved feature specs on their own. During implementation, commit at **milestones**: points you would want to return to. A milestone passes the relevant checks and has one theme you can describe in a sentence, such as the domain logic for a feature with its tests, or the UI built on top of it. A feature typically takes a few commits; neither one per task nor one per feature. Also commit before risky steps (large refactors, migrations, dependency changes) and before ending a session. Split a commit that would mix unrelated concerns.
 
 - Run the relevant checks before committing. If you commit while something is failing or incomplete, say so in the message.
 - Don't commit secrets, credentials, local environment files, or build output that the repository doesn't already track.

package/scaffold/docs/WORKFLOW.md

@@ -29,7 +29,17 @@ Ask the user to **accept, revise, or discard**.
 
 ## Phase 3: Specify (after accepted scope)
 
-Choose `feature-NNN-kebab-case`, using the next available ID above the current maximum (starting with `001`). Once the user approves, optionally run `npx scaffold-agent-specs feature "Title" --approved` to create the directory from templates; if the command is unavailable, copy the templates by hand. The flag acknowledges explicit approval; the CLI does not verify the conversation or write the actual scope. Create the directory and populate:
+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.
+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.
+5. **Fill content:** replace every remaining bracketed prompt, such as `[First actionable implementation step]`, with content from the approved discussion, and delete template guidance that doesn't apply. No prompts may remain.
+
+(The `scaffold-agent-specs feature` command performs steps 1–4 for people who prefer it; agents don't need it.)
+
+Required and optional documents:
 
 | File                   | Purpose                                                                        | Required?      |
 | ---------------------- | ------------------------------------------------------------------------------ | -------------- |
@@ -48,7 +58,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, security-sensitive choices, or changes to approved behavior. Technical refinement that stays within scope usually needs no additional approval.
+- 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.
 - 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.

package/scaffold/docs/features/README.md

@@ -2,7 +2,7 @@
 
 Create a directory here **only after the user explicitly accepts the feature scope**. Do not create speculative feature directories during discovery.
 
-After approval, an agent may run `npx scaffold-agent-specs feature "Feature title" --approved` (or copy the templates by hand), then fill all required documents from the accepted discussion. The CLI only creates templated files and replaces identifiers, titles, and dates.
+After approval, agents create the directory by copying the templates, following the steps in [`docs/WORKFLOW.md`](../WORKFLOW.md) (Phase 3), then fill all required documents from the accepted discussion. People can use `npx scaffold-agent-specs feature "Feature title" --approved` instead; it only creates the templated files and fills in identifiers, titles, and dates.
 
 Each feature is named `feature-NNN-kebab-case`, for example `feature-007-user-statistics-page`. Start at `001` and choose the next number above the highest existing feature ID; do not reuse numbers.