scaffold-agent-specs 0.1.6 → 0.2.0

package/README.md

@@ -6,38 +6,12 @@ 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:
 
 ```sh
-npx scaffold-agent-specs init
+npx scaffold-agent-specs init --profile opinionated
 ```
 
 When the user and agent have discussed a feature and the user **explicitly accepts its scope**:
@@ -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.
@@ -64,7 +38,19 @@ npx scaffold-agent-specs feature "Account dashboard" --approved --design --resea
 
 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
+For a complete request-to-verification walkthrough with runnable code, see the [worked example](examples/feature-workflow/README.md).
+
+## Install profiles
+
+Run `npx scaffold-agent-specs init` to choose interactively between **basic** (quality safeguards and existing project conventions) and **opinionated** (formal feature specs, approval gates, acceptance tracking, and milestone commits). Noninteractive installs default to basic. Select explicitly with `--profile basic` or `--profile opinionated`.
+
+Basic installs `AGENTS.md` and the thin `CLAUDE.md` adapter. Opinionated installs the full scaffold below. Both record the selection in `.agent-specs/profile.json`; commit this file so updates preserve the profile. Older installations without this file retain opinionated behavior when their workflow or template directory exists.
+
+Use `update --profile opinionated` or `update --profile basic` to switch. Released instructions are replaced, customized files are skipped, and `--dry-run` previews without changing the profile. Switching to basic leaves existing templates and feature documents in place; its instructions no longer require the formal workflow. Review skipped instructions when switching, since they can still describe the previous profile. `init` never switches an existing profile; use `update` instead.
+
+The `feature` command requires the opinionated templates. Basic users can install them with `update --profile opinionated`.
+
+## Opinionated `init` installs
 
 ```text
 AGENTS.md
@@ -74,14 +60,18 @@ CLAUDE.md
     adr/ADR.md
     conventions/CONVENTION.md
     feature/{PLAN,ACCEPTANCE_MATRIX,TASKS,DESIGN,RESEARCH,HANDOFF}.md
-    project/{ARCHITECTURE,GLOSSARY}.md
+    project/{ARCHITECTURE,GLOSSARY,VISUAL_DESIGN,TESTING,PRODUCT,DEPLOYMENT}.md
 docs/
   WORKFLOW.md
   adr/README.md
   features/README.md
 ```
 
-No speculative feature, ADR, architecture document, glossary, or convention document is created. Those appear only when needed. The templates in `.agent-specs/` are yours to edit; **the `feature` command reads your repository's copy**, including your customizations, not the package's default templates.
+No speculative feature, ADR, architecture document, glossary, visual design reference, testing guide, product context, deployment guide, or convention document is created. Those appear only when needed. The templates in `.agent-specs/` are yours to edit; **the `feature` command reads your repository's copy**, including your customizations, not the package's default templates.
+
+The workflow's [optional project document catalog](scaffold/docs/WORKFLOW.md#optional-project-document-catalog) lists creation triggers and ownership for architecture, glossary, visual design, testing, product context, deployment, conventions, and ADRs. Agents reuse adequate existing documentation and recommend missing shared references only when useful. `AGENTS.md` links to this catalog instead of maintaining a separate list.
+
+For applicable features, release and recovery considerations live in `PLAN.md`, required checks and evidence in `ACCEPTANCE_MATRIX.md`, and release tasks in `TASKS.md`. Optional `docs/DEPLOYMENT.md` holds reusable rollout, migration, post-release verification, and recovery procedures when an existing publishing guide or runbook does not suffice. Implementation completion does not imply publication or deployment; required live checks must have evidence before the feature is marked complete.
 
 ## Commands and safety
 
@@ -100,7 +90,7 @@ No speculative feature, ADR, architecture document, glossary, or convention docu
 | `--dir PATH` | Work in a specified repository root instead of the current directory. |
 | `--help` / `--version` | Show help or the CLI version. |
 
-Feature IDs are allocated above the **largest existing** feature ID, starting at `001`. Running `init` again adds newly missing files but never replaces existing ones. `init` refuses to write through symlinked paths under the chosen root.
+Feature IDs are allocated above the **largest existing** feature ID, starting at `001`. Feature creation uses a shared lock so concurrent commands cannot allocate the same ID. If another command holds the lock, retry after it finishes. After a crash, remove `docs/features/.agent-specs-feature.lock/` only after confirming no feature command is running. Dry runs do not reserve IDs. Running `init` again adds newly missing files but never replaces existing ones. `init` refuses to write through symlinked paths under the chosen root.
 
 ## Updating an existing repository
 
@@ -109,12 +99,22 @@ npx scaffold-agent-specs@latest update --dry-run   # preview
 npx scaffold-agent-specs@latest update
 ```
 
-`update` compares each scaffold file in your repository with every released version of it. A file that still matches a released version is replaced with the current one, and a file that is missing is created. A file you have customized is skipped and reported, so you can merge the changes by hand or rerun with `--force`. Formatting-only differences (for example, Prettier padding tables) don't count as customizations. Feature documents in `docs/features/feature-*/` are never touched, so existing features keep the layout they were written with.
+`update` compares each scaffold file in your repository with every released version of it. A file that still matches a released version is replaced with the current one, and a file that is missing is created. A file you have customized is skipped and reported, so you can merge the changes by hand or rerun with `--force`. Matching is exact: formatting changes also count as customizations, because whitespace and punctuation can affect meaning. Historical releases are recognized using hashes of their original contents; previously reformatted copies may need a manual merge. Feature documents in `docs/features/feature-*/` are never touched, so existing features keep the layout they were written with.
 
 There is intentionally no `implement` command: an agent should follow `AGENTS.md` and `docs/WORKFLOW.md` and wait for a separate implementation instruction. ADRs can be created from `.agent-specs/templates/adr/ADR.md` once architectural decisions are adopted.
 
 ## 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 +123,9 @@ 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).
+
+Pull requests run tests (including an actual npm tarball smoke test) and scaffold formatting checks on Node.js 20, 22, and 24. Publishing remains manual.
 
 ## License
 

package/bin/scaffold-agent-specs.js

@@ -2,7 +2,7 @@
 import { run } from '../lib/cli.js';
 
 try {
-  run(process.argv.slice(2));
+  await run(process.argv.slice(2));
 } catch (error) {
   console.error(`Error: ${error.message}`);
   process.exitCode = 1;

package/lib/basic-AGENTS.md

@@ -0,0 +1,13 @@
+# Repository Agent Instructions
+
+These shared instructions apply to all coding agents. Follow existing project practices and the user's requested scope.
+
+- Inspect relevant code, tests, and documentation before asking questions or proposing an approach.
+- Prefer the smallest coherent change. Follow existing conventions and avoid unrelated refactors.
+- Ask focused questions about consequential choices; choose sensible defaults for minor details. Keep the user in control of scope and significant architectural tradeoffs, and ask before materially expanding the requested work.
+- 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.
+- 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/cli.js

@@ -1,12 +1,13 @@
 import fs from 'node:fs';
+import { createInterface } from 'node:readline/promises';
 import { fileURLToPath } from 'node:url';
-import { initProject, createFeature, updateProject } from './scaffold.js';
+import { initProject, createFeature, updateProject, projectProfile } from './scaffold.js';
 
 const help = `scaffold-agent-specs: spec-driven scaffolding for coding agents
 
 Usage:
