scaffold-agent-specs 0.2.0 → 0.2.1

package/lib/basic-AGENTS.md

@@ -8,6 +8,7 @@ These shared instructions apply to all coding agents. Follow existing project pr
 - Explain assumptions, uncertainty, incomplete work, and failed or unrun checks honestly.
 - Follow existing UI conventions and design-system documentation when working on visual interfaces.
 - Update affected documentation alongside code. Document consequential decisions where the project normally records them. Keep documentation concise and prefer an existing source of truth.
+- Add or update automated tests for behavior changes when the project has a test suite; if a behavior can't reasonably be tested automatically, say why.
 - Run relevant checks before claiming completion. Never claim unverified success. Report changes, verification evidence, and remaining limitations.
 - Follow repository conventions and the user's instructions for Git workflow and commit messages. Keep commits focused; do not commit secrets, credentials, local environment files, or unrelated changes.
 - Do not push, rewrite history, or change branches without the user's authorization.

package/lib/released-fingerprints.json

@@ -67,7 +67,11 @@
     "d527b953d0f1d6fd805e9800ba4ba71db2e5e1c25dcdfe4bdbfc6706e1782314",
     "f730107d9764f5a0a294124e04c9a5c89ecda9e6f3365afc9b0ca4a952dec1d1",
     "9c8d3e7eb471911d0ca58bfd0331298effcee068f28b71f52373c05641c3bc93",
