scaffold-agent-specs 0.1.4 → 0.1.6

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,8 @@
     "c08f3412d558b6992b0a2e003d5be0de201502846453c2b2da70c2d682d5815a",
     "bc70d6dee9f3f76affb0636ff804a112885b0973aaa2753ac970fc83d0260b5e",
     "a09404a3dce7e2c1f7aa0efce59c5b075943ad768a02b62dc51e08e44a050318",
-    "53776f37c6f55ece45c4b4d32d2a48749031c90e77047d9a730c3f150af0d79f"
+    "53776f37c6f55ece45c4b4d32d2a48749031c90e77047d9a730c3f150af0d79f",
+    "3753a29898a4209208fdbb8f1e9a3de206d845d95e60d8c543f48c2c239780bf"
   ],
   "CLAUDE.md": [
     "272bcb5a9f136af56c1c93203c21976e02a09ed0a59d2515fad23d24b6c34408"
@@ -45,7 +48,9 @@
     "0712abf011e6632fcdaee95c9b0c7bcad39808b5d28678c25aa0c05d281f795f",
     "637e83ce425e97ee9751a8500f5928d1f1ed2536e8d1a02b85bf6e11bc937192",
     "9dd7762484311d7a2a59620d4e89c61e4eb68688d9ebe1b3e2f2ac6d114373fd",
-    "049b5a682f613a0bb2dab7bd39e79645860eb30202d358ed9a879dbe238e84bc"
+    "049b5a682f613a0bb2dab7bd39e79645860eb30202d358ed9a879dbe238e84bc",
+    "8f66846159f0f049af2035fd71be7b289cc999099ad2ac6c1aa3b61745754745",
+    "4e12aed278f410305dc640a9f9cb0fa5135e28b0963c2a9bc4a8b7810e4af63f"
   ],
   "docs/adr/README.md": [
     "2f27a4a5ecfb92725875c0b859194588b0ed367ac87b7d321ba063062abf25d5"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "scaffold-agent-specs",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "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

@@ -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,6 +5,7 @@ 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.
 - Offer sensible defaults and surface tradeoffs; do not silently make consequential product decisions.
@@ -68,7 +69,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.
 - 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 +83,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.