-  scaffold-agent-specs init [--dir PATH] [--dry-run]
-  scaffold-agent-specs update [--dir PATH] [--dry-run] [--force]
+  scaffold-agent-specs init [--profile basic|opinionated] [--dir PATH] [--dry-run]
+  scaffold-agent-specs update [--profile basic|opinionated] [--dir PATH] [--dry-run] [--force]
   scaffold-agent-specs feature "Feature title" --approved [options]
   scaffold-agent-specs --version
   scaffold-agent-specs --help
@@ -19,6 +20,9 @@ Options for feature:
   --dry-run     Preview without writing; approval not required for a preview
   --dir PATH    Target repository root (default: current directory)
 
+Profiles: init prompts in a terminal; otherwise defaults to basic.
+Existing installations keep their profile. update --profile switches explicitly.
+
 Options for update:
   --dry-run     Preview without writing
   --force       Also overwrite files that were modified locally
@@ -31,7 +35,7 @@ still match a released version; locally modified files are skipped unless --forc
 Feature documents in docs/features/feature-*/ are never touched.
 `;
 
-export function run(args) {
+export async function run(args) {
   if (!args.length || args.includes('--help') || args.includes('-h') || args[0] === 'help') {
     console.log(help);
     return;
@@ -47,6 +51,7 @@ export function run(args) {
   const flags = new Set();
   const positionals = [];
   let dir = process.cwd();
+  let profile;
   const allowed = new Set({
     init: ['--dry-run'],
     update: ['--dry-run', '--force'],
@@ -55,7 +60,11 @@ export function run(args) {
 
   for (let i = 0; i < rest.length; i++) {
     const argument = rest[i];
-    if (argument === '--dir') {
+    if (argument === '--profile' || argument.startsWith('--profile=')) {
+      if (command === 'feature') throw new Error('--profile is only supported by init and update.');
+      profile = argument === '--profile' ? rest[++i] : argument.slice(10);
+      if (!['basic', 'opinionated'].includes(profile)) throw new Error('Profile must be basic or opinionated.');
+    } else if (argument === '--dir') {
       if (i + 1 >= rest.length || rest[i + 1].startsWith('--')) throw new Error('Missing path after --dir.');
       dir = rest[++i];
     } else if (argument.startsWith('--dir=')) {
@@ -71,12 +80,20 @@ export function run(args) {
   }
   if (command === 'init') {
     if (positionals.length) throw new Error('init takes no positional arguments.');
-    initProject(dir, { dryRun: flags.has('--dry-run') });
+    if (!profile && !projectProfile(dir) && process.stdin.isTTY && process.stdout.isTTY) {
+      const prompt = createInterface({ input: process.stdin, output: process.stdout });
+      try {
+        const answer = (await prompt.question('Profile: basic (quality safeguards) or opinionated (formal specs, approval gates, milestone commits) [basic]: ')).trim();
+        profile = answer || 'basic';
+        if (!['basic', 'opinionated'].includes(profile)) throw new Error('Profile must be basic or opinionated.');
+      } finally { prompt.close(); }
+    }
+    initProject(dir, { profile, dryRun: flags.has('--dry-run') });
     return;
   }
   if (command === 'update') {
     if (positionals.length) throw new Error('update takes no positional arguments.');
-    updateProject(dir, { dryRun: flags.has('--dry-run'), force: flags.has('--force') });
+    updateProject(dir, { profile, dryRun: flags.has('--dry-run'), force: flags.has('--force') });
     return;
   }
   if (!positionals.length) throw new Error('Missing feature title. Try `feature "User statistics page" --approved`.');

package/lib/released-fingerprints.json

@@ -1,63 +1,97 @@
 {
   ".agent-specs/templates/adr/ADR.md": [
-    "6bdd5aa7149e0e3a53ddf1ff3fc067c3797e0c9942844cbb00b34c228204183c"
+    "230b94a66fdd41f3bbc7349e3a2c072075771bf5d93ad3acb8701ad560509704",
+    "231c494ae7e43641797692e3d2869eaba9ad9a72320e7da5d63ce6c000fea061"
   ],
   ".agent-specs/templates/conventions/CONVENTION.md": [
-    "462a9cbf6c502f6692c9813a2da02e796a3547d02fb58058e2153bf4e3dc91d3",
-    "636e0b91189004f35c12da1d31bca6a26d5b6e6460547ac7b052f6dcfe4122c8",
-    "6f048a218b8fa094fe8d12ee1978d0600849db4d8142ca56502e986b5af7dfaa"
+    "0100029996755bf1f1cdf34e0d064807ee923256c5c84b0a98787fc067aae8a7",
+    "553894159720e718cb0a6938b758d65f9f55c7df3f8ccb969d632981c000cfad",
+    "66e57d4c939f9beeb596cc7094ede6436ec9d4096888196a6d8498474f8df445"
   ],
   ".agent-specs/templates/feature/ACCEPTANCE_MATRIX.md": [
-    "0efef77a6c06737d224289611ab9cd7640a987395bcb526fff4f4b5f86295753"
+    "2c4ced9eefb608d9dac68708a760b4425bafccb287dfd3701d16d4f416afa7a8",
+    "418ad2f5d8693d63d436e77b61d09a335919cbe7caad702c62e330cbfcc8bc2e",
+    "13465e7579dee1327232b4d2ca468b4c2dae7e988764a0149f9dfeb9febfa39f",
+    "38bf94015959e497a19487e25ba7165ec7dc8d984c38c3bf3e30628f80064432"
   ],
   ".agent-specs/templates/feature/DESIGN.md": [
-    "301b5b38817a3fa1f21d7ac1f9816f5edc294610322e82bbaf51898485a00934"
+    "67ab041fede40d545a8a1e39866648e0fbbea0dfcc754082e6484d90d4e9780d",
+    "6dd83ff2274e66b2d314d25f11aec77e05914b09a7df29ff8f36f38bead20e42",
+    "95b7b6f8930df17fba720217bbdfa49e4fbb130c2f26eed7628b80ed4e7b879c"
   ],
   ".agent-specs/templates/feature/HANDOFF.md": [
-    "5d089e10cd26341154f71262f1f7bbaf851ef42bdea73bf26a2c80cc647cc9dc"
+    "cd0531eec14496409f94b087ceb27d269dfb8feb8e9321b8075ed2ec15148794"
   ],
   ".agent-specs/templates/feature/PLAN.md": [
-    "8502cc0a36a3868f8f255863db7abd58b9626ae0b9a9c76875aa77441a0cac2c",
-    "e23d02f2b21676dcc9493eee8b2ec617b922a912e118762d6afe191ac391f826"
+    "41f8adea2769c825a4e50b82ab1c7f20249923fd8fd0cdb2f91a3c45626cd723",
+    "66e60c4ac70c18ff549a57691b73113dc0f015fcfefcbad537a20fe1213f3702",
+    "08bfa77df5a28778ea6ab9d8c44858c3fe37f6beb2719f38f30cfc314f80f147",
+    "23ee3da377f7f99718bfc846fa7e37e5b9470bbbf0f3ec08359d4a53756428dc"
   ],
   ".agent-specs/templates/feature/RESEARCH.md": [
-    "e68f104f0b35440da933573d7f04a861f62a8f8248a3156b975824d2cac40c53"
+    "667580dd935face184e8f8a8177a092bf8d146a9e60c9396fddbae2b64c9cb40",
+    "709450b00f6c0c0c25a78eccf4ecf2ac1a45a38951157d57eba5d3f63bcba9c5"
   ],
   ".agent-specs/templates/feature/TASKS.md": [
-    "0b6f660cb321bdbbeecd21af788e3954a01726bf111f079707fd927451ef49e7",
-    "a4c5de105bb6d474e2131994cb90fbcd4f3e436ba22b92a0f865755d00064d0d"
+    "aa8494ff4e045f8ab65f360654b0f2f4036c744dd72caa720e14436d48626fde",
+    "bed26521049b15acfbd80ebe226873d75c604f9d0c88238a3ecabb8a9dd73cac"
   ],
   ".agent-specs/templates/project/ARCHITECTURE.md": [
-    "3ed1a7ae1021f999fa7769f406f7de5e008d9f8c09e219214c817f580a1d9ae5"
+    "d4b2e5ed4449b70746b3dfd628e111edffbb69d7247267cab86e6d48c506943d",
+    "fa96b3a94003604b02c8ffdc617ab810b6c96b5df2b647f5b46ec53c35a4a1d3"
+  ],
+  ".agent-specs/templates/project/DEPLOYMENT.md": [
+    "0b2b7a20d49f096a1a9dc3b22f1796de2321cc13b016322b253a33e396458e7b"
   ],
   ".agent-specs/templates/project/GLOSSARY.md": [
-    "5f9109b0699879db0b6563e9df4889c3b0963893c43a1fd82a71f5f3d7327af9"
+    "7c70e97600adefb95611c1ba6f675291a5632bcb9e2e866cecc3267d7bc81bad",
+    "f84785fd38fb580ed923c212c1a803b9f4abedd1c799dc091fa1d4e854486d51"
+  ],
+  ".agent-specs/templates/project/PRODUCT.md": [
+    "551c8e3b48e4abe29dcac80dd7217674be01570d30de5b5603b71bcc6814b2e3"
+  ],
+  ".agent-specs/templates/project/TESTING.md": [
+    "7771a95ed6808dc14a06f422e17cb0bb87679cb2e60c67cb4bfbe4c6e552e72c"
+  ],
+  ".agent-specs/templates/project/VISUAL_DESIGN.md": [
+    "03b0ad8ab6d435f0de17585fd06d12d7f72eb27ca70281fb97c5d672a0e6210c"
   ],
   "AGENTS.md": [
-    "70196e937a5782962f69c2c0735929059fac6c60b724977ebbfea9d0e4c84b20",
-    "c08f3412d558b6992b0a2e003d5be0de201502846453c2b2da70c2d682d5815a",
-    "bc70d6dee9f3f76affb0636ff804a112885b0973aaa2753ac970fc83d0260b5e",
-    "a09404a3dce7e2c1f7aa0efce59c5b075943ad768a02b62dc51e08e44a050318",
-    "53776f37c6f55ece45c4b4d32d2a48749031c90e77047d9a730c3f150af0d79f",
-    "3753a29898a4209208fdbb8f1e9a3de206d845d95e60d8c543f48c2c239780bf"
+    "0eab3a77a396a41ea82ec3c2a6c459bffbeac5d4277342edb137d2c48a691412",
+    "18693b6856d66ab7ee2f035a5555d3311b8f3cf23a68ebe6af8cef0ddf03d557",
+    "3d56b1c3d2706168e23701cbf1fd914c59aa5ef5a53a455e95d5c8551e80aa59",
+    "7e7b110327268ab0e374bbee1cf115f1afb5541aaea447cbe28227121cd3a89e",
+    "ab68bb3e1415ce764e45debc529a7a87296e1164974f7873db45f1be44dcd81f",
+    "cc14da014a959578f7e28970f5168401dd653f97b16b3a81055c549a07c09c9c",
+    "cd231a977a879afa19301947a03f2ffb246240bc127fb00b7fedd516231936bc",
+    "d527b953d0f1d6fd805e9800ba4ba71db2e5e1c25dcdfe4bdbfc6706e1782314",
+    "f730107d9764f5a0a294124e04c9a5c89ecda9e6f3365afc9b0ca4a952dec1d1",
+    "9c8d3e7eb471911d0ca58bfd0331298effcee068f28b71f52373c05641c3bc93",
+    "94a8b845546e7f7564cac89ee73cdcb24ac4d54989c7a9f6c676e7e8066c64cd"
   ],
   "CLAUDE.md": [
-    "272bcb5a9f136af56c1c93203c21976e02a09ed0a59d2515fad23d24b6c34408"
+    "67de3db5b7413656ff1d221df90360fdfd0dd80608eb5dbae0416fecf359cbf8",
+    "e1bfd28d839af2ff6ec82759d888081a7c3fa2da2c20dbcfb144f533e0e3f982"
   ],
   "docs/WORKFLOW.md": [
-    "0712abf011e6632fcdaee95c9b0c7bcad39808b5d28678c25aa0c05d281f795f",
-    "637e83ce425e97ee9751a8500f5928d1f1ed2536e8d1a02b85bf6e11bc937192",
-    "9dd7762484311d7a2a59620d4e89c61e4eb68688d9ebe1b3e2f2ac6d114373fd",
-    "049b5a682f613a0bb2dab7bd39e79645860eb30202d358ed9a879dbe238e84bc",
-    "8f66846159f0f049af2035fd71be7b289cc999099ad2ac6c1aa3b61745754745",
-    "4e12aed278f410305dc640a9f9cb0fa5135e28b0963c2a9bc4a8b7810e4af63f"
+    "5a3595c9db922174f09983d691154b541b2974040e67bc97edfc6ccc7011ab9f",
+    "962d11a5e74312a28d3d3fb4c048f259108ea15cd9da9d2bbaf4a010a982b4ac",
+    "982ddc5918cd15fe945c32d32e16bd98f6d33ce836fba2e009e284e4b800834b",
+    "c80b35e94103071e51712155a3e343271a6599c62b655c821aca95c55218da4f",
+    "e737237b908dc482b01f07d69cc9c885216f5268a199863ab56203347af17564",
+    "ee6a539425172b2efc0477cbf2cf2b07fa0f5cc79d0b06a794e75922101b2961",
+    "ee972b6193146aef80b85fbb76a5289d651173032daa14fc5fe3744c3d36a930",
+    "6ae499a00796e17367c1c25bd5f162b040622aa1bcc4f0d39ba5efc8817bfbd3",
+    "59708748d05e26859c71eb9beab4f27b1e9dcded7bc4648d04bb35033b853022",
+    "70de8d1dc3a24c3bc293a696ad2b150c6d9dced69d0a5d03f54f3f7e275bfa33",
+    "05dd5854cb7a287ad2d39119c4f10b647415d2a6b01be0d7c6fe8427a012590c"
   ],
   "docs/adr/README.md": [
-    "2f27a4a5ecfb92725875c0b859194588b0ed367ac87b7d321ba063062abf25d5"
+    "1d2c05c11246d0d45592f930b3a339bf454363875b968f650165e91a906c95af"
   ],
   "docs/features/README.md": [
-    "a46ffb46dc49d5304db438179e6b090665d706d2f09c50c56bb2a0c09c92b5da",
-    "3fb7c6fa1177a5cb940e8066d18624ce0d32c76b945a9b1f183d8809f40a7275",
-    "ddf40d2b1fd1fb821799e59df15c4ab9ce9edf1e231b3fce5776ff3635c3ffaf"
+    "5b995d3af23bbb7eb44fc146690ded522a410deb7d54401b7fd3b8fc4f62c5a2",
+    "c871bd8bc6152615851bc2103429c699ba11f8da3cd8c167edc8510204b72bfe",
+    "ce489254e2001ad7a5f85ce23474e9e4765dfc6fcf6a43f780e425f2bdab86a5"
   ]
 }

package/lib/scaffold.js

@@ -54,10 +54,45 @@ function getBundledFiles(dir, base = dir) {
   }).sort();
 }
 
-export function initProject(target, { dryRun = false, log = console.log } = {}) {
+const profileFile = '.agent-specs/profile.json';
+export function projectProfile(target) {
+  const root = path.resolve(target);
+  const file = path.join(root, profileFile);
+  assertSafePath(root, file);
+  if (pathExists(file)) {
+    const { profile } = JSON.parse(fs.readFileSync(file, 'utf8'));
+    validateProfile(profile);
+    return profile;
+  }
+  return fs.existsSync(path.join(root, 'docs/WORKFLOW.md')) || fs.existsSync(path.join(root, '.agent-specs/templates')) ? 'opinionated' : undefined;
+}
+function validateProfile(profile) {
+  if (!['basic', 'opinionated'].includes(profile)) throw new Error('Profile must be basic or opinionated.');
+}
+function profileFiles(profile) {
+  validateProfile(profile);
+  return profile === 'basic' ? ['AGENTS.md', 'CLAUDE.md'] : getBundledFiles(bundledScaffold);
+}
+function profileContent(rel, profile) {
+  if (profile === 'basic' && rel === 'AGENTS.md') return fs.readFileSync(new URL('./basic-AGENTS.md', import.meta.url), 'utf8');
+  return fs.readFileSync(path.join(bundledScaffold, rel), 'utf8');
+}
+function saveProfile(root, profile, dryRun) {
+  if (!dryRun) {
+    fs.mkdirSync(path.join(root, '.agent-specs'), { recursive: true });
+    fs.writeFileSync(path.join(root, profileFile), JSON.stringify({ profile }, null, 2) + '\n');
+  }
+}
+
+export function initProject(target, { dryRun = false, profile, log = console.log } = {}) {
   const root = path.resolve(target);
   assertDirectory(root);
-  const files = getBundledFiles(bundledScaffold);
+  const existing = projectProfile(root);
+  profile ??= existing ?? 'basic';
+  validateProfile(profile);
+  if (existing && existing !== profile) throw new Error('Use update --profile to switch an existing installation.');
+  assertSafePath(root, path.join(root, profileFile));
+  const files = profileFiles(profile);
   const created = [];
   const skipped = [];
 
@@ -76,21 +111,21 @@ export function initProject(target, { dryRun = false, log = console.log } = {})
     if (!dryRun) {
       fs.mkdirSync(path.dirname(destination), { recursive: true });
       // Atomic no-clobber creation; existing work must never be overwritten.
-      fs.copyFileSync(path.join(bundledScaffold, rel), destination, fs.constants.COPYFILE_EXCL);
+      fs.writeFileSync(destination, profileContent(rel, profile), { flag: 'wx' });
     }
     created.push(rel);
     log(`${dryRun ? 'would create' : 'create'} ${rel}`);
   }
 
+  saveProfile(root, profile, dryRun);
+  log(`Profile: ${profile}`);
   log(`${dryRun ? 'Preview:' : 'Initialized:'} ${created.length} ${dryRun ? 'to create' : 'created'}, ${skipped.length} skipped.`);
   return { created, skipped };
 }
 
-// Identifies a file's content regardless of formatting, so a released file that a
-// formatter such as Prettier has rewritten (padding, emphasis markers) still matches.
+// Only exact released contents are safe to replace. Formatting can change meaning.
 export function fingerprint(content) {
-  const normalized = content.replace(/[\s*_-]/g, '');
-  return crypto.createHash('sha256').update(normalized).digest('hex');
+  return crypto.createHash('sha256').update(content).digest('hex');
 }
 
 export function getBundledFingerprints() {
@@ -100,18 +135,20 @@ export function getBundledFingerprints() {
   ]));
 }
 
-export function updateProject(target, { dryRun = false, force = false, log = console.log } = {}) {
+export function updateProject(target, { dryRun = false, force = false, profile, log = console.log } = {}) {
   const root = path.resolve(target);
   assertDirectory(root);
   const released = JSON.parse(fs.readFileSync(releasedFingerprintsFile, 'utf8'));
-  const files = getBundledFiles(bundledScaffold);
+  profile ??= projectProfile(root) ?? 'opinionated';
+  assertSafePath(root, path.join(root, profileFile));
+  const files = profileFiles(profile);
   const plan = [];
 
   // Decide every action before writing anything.
   for (const rel of files) {
     const destination = path.join(root, rel);
     assertSafePath(root, destination);
-    const incoming = fs.readFileSync(path.join(bundledScaffold, rel), 'utf8');
+    const incoming = profileContent(rel, profile);
     if (!pathExists(destination)) {
       plan.push({ rel, action: 'create', incoming });
       continue;
@@ -144,6 +181,8 @@ export function updateProject(target, { dryRun = false, force = false, log = con
     log(`${labels[action]} ${rel}${action === 'overwrite' ? ' (local changes discarded)' : ''}`);
   }
 
+  saveProfile(root, profile, dryRun);
+  log(`Profile: ${profile}`);
   const count = (...actions) => plan.filter((item) => actions.includes(item.action)).length;
   const modified = plan.filter((item) => item.action === 'modified').map((item) => item.rel);
   log(`${dryRun ? 'Preview:' : 'Updated:'} ${count('update', 'overwrite')} ${dryRun ? 'to update' : 'updated'}, ${count('create')} ${dryRun ? 'to create' : 'created'}, ${count('current')} already current, ${modified.length} skipped.`);
@@ -205,7 +244,7 @@ export function createFeature(target, title, {
   ))];
   // Ensure initialization and templates exist before changing the repository.
   if (!fs.existsSync(featuresDir) || !fs.statSync(featuresDir).isDirectory()) {
-    throw new Error('docs/features/ is missing. Run `scaffold-agent-specs init` first.');
+    throw new Error('docs/features/ is missing. Run `scaffold-agent-specs update --profile opinionated` first.');
   }
   for (const filename of files) {
     const template = path.join(templateDir, filename);
@@ -214,32 +253,49 @@ export function createFeature(target, title, {
       throw new Error(`Feature template missing: ${path.relative(root, template)}. Run init or restore the template.`);
     }
   }
-  const number = nextFeatureNumber(featuresDir);
-  const id = String(number).padStart(3, '0');
-  const name = `feature-${id}-${slug}`;
-  const featureDir = path.join(featuresDir, name);
-  assertSafePath(root, featureDir);
-  if (pathExists(featureDir)) throw new Error(`Feature directory already exists: ${featureDir}`);
-  const date = localDate();
-  const created = files.map((file) => path.join('docs', 'features', name, file));
+  // Serialize allocation across all titles, not just identical directory names.
+  const lock = path.join(featuresDir, '.agent-specs-feature.lock');
+  assertSafePath(root, lock);
   if (!dryRun) {
-    // Exclusive mkdir prevents two concurrent calls from sharing the same feature ID.
-    fs.mkdirSync(featureDir);
     try {
-      for (const file of files) {
-        const content = fs.readFileSync(path.join(templateDir, file), 'utf8');
-        fs.writeFileSync(path.join(featureDir, file), fillFeatureTemplate(content, { title: title.trim(), id, slug, date }), { flag: 'wx' });
-      }
+      fs.mkdirSync(lock);
     } catch (error) {
-      // A failed scaffold must not leave a half-created feature.
-      fs.rmSync(featureDir, { recursive: true, force: true });
+      if (error.code === 'EEXIST') {
+        throw new Error(`Feature creation is locked: ${lock}. Retry after the other command finishes. If it crashed, remove this lock directory only after confirming no feature command is running.`);
+      }
       throw error;
     }
   }
-  for (const file of created) log(`${dryRun ? 'would create' : 'create'} ${file}`);
-  log(`${dryRun ? 'Preview:' : 'Scaffolded:'} ${name} (${files.length} file${files.length === 1 ? '' : 's'}).`);
-  if (!dryRun) {
-    log('Next: fill the files with the approved feature scope, then stop before implementation.');
+  try {
+    const number = nextFeatureNumber(featuresDir);
+    const id = String(number).padStart(3, '0');
+    const name = `feature-${id}-${slug}`;
+    const featureDir = path.join(featuresDir, name);
+    assertSafePath(root, featureDir);
+    if (pathExists(featureDir)) throw new Error(`Feature directory already exists: ${featureDir}`);
+    const date = localDate();
+    const created = files.map((file) => path.join('docs', 'features', name, file));
+    if (!dryRun) {
+      // Exclusive mkdir also protects against an existing destination.
+      fs.mkdirSync(featureDir);
+      try {
+        for (const file of files) {
+          const content = fs.readFileSync(path.join(templateDir, file), 'utf8');
+          fs.writeFileSync(path.join(featureDir, file), fillFeatureTemplate(content, { title: title.trim(), id, slug, date }), { flag: 'wx' });
+        }
+      } catch (error) {
+        // A failed scaffold must not leave a half-created feature.
+        fs.rmSync(featureDir, { recursive: true, force: true });
+        throw error;
+      }
+    }
+    for (const file of created) log(`${dryRun ? 'would create' : 'create'} ${file}`);
+    log(`${dryRun ? 'Preview:' : 'Scaffolded:'} ${name} (${files.length} file${files.length === 1 ? '' : 's'}).`);
+    if (!dryRun) {
+      log('Next: fill the files with the approved feature scope, then stop before implementation.');
+    }
+    return { featureDir, created };
+  } finally {
+    if (!dryRun) fs.rmdirSync(lock);
   }
-  return { featureDir, created };
 }

package/package.json

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

package/scaffold/.agent-specs/templates/feature/ACCEPTANCE_MATRIX.md

@@ -5,6 +5,8 @@
 
 Each row must specify **observable behavior**, a verification method, and actual evidence. Write criteria when specifying the feature; update result and evidence during implementation. Do not mark `Pass` based solely on code inspection or optimism.
 
+When release or recovery checks are part of the approved scope, include rows for the relevant rollout, migration, post-release behavior, and recovery outcomes. Record the version, environment, command or observation, and evidence link. Passing local tests does not establish production success or recoverability. Required checks awaiting release stay `Not run` or `Blocked`; checks explicitly outside this feature's scope belong in the plan's release handoff, not in invented passing rows.
+
 | ID     | Requirement | Scenario / expected outcome                      | Verification method             | Result  | Evidence                     |
 | ------ | ----------- | ------------------------------------------------ | ------------------------------- | ------- | ---------------------------- |
 | AC-001 | FR-001      | [Given/when/then or clear expected result]       | [Test name or manual procedure] | Not run | [Add evidence when verified] |
@@ -19,6 +21,8 @@ Each row must specify **observable behavior**, a verification method, and actual
 
 If the user approves changing or waiving a criterion, update the approved scope in `PLAN.md` and document that decision explicitly. Do not silently convert a failing criterion into a pass.
 
+If a later feature supersedes this behavior, preserve these criteria, results, and evidence as historical records. Add a dated note under verification notes identifying the affected IDs and linking to the replacement feature's plan and acceptance matrix. A historical `Pass` does not verify the replacement; its matrix must record fresh evidence. See the supersession rules in `docs/WORKFLOW.md`.
+
 ## Verification notes
 
 [Commands, test environment, observations, limitations, and links to test reports. Leave as 'Not yet verified' during initial specification.]

package/scaffold/.agent-specs/templates/feature/DESIGN.md

@@ -37,4 +37,5 @@
 
 - Approved scope: [`PLAN.md`](./PLAN.md)
 - Requirements and checks: [`ACCEPTANCE_MATRIX.md`](./ACCEPTANCE_MATRIX.md)
+- [Shared visual design reference, if relevant; link to existing design-system documentation or `docs/VISUAL_DESIGN.md` rather than repeating shared rules]
 - [Any relevant convention, architecture documentation, or adopted ADR]

package/scaffold/.agent-specs/templates/feature/PLAN.md

@@ -47,6 +47,12 @@
 
 - [Dependency, prerequisite, migration risk, or 'None identified']
 
+## Release and recovery (when applicable)
+
+[Omit this section when there are no feature-specific release considerations. Otherwise link to the existing deployment/publishing guide and record only this feature's rollout order, compatibility constraints, data migrations, and recovery considerations. Identify irreversible steps, rollback limits, and the supported recovery or forward-fix approach; do not assume reverting code restores data.]
+
+[Define observable post-release checks and stop/recovery conditions. State whether release execution and live verification are in the approved scope or a later handoff. Map required checks to acceptance IDs and release work to tasks. Record prerequisites, authorization needed, and who owns deferred work; do not invent approvals or claim untested recovery works.]
+
 ## Assumptions and open questions
 
 - [Question or assumption; mark **Blocking** when implementation cannot responsibly proceed without an answer]
@@ -57,6 +63,12 @@
 | ------------ | ---------------------- | -------------------------------------------- |
 | [YYYY-MM-DD] | Initial approved scope | [Explicit approval reference / conversation] |
 
+## Related and superseded features
+
+[State 'None' if unrelated to earlier features. Otherwise link the relevant feature plans and identify the affected requirement and acceptance IDs, the behavior being replaced or extended, and what remains unchanged. Qualify IDs with their feature because IDs are local to each feature. Distinguish planned replacement from implemented supersession; approval alone does not replace existing behavior.]
+
+[When replacement is implemented, record its date and implementation reference here and add a reciprocal note to the earlier plan. Preserve the earlier scope and verification history; follow the supersession rules in docs/WORKFLOW.md.]
+
 ## References
 
 - Acceptance criteria: [`ACCEPTANCE_MATRIX.md`](./ACCEPTANCE_MATRIX.md)

package/scaffold/.agent-specs/templates/project/DEPLOYMENT.md

@@ -0,0 +1,27 @@
+# Release and Recovery Guide
+
+> **Optional project document.** Create under `docs/DEPLOYMENT.md` when recurring release, deployment, or recovery procedures need explanation beyond existing scripts, CI, publishing instructions, or runbooks. Reuse an adequate existing guide. Describe actual supported procedures and link to authoritative automation; do not invent infrastructure or claim untested recovery works. Omit irrelevant sections. Feature-specific rollout choices belong in the feature plan, and execution evidence belongs in its acceptance matrix or an existing release record.
+
+## Release targets and prerequisites
+
+[What is released or deployed, to which environments or registries, and from which artifact/version. Link to build and release automation. Identify prerequisites, required access, and who can authorize execution; do not include credentials. Documentation or feature approval alone does not authorize a deployment, publication, or production data change.]
+
+## Rollout procedure and compatibility
+
+[The supported sequence, commands or automation links, and checkpoints. Explain component ordering, version compatibility, feature flags, staged exposure, or downtime only where applicable. Identify stop conditions and how to determine which version is actually active.]
+
+## Data changes and migration
+
+[Migration ordering, compatibility with old and new application versions, backup requirements, and any irreversible steps. State 'Not applicable' if no persistent data is involved. Link to authoritative migration and restore procedures instead of copying them.]
+
+## Post-release verification
+
+[Observable smoke checks, health signals, logs or metrics, and their success/failure conditions. Identify when checks run and who follows up. Distinguish a successful build or deployment command from evidence that the released behavior works.]
+
+## Rollback and recovery
+
+[When to stop rollout or recover, who decides, the known-good artifact/configuration, and the supported procedure. Explain what reverting code does not undo, including data changes. If rollback is unavailable or unsafe, state that explicitly and describe the supported forward fix or recovery path and its limitations. Record where recovery was rehearsed and link to evidence, or label it unverified.]
+
+## Evidence and maintenance
+
+[Link to existing release/deployment records and recovery evidence. Record the version, environment, time, check results, and unresolved issues when executing a release. Keep reusable procedures here and feature-specific evidence in its acceptance matrix or linked release record. Update this guide when release automation, compatibility assumptions, or recovery procedures change.]

package/scaffold/.agent-specs/templates/project/PRODUCT.md

@@ -0,0 +1,27 @@
+# Product Context
+
+> **Optional project document.** Create under `docs/PRODUCT.md` when shared product context is not adequately explained by the README or existing product documentation. Reuse and link authoritative material instead of maintaining competing descriptions. Capture agreed context and current capabilities; do not invent product strategy or turn this document into a roadmap, backlog, or feature approval mechanism. Omit irrelevant sections.
+
+## Purpose and users
+
+[What problem the product solves, for whom, and in what setting. Distinguish primary users from other stakeholders where useful.]
+
+## Core journeys
+
+[The main outcomes users can achieve today and the important steps or boundaries of each journey. Link to current user documentation and relevant feature plans rather than copying detailed requirements.]
+
+## Product principles and constraints
+
+[Agreed principles that guide product tradeoffs, with their rationale and sources. Include enduring constraints only when established; do not infer commitments from a single implementation choice.]
+
+## Deliberate non-goals
+
+[Explicitly agreed exclusions and the reasons for them. Distinguish deliberate boundaries from capabilities that simply have not been built. Changes to these boundaries require scope discussion, not an unannounced documentation edit.]
+
+## Uncertainty and references
+
+[Identify unresolved questions as unresolved. Link to authoritative product material, user documentation, the glossary, and relevant decisions. Do not present assumptions or proposals as agreed context.]
+
+## Maintenance
+
+Update this reference when approved product direction or implemented core journeys change. Distinguish approved future direction from available behavior. Feature scope and approval remain in each feature's `PLAN.md`, progress in `TASKS.md`, and verification evidence in `ACCEPTANCE_MATRIX.md`.

package/scaffold/.agent-specs/templates/project/TESTING.md

@@ -0,0 +1,31 @@
+# Project Testing Guide
+
+> **Optional project document.** Create under `docs/TESTING.md` when verification setup or test selection needs explanation beyond existing scripts, CI, README, or contributing documentation. Reuse an existing guide when it already serves this purpose. Document the project's actual approach, not a hypothetical test strategy. Link to authoritative scripts and configuration rather than copying their implementation. Omit irrelevant sections.
+
+## Choosing checks
+
+| Change or risk   | Relevant checks and command           | Authoritative script / configuration   |
+| ---------------- | ------------------------------------- | -------------------------------------- |
+| [Type of change] | [Checks to run and working directory] | [Link to maintained command or CI job] |
+
+[Explain when focused checks suffice and when integration, end-to-end, build, or other checks are needed. Identify differences between local and CI verification. Do not prescribe new tooling without an agreed need.]
+
+## Setup and test data
+
+[Required runtimes, services, environment variable names, fixtures, seed data, and setup/cleanup procedures. Link to existing setup documentation. Describe how to obtain authorized test credentials without including secrets. Identify commands that modify data and the isolated test environment they require.]
+
+## Integration boundaries
+
+[Which checks use real services and which use substitutes, why those boundaries exist, and what a passing substituted test does not establish.]
+
+## Manual verification
+
+[Reproducible checks that automation does not cover, prerequisites such as devices or service access, and what evidence to record. Keep feature-specific expected outcomes in the feature's acceptance matrix.]
+
+## Known limitations and troubleshooting
+
+[Known environment restrictions, flaky checks, diagnostic steps, and any maintained issue references. Distinguish unavailable checks from product failures; a limitation does not justify reporting a pass or silently skipping required verification.]
+
+## Evidence and maintenance
+
+Record commands, results, and limitations for each feature in its `ACCEPTANCE_MATRIX.md`; this guide owns reusable verification procedures, not execution history. Update it when test setup, commands, or verification boundaries change.

package/scaffold/.agent-specs/templates/project/VISUAL_DESIGN.md

@@ -0,0 +1,28 @@
+# Visual Design
+
+> **Optional project document.** Create under `docs/VISUAL_DESIGN.md` when defining or changing shared visual conventions for a visual interface, unless existing design-system documentation already serves this purpose. Ground this reference in the existing interface and agreed direction. Clearly label proposed conventions separately from adopted ones. Omit irrelevant sections and link to authoritative code instead of copying values that can drift.
+
+## Visual direction
+
+[Describe the intended visual character, relevant references, and constraints.]
+
+## Foundations
+
+[Color roles, typography, spacing, and layout conventions. Link to authoritative tokens, styles, and assets.]
+
+## Components and states
+
+[Shared component styles and conventions for hover, focus, disabled, loading, empty, error, and success states. Link to existing components or examples.]
+
+## Responsive behavior, accessibility, and motion
+
+[Shared rules for adapting layouts, keyboard focus, contrast, readable content, motion, and reduced-motion preferences.]
+
+## Proposed changes and open questions
+
+[Unresolved visual choices, clearly separated from adopted conventions. Remove resolved entries or incorporate adopted choices above.]
+
+## References
+
+- [Authoritative tokens, styles, component library, or design assets]
+- [Feature designs for specific interactions; keep feature details there]

package/scaffold/AGENTS.md

@@ -1,67 +1,48 @@
 # Repository Agent Instructions
 
-These are the shared instructions for AI coding agents working in this repository. Keep tool-specific instructions (for example, Claude Code instructions) in their own thin adapter files rather than duplicating this document.
+These shared instructions apply to all coding agents. Keep tool-specific adapter files thin and link here instead of duplicating rules.
 
 ## Working principles
 
-- Read this file before working, and read [`docs/WORKFLOW.md`](docs/WORKFLOW.md) when discussing, specifying, implementing, or completing a feature.
-- Inspect relevant code, tests, and existing documentation before asking questions or proposing an approach. Don't ask for information the repository already answers.
-- Prefer the smallest coherent change. Follow existing project conventions and avoid unrelated refactors. Consult relevant documents in `docs/conventions/` when that directory exists.
-- Be transparent about assumptions, uncertainty, incomplete work, and failed or unrun checks. Never present unverified behavior as tested.
-- Use interactive question tools when available; otherwise ask in chat. Ask focused questions that materially affect scope, behavior, UX, data, security, or architecture. Propose sensible defaults for minor details.
+- Inspect relevant code, tests, and documentation before asking questions or proposing an approach. Do not ask for information the repository already answers.
+- Prefer the smallest coherent change, follow project conventions, and avoid unrelated refactors. Consult relevant `docs/conventions/` documents when present.
+- State assumptions, uncertainty, incomplete work, and failed or unrun checks honestly. Never claim unverified success.
+- Use interactive question tools when available, otherwise chat. Ask focused questions about consequential choices and choose sensible defaults for minor details.
 - Keep the human in control of scope and significant architectural tradeoffs.
 
 ## Feature workflow and approval gates
 
-For **new features**, follow this sequence:
+Read [`docs/WORKFLOW.md`](docs/WORKFLOW.md) when discussing, specifying, implementing, or completing a feature. It owns the detailed procedure and document contracts.
 
-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/`, 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.
+For new features:
 