-    "94a8b845546e7f7564cac89ee73cdcb24ac4d54989c7a9f6c676e7e8066c64cd"
+    "94a8b845546e7f7564cac89ee73cdcb24ac4d54989c7a9f6c676e7e8066c64cd",
+    "e5eab6b6a716b79a496d25aa501a1c98cef886b0ce695ef9becc94c77c442824",
+    "e697e51065467c9b160859efea601535fb0fcec175c7705ce13424fe7b363269",
+    "a6160169f9e674ca96105498854550b7dbe3557454f6dab57325e255648468ab",
+    "79548f0b3701dbac5b3872726fcba40663774eb867744bdfdc21b55b75ca2dd5"
   ],
   "CLAUDE.md": [
     "67de3db5b7413656ff1d221df90360fdfd0dd80608eb5dbae0416fecf359cbf8",
@@ -84,7 +88,10 @@
     "6ae499a00796e17367c1c25bd5f162b040622aa1bcc4f0d39ba5efc8817bfbd3",
     "59708748d05e26859c71eb9beab4f27b1e9dcded7bc4648d04bb35033b853022",
     "70de8d1dc3a24c3bc293a696ad2b150c6d9dced69d0a5d03f54f3f7e275bfa33",
-    "05dd5854cb7a287ad2d39119c4f10b647415d2a6b01be0d7c6fe8427a012590c"
+    "05dd5854cb7a287ad2d39119c4f10b647415d2a6b01be0d7c6fe8427a012590c",
+    "b112b7ebdae8c2b7eed70aa15c7118f6804abcf44b628d89b0f0ac58ac84da51",
+    "9a1e43ec8035a467e546d8e9a6a53a9d5ad86d87a493680f938a4ada24b13fb1",
+    "f486c636571db610be3cfbb4d832db28ff22b2f1a50fbfcbf721c66a349d20de"
   ],
   "docs/adr/README.md": [
     "1d2c05c11246d0d45592f930b3a339bf454363875b968f650165e91a906c95af"

package/package.json

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

package/scaffold/AGENTS.md

@@ -22,11 +22,12 @@ For new features:
 4. **Stop after specification.** Summarize the documents and blockers. Start implementation only when the user explicitly requests it.
 5. Implement within approved scope, keep documents current, and verify acceptance outcomes before declaring completion.
 
-Existing-feature work and ordinary fixes follow the user's requested scope; do not force a new feature directory for every small change.
+Existing-feature work and ordinary fixes follow the user's requested scope; do not force a new feature directory for every small change. To extend a completed feature, follow [Amending a completed feature](docs/WORKFLOW.md#amending-a-completed-feature).
 
 ### Scope and decision boundaries
 
 - Ask before changing promised behavior, exclusions, or acceptance criteria, or adding an independent user-facing capability, however small.
+- A new capability follows the feature workflow even when the user asks for it directly. The only exception is a small one whose whole behavior fits in one sentence, such as an extra option or a single-step command like undo: the request approves it. Before building it, ask about any consequential choice it leaves open, such as which item "most recent" means. If a feature is in progress, commit its current milestone first. Record it in the active or a completed feature when it fits that feature's purpose; otherwise describe it in the commit message. A new view, report, or multi-step workflow, or anything needing more than a quick question to settle, is a new feature.
 - Implementation choices necessary to fulfill agreed outcomes may proceed without renewed approval. This includes validation and error feedback needed to make an agreed form work coherently. Record meaningful choices in the plan. New capabilities such as undo, additional management actions, or a changed recovery policy need approval.
 - Surface major dependencies, migrations that modify or delete existing data, security-sensitive choices, substantial complexity, and broad architectural consequences before committing to them. Follow the workflow for technical refinements within scope.
 
@@ -36,13 +37,14 @@ Existing-feature work and ordinary fixes follow the user's requested scope; do n
 - Respect document ownership: `PLAN.md` owns scope and approach; `ACCEPTANCE_MATRIX.md` owns verification evidence; `TASKS.md` owns progress and the sole feature lifecycle status. Optional documents must not supersede them.
 - Use the [optional project document catalog](docs/WORKFLOW.md#optional-project-document-catalog) for creation triggers, ownership, and when to consult shared references. Reuse existing sources, create documents only when useful and authorized, and remove stale claims. Feature-level optional documents are covered by the workflow's Phase 3 table.
 - Record significant adopted architectural decisions in `docs/adr/`; keep unimplemented proposals in the plan. Use the ADR template and avoid ADRs for routine local details.
+- Add or update automated tests for every behavior change, inside or outside a feature, whenever the project has a test suite. If a behavior cannot reasonably be tested automatically, say why and verify it another way; manual verification alone is not a substitute for an achievable test.
 - Run relevant tests, linters, type checks, and builds before claiming completion, or explain precisely why checks were not run. Record concrete evidence; implementation alone is not a pass.
 - For applicable changes, document rollout, migrations, recovery limits, and post-release checks in the existing feature documents, linking to shared deployment/publishing guidance. Distinguish implemented and verified work from released behavior. Follow existing authorization for release execution; documentation alone does not grant it.
 - Mark a feature complete only when acceptance criteria pass or the user explicitly accepts exceptions. Report unresolved failures, missing verification, migrations, and follow-up work.
 
 ## Git commits
 
-Follow the user's explicit commit preference first, including requests to review diffs before commits or to leave work uncommitted. Otherwise, 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.
+Follow the user's explicit commit preference first, including requests to review diffs before commits or to leave work uncommitted. Otherwise, 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. When a feature has both substantial domain logic and an interface layer (UI, CLI, or API), commit the domain logic with its tests before building on it. 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

@@ -68,7 +68,7 @@ If the approved scope changes behavior owned by an earlier feature, fill the pla
 - 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. Consult the existing testing guide for setup, check selection, and integration boundaries. 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 an independent user-facing capability 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. Validation and error feedback necessary to fulfill agreed outcomes may proceed without another gate; document meaningful choices in the plan. For example, an agreed form needs feedback when submission fails, but adding a new retry policy or recovery workflow may change the product contract. Supporting work that leaves behavior unchanged, such as operator scripts or security hardening, needs no approval but belongs in the plan's technical approach.
+- Treat an independent user-facing capability 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. A direct user request approves it only within the small-capability exception in `AGENTS.md`; anything larger becomes a separate feature. Validation and error feedback necessary to fulfill agreed outcomes may proceed without another gate; document meaningful choices in the plan. For example, an agreed form needs feedback when submission fails, but adding a new retry policy or recovery workflow may change the product contract. Supporting work that leaves behavior unchanged, such as operator scripts or security hardening, needs no approval but belongs in the plan's technical approach.
 - Prepare and verify release/recovery steps within the approved scope. Use the project's existing authorization process before deploying, publishing, or modifying production data; a written procedure or implementation request alone is not authorization. Reuse explicit authorization already given rather than asking again.
 - 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`.
@@ -87,12 +87,20 @@ If the approved scope changes behavior owned by an earlier feature, fill the pla
 - Report what was implemented and, if applicable, released, 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.
 
+## Amending a completed feature
+
+When the user asks to extend a completed feature with a small addition that fits its purpose (for example, a new output option for an existing command), amend that feature instead of creating a new one. A specific, explicit request approves the addition; if it leaves consequential choices open, propose them first as in Phase 2.
+
+- **Record before building:** add new requirement, acceptance, and task IDs after the existing ones, and log the change, its date, and the user's request in the plan's scope change log. Never renumber, rewrite, or delete existing rows or their evidence.
+- **Reopen honestly:** set the `TASKS.md` status to `In progress` while working. Implement and verify through Phases 4 and 5, including automated tests, and set it back to `Complete` only when the new criteria pass.
+- **Know the limits:** use a new feature instead when the addition is independently useful, needs more than a few acceptance criteria, or changes behavior that existing requirements define. Changing defined behavior follows the superseding rules below. Ordinary bug fixes that restore specified behavior need no feature documents.
+
 ## Superseding earlier feature specifications
 
 A later feature may replace only part of an earlier feature. Related work or an extension does not automatically supersede the entire earlier specification.
 
 - **During specification:** In the new plan's "Related and superseded features" section, link the earlier plan and identify exactly which requirements and acceptance criteria will change, the replacement behavior, and what remains in force. Qualify references with the feature ID (for example, `feature-003-export / FR-002`), since IDs repeat across features. Label the replacement as planned; scope approval alone does not mean the current behavior has changed.
-- **When implemented:** Record the effective replacement date and a commit, PR, or other concrete implementation reference in the new plan. Add a reciprocal "Related and superseded features" note to the earlier plan identifying the affected IDs and linking to the replacement. For staged rollouts, state where the replacement is effective and where the earlier behavior still applies. Do not mark unimplemented portions as superseded.
+- **When implemented:** Record the effective replacement date and a commit, PR, or other concrete implementation reference in the new plan. A commit cannot contain its own hash, so cite the implementing commit's subject, or add its hash in a later commit. Add a reciprocal "Related and superseded features" note to the earlier plan identifying the affected IDs and linking to the replacement. For staged rollouts, state where the replacement is effective and where the earlier behavior still applies. Do not mark unimplemented portions as superseded.
 - **Preserve evidence:** Keep the earlier requirements, acceptance rows, results, and evidence intact. Add a dated supersession note to the earlier acceptance matrix's verification notes, naming affected criteria and linking to the new plan and matrix. An old `Pass` describes the earlier behavior at the recorded verification point; it is not evidence for the replacement. Verify replacement behavior in the new feature's matrix, leaving unverified criteria `Not run` or `Blocked` as appropriate.
 - **Preserve lifecycle history:** Do not reopen a completed feature or rewrite its task checklist merely because a later feature replaces its behavior. Supersession is a relationship recorded in the plans, not a new lifecycle status or acceptance result. Unaffected requirements remain in force. Correcting genuinely inaccurate records is separate from supersession and must be explained explicitly.