-Existing-feature work and ordinary fixes should follow the user's requested scope; do not force a new feature directory for every small change.
+1. Discuss the problem and inspect the repository before proposing scope. Do not implement or create feature artifacts during discovery.
+2. Present scope, acceptance expectations, exclusions, and consequential open questions. Offer **accept / revise / discard**; obtain clear affirmative approval, including renewed approval after revisions.
+3. After approval, populate `PLAN.md`, `ACCEPTANCE_MATRIX.md`, and `TASKS.md` from the feature templates. Record approved scope faithfully and distinguish proposed technical choices from adopted decisions.
+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.
 
-### Scope changes and technical decisions
+Existing-feature work and ordinary fixes follow the user's requested scope; do not force a new feature directory for every small change.
 
-- 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 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.
+### Scope and decision boundaries
 
-## Feature documentation contracts
+- Ask before changing promised behavior, exclusions, or acceptance criteria, or adding an independent user-facing capability, however small.
+- 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.
 
-- **`PLAN.md`** explains _why and what_, including approved scope, requirements, constraints, risks, and the proposed technical direction.
-- **`ACCEPTANCE_MATRIX.md`** defines objectively verifiable outcomes and records methods, results, and evidence. Do not claim a pass without evidence.
-- **`TASKS.md`** is the authoritative checklist for implementation progress and holds the feature's lifecycle status. Keep items small and link them to acceptance IDs where practical.
-- **`DESIGN.md`** is optional detailed technical/interaction design, not a second feature specification.
-- **`RESEARCH.md`** is optional durable investigative findings, not an approved decision.
-- **`HANDOFF.md`** is optional, temporary context for a session or agent transition. It must never supersede the plan, acceptance matrix, or task checklist.
-- Feature directories use `feature-NNN-kebab-case`, with three-digit IDs starting at `001`. Choose the next number above the highest existing feature ID; never reuse a retired ID.
-- Use stable IDs such as `FR-001` (requirement), `AC-001` (acceptance), and `T-001` (task) so documents can cross-reference each other.
+## Documentation and completion
 
-## Documentation and architecture decisions
-
-- Update relevant documentation **in the same change** when code changes behavior, architecture, configuration, developer setup, or public interfaces. Documentation is part of done, not an optional follow-up.
-- Record durable, cross-cutting architectural decisions in `docs/adr/`. Use `.agent-specs/templates/adr/ADR.md` for the format; real ADRs start at `adr-001-...`.
-- An ADR records context, the adopted decision, alternatives and tradeoffs, consequences, and references. Avoid ADRs for routine local implementation details.
-- 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 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
-
-- Before claiming completion, run relevant tests, linters, type checks, and build checks supported by the repository, or explain precisely why they were not run.
-- Update acceptance results with concrete evidence (test name, command, output summary, or a reproducible manual check). Never infer a pass from implementation alone.
-- Keep `TASKS.md` synchronized with actual progress, including its status, which is the single lifecycle status for the feature. Do not mark blocked or incomplete work as done.
-- Call out unresolved failures, missing coverage, migrations, and follow-up work explicitly.
+- Update affected documentation in the same change as behavior, architecture, configuration, setup, or public-interface changes.
+- 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.
+- 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
 
-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. 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/CLAUDE.md

@@ -1,6 +1,4 @@
 # Claude Code Instructions
 
-1. **Always read and follow `AGENTS.md` before doing any work.** For feature work, also read `docs/WORKFLOW.md` and the relevant files in `docs/features/`.
-2. Treat `AGENTS.md` as the shared source of truth for repository workflow, documentation, verification, and commit style. Do not duplicate or override its instructions here.
-3. **Do not add AI attribution to Git commits.** In particular, do not add `Co-Authored-By: Claude` (or similar AI co-author trailers), `Generated with Claude Code`, or other AI attribution lines to commit messages. Do not append such trailers automatically when generating commits.
-4. Follow the human approval gates in `AGENTS.md`: approval of feature scope authorizes writing specs, **not** beginning implementation.
+1. **Read and follow `AGENTS.md` before doing any work.** It is the shared source of truth for workflow, documentation, verification, and Git practices.
+2. Follow any additional documentation referenced by `AGENTS.md`. Do not duplicate or override its instructions here.

package/scaffold/docs/WORKFLOW.md

@@ -4,10 +4,12 @@ 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.
+- Read existing code and documentation when relevant, then explore the user's idea collaboratively. Consult `docs/PRODUCT.md` or the existing product reference when present to understand users, core journeys, and agreed boundaries; it does not authorize new feature scope.
+- 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, approved scope, and any supersession notes rather than the whole folder. Follow relevant replacement links to understand current behavior. 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. Read `docs/TESTING.md` or the existing testing/contributing guide when present. If the project already has a test approach, follow it instead of asking.
+- For changes with release or data-recovery implications, inspect the existing deployment/publishing guide or runbook. Establish whether release execution and live verification are part of the requested scope or a later handoff.
 - 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 +23,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 +36,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,15 +55,21 @@ 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. Use stable requirement (`FR-001`), acceptance (`AC-001`), and task (`T-001`) IDs and cross-reference them 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.
+
+For applicable features, fill the plan's "Release and recovery" section: rollout order, compatibility, migrations, irreversible steps, recovery limits, and observable post-release checks. Link to shared procedures rather than copying them. Put required verification outcomes in `ACCEPTANCE_MATRIX.md` and execution work in `TASKS.md`; identify ownership and prerequisites for release work explicitly outside scope. Do not add a release process to features that do not need one.
+
+If the approved scope changes behavior owned by an earlier feature, fill the plan's "Related and superseded features" section using the rules below. Treat the relationship as planned until the replacement is implemented.
 
 **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.
 
 ## Phase 4: Implement (separate explicit request)
 
 - 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.
+- 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.
+- 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`.
 - If interrupted, add or refresh `HANDOFF.md` with the current task, blockers, commands run, and the next actionable step.
@@ -68,21 +78,53 @@ 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. 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.
+- 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.
+- For implemented replacements, reconcile supersession links and historical verification notes in the affected earlier features using the rules below. Apply this reconciliation to the active plan; preserve earlier specifications as historical records with explicit supersession notes.
+- Update affected user/developer/project documentation in the same change. Use the optional project document catalog below to identify relevant references and their ownership; maintain existing equivalents instead of creating duplicates.
+- Review the catalog for a missing document that has become useful and report only useful recommendations with a brief reason. Follow its creation policy rather than treating the catalog as a checklist of files to generate.
+- Report release state separately from implementation completion: distinguish locally verified, ready for release, and actually released behavior, naming the version/environment when known. Required release or recovery checks remain `Not run` or `Blocked` until evidenced; do not mark the feature complete while they remain required and unverified. If release is explicitly outside the approved scope, implementation may be complete once its acceptance criteria pass; record the remaining release work, owner (or unassigned ownership), and prerequisites in the plan and final handoff without claiming it shipped. Do not introduce a second feature lifecycle status.
 - 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.
+- 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.
 
+## 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.
+- **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.
+
+For example, if feature 012 replaces feature 003's CSV delimiter, both plans identify the affected requirement and acceptance IDs. Feature 003 retains its original delimiter test result with a note pointing to feature 012; feature 012 records its own evidence for the new delimiter. Other export behavior remains governed by the unchanged requirements.
+
+## Optional project document catalog
+
+This is the shared index for project-level documentation. The Phase 3 table covers feature-level optional files (`DESIGN.md`, `RESEARCH.md`, and `HANDOFF.md`). Templates are installed for reuse; initialization does not create the completed project documents below.
+
+Before creating a shared reference, check whether an existing README, contributing guide, design system, publishing guide, runbook, or other maintained source already serves the purpose. Use that source even if its filename differs. When a missing reference would help, recommend it and why; create it when the user agrees or has already authorized it as part of the work. Do not repeat an approval request already answered. Updating an existing affected reference is part of completing the change. ADRs follow their adoption rule below, not a separate optional-document approval gate.
+
+| Document                         | When it adds value                                                                                                                     | Ownership and use                                                                                                                                                                                                                                                       |
+| -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `docs/ARCHITECTURE.md`           | The implemented system needs an overview of components, boundaries, and data flows.                                                    | Read for cross-cutting implementation work; update when the system changes. Describe current architecture and link to ADRs for rationale.                                                                                                                               |
+| `docs/GLOSSARY.md`               | Domain terms recur across features or are easily confused.                                                                             | Own precise shared meanings; consult during specification and update when domain language changes.                                                                                                                                                                      |
+| `docs/VISUAL_DESIGN.md`          | Shared visual conventions are being defined or changed and no existing design-system reference suffices.                               | Read before UI work; maintain shared conventions when they change. Ground them in the interface and agreed direction, distinguish proposals from adopted rules, and leave feature-specific interactions in `DESIGN.md`.                                                 |
+| `docs/TESTING.md`                | Verification setup, check selection, or integration boundaries need explanation beyond scripts and CI.                                 | Read before planning/running verification; maintain reusable procedures and limitations. Scripts/CI own executable commands; feature matrices own results.                                                                                                              |
+| `docs/PRODUCT.md`                | Users, purpose, core journeys, principles, or deliberate non-goals are unclear from existing documentation.                            | Read before scope decisions; update for agreed direction or implemented journey changes. Distinguish current capabilities from future direction and proposals. This is not a roadmap or feature approval mechanism.                                                     |
+| `docs/DEPLOYMENT.md`             | Recurring release, deployment, or recovery procedures need explanation beyond existing automation or publishing/runbook documentation. | Read for release-impacting changes; maintain rollout order, compatibility, migrations, post-release checks, and recovery limits. Feature plans own deviations; matrices or linked release records own execution evidence. Procedures do not grant execution permission. |
+| `docs/conventions/<topic>.md`    | A stable, non-obvious rule applies across features and is not adequately enforced or documented elsewhere.                             | Read for relevant changes; maintain reusable rules. Tooling owns mechanically enforced rules; feature plans or ADRs own feature-specific decisions.                                                                                                                     |
+| `docs/adr/adr-NNN-kebab-case.md` | A significant architectural decision has actually been adopted.                                                                        | Record rationale at adoption under the agreed workflow; preserve history and link superseding decisions. Keep unimplemented proposals in feature plans.                                                                                                                 |
+
+Use `.agent-specs/templates/project/` for the six named project references, `templates/conventions/CONVENTION.md` for conventions, and `templates/adr/ADR.md` for decisions (all under `.agent-specs/`). Fill templates from actual project context and remove irrelevant guidance; never create empty documents merely because a template exists.
+
 ## Maintaining the source of truth
 
 - `PLAN.md` owns agreed scope, not task completion.
 - `ACCEPTANCE_MATRIX.md` owns acceptance and verification evidence, not general project notes.
 - `TASKS.md` owns implementation progress and the feature's lifecycle status, not architectural rationale.
-- `DESIGN.md`, if present, owns detailed technical and UX design, not user-approved scope.
+- `DESIGN.md`, if present, owns detailed technical and UX design, not user-approved scope. Link to the project visual design reference for shared conventions.
 - `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, 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/`.
+- Shared project references and ADRs follow the ownership and maintenance rules in the optional project document catalog above. Feature-specific release plans and exceptions stay in `PLAN.md`; verification evidence stays in `ACCEPTANCE_MATRIX.md` or its linked release records.
 
 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.