scaffold-agent-specs 0.1.1 → 0.1.3

package/README.md

@@ -62,6 +62,8 @@ npx scaffold-agent-specs feature "Account dashboard" --approved --design --resea
 
 **Important:** The CLI copies and personalizes headings, IDs, titles, and dates. It **does not invent a feature spec**. Your coding agent must populate the remaining placeholders from the approved conversation, then **stop** until you separately authorize implementation. The `--approved` flag is an acknowledgment; the CLI cannot verify the conversation itself.
 
+The `feature` command is a convenience for people. Agents are told to create feature directories by copying the templates themselves, following the steps in `docs/WORKFLOW.md`, so they don't depend on the CLI being installed or reachable from a sandbox.
+
 ## `init` installs
 
 ```text
@@ -87,6 +89,9 @@ No speculative feature, ADR, architecture document, glossary, or convention docu
 | --- | --- |
 | `init` | Copy the initial scaffold into the current directory. Never overwrite existing files. |
 | `init --dry-run` | Preview which files would be created or skipped. |
+| `update` | Bring scaffold files up to this version. Replace only files that are unmodified; skip customized ones. |
+| `update --dry-run` | Preview which files would be updated, created, or skipped. |
+| `update --force` | Also overwrite customized scaffold files, discarding local changes. |
 | `feature "Title" --approved` | Create the next `feature-NNN-title/` and its three required docs. |
 | `feature "Title" --approved --design` | Include optional detailed design. |
 | `feature "Title" --approved --research` | Include optional research. |
@@ -95,7 +100,16 @@ 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 modified ones. Before updating the scaffold in a future release, review the changes and merge into customized files manually. `init` refuses to write through symlinked paths under the chosen root.
+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.
+
+## Updating an existing repository
+
+```sh
+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.
 
 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.
 
@@ -103,6 +117,8 @@ There is intentionally no `implement` command: an agent should follow `AGENTS.md
 
 ```sh
 npm test                # Built-in Node.js test runner
+npm run format          # Format scaffold Markdown with Prettier
+npm run fingerprints    # Record scaffold fingerprints for `update` (before each release)
 npm run pack:check      # Preview npm-published file manifest
 npm pack                # Produce local npm tarball for testing
 ```

package/lib/cli.js

@@ -1,11 +1,12 @@
 import fs from 'node:fs';
 import { fileURLToPath } from 'node:url';
-import { initProject, createFeature } from './scaffold.js';
+import { initProject, createFeature, updateProject } 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 feature "Feature title" --approved [options]
   scaffold-agent-specs --version
   scaffold-agent-specs --help
@@ -18,9 +19,16 @@ Options for feature:
   --dry-run     Preview without writing; approval not required for a preview
   --dir PATH    Target repository root (default: current directory)
 
+Options for update:
+  --dry-run     Preview without writing
+  --force       Also overwrite files that were modified locally
+  --dir PATH    Target repository root (default: current directory)
+
 The CLI copies templates, but does not generate a specification or implement code.
 Your agent must fill the documents from the approved discussion and stop before implementation.
-Existing files are never overwritten by init.
+Existing files are never overwritten by init. update replaces only files that
+still match a released version; locally modified files are skipped unless --force.
+Feature documents in docs/features/feature-*/ are never touched.
 `;
 
 export function run(args) {
@@ -34,12 +42,16 @@ export function run(args) {
     return;
   }
   const [command, ...rest] = args;
-  if (!['init', 'feature'].includes(command)) throw new Error(`Unknown command: ${command}. Try --help.`);
+  if (!['init', 'update', 'feature'].includes(command)) throw new Error(`Unknown command: ${command}. Try --help.`);
 
   const flags = new Set();
   const positionals = [];
   let dir = process.cwd();
-  const allowed = command === 'init' ? new Set(['--dry-run']) : new Set(['--dry-run', '--approved', '--design', '--research', '--handoff']);
+  const allowed = new Set({
+    init: ['--dry-run'],
+    update: ['--dry-run', '--force'],
+    feature: ['--dry-run', '--approved', '--design', '--research', '--handoff'],
+  }[command]);
 
   for (let i = 0; i < rest.length; i++) {
     const argument = rest[i];
@@ -62,6 +74,11 @@ export function run(args) {
     initProject(dir, { 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') });
+    return;
+  }
   if (!positionals.length) throw new Error('Missing feature title. Try `feature "User statistics page" --approved`.');
   createFeature(dir, positionals.join(' '), {
     approved: flags.has('--approved'),

package/lib/released-fingerprints.json

@@ -0,0 +1,56 @@
+{
+  ".agent-specs/templates/adr/ADR.md": [
+    "6bdd5aa7149e0e3a53ddf1ff3fc067c3797e0c9942844cbb00b34c228204183c"
+  ],
+  ".agent-specs/templates/conventions/CONVENTION.md": [
+    "462a9cbf6c502f6692c9813a2da02e796a3547d02fb58058e2153bf4e3dc91d3"
+  ],
+  ".agent-specs/templates/feature/ACCEPTANCE_MATRIX.md": [
+    "0efef77a6c06737d224289611ab9cd7640a987395bcb526fff4f4b5f86295753"
+  ],
+  ".agent-specs/templates/feature/DESIGN.md": [
+    "301b5b38817a3fa1f21d7ac1f9816f5edc294610322e82bbaf51898485a00934"
+  ],
+  ".agent-specs/templates/feature/HANDOFF.md": [
+    "5d089e10cd26341154f71262f1f7bbaf851ef42bdea73bf26a2c80cc647cc9dc"
+  ],
+  ".agent-specs/templates/feature/PLAN.md": [
+    "8502cc0a36a3868f8f255863db7abd58b9626ae0b9a9c76875aa77441a0cac2c",
+    "e23d02f2b21676dcc9493eee8b2ec617b922a912e118762d6afe191ac391f826"
+  ],
+  ".agent-specs/templates/feature/RESEARCH.md": [
+    "e68f104f0b35440da933573d7f04a861f62a8f8248a3156b975824d2cac40c53"
+  ],
+  ".agent-specs/templates/feature/TASKS.md": [
+    "0b6f660cb321bdbbeecd21af788e3954a01726bf111f079707fd927451ef49e7",
+    "a4c5de105bb6d474e2131994cb90fbcd4f3e436ba22b92a0f865755d00064d0d"
+  ],
+  ".agent-specs/templates/project/ARCHITECTURE.md": [
+    "3ed1a7ae1021f999fa7769f406f7de5e008d9f8c09e219214c817f580a1d9ae5"
+  ],
+  ".agent-specs/templates/project/GLOSSARY.md": [
+    "5f9109b0699879db0b6563e9df4889c3b0963893c43a1fd82a71f5f3d7327af9"
+  ],
+  "AGENTS.md": [
+    "70196e937a5782962f69c2c0735929059fac6c60b724977ebbfea9d0e4c84b20",
+    "c08f3412d558b6992b0a2e003d5be0de201502846453c2b2da70c2d682d5815a",
+    "bc70d6dee9f3f76affb0636ff804a112885b0973aaa2753ac970fc83d0260b5e",
+    "a09404a3dce7e2c1f7aa0efce59c5b075943ad768a02b62dc51e08e44a050318"
+  ],
+  "CLAUDE.md": [
+    "272bcb5a9f136af56c1c93203c21976e02a09ed0a59d2515fad23d24b6c34408"
+  ],
+  "docs/WORKFLOW.md": [
+    "0712abf011e6632fcdaee95c9b0c7bcad39808b5d28678c25aa0c05d281f795f",
+    "637e83ce425e97ee9751a8500f5928d1f1ed2536e8d1a02b85bf6e11bc937192",
+    "9dd7762484311d7a2a59620d4e89c61e4eb68688d9ebe1b3e2f2ac6d114373fd"
+  ],
+  "docs/adr/README.md": [
+    "2f27a4a5ecfb92725875c0b859194588b0ed367ac87b7d321ba063062abf25d5"
+  ],
+  "docs/features/README.md": [
+    "a46ffb46dc49d5304db438179e6b090665d706d2f09c50c56bb2a0c09c92b5da",
+    "3fb7c6fa1177a5cb940e8066d18624ce0d32c76b945a9b1f183d8809f40a7275",
+    "ddf40d2b1fd1fb821799e59df15c4ab9ce9edf1e231b3fce5776ff3635c3ffaf"
+  ]
+}

package/lib/scaffold.js

@@ -1,8 +1,10 @@
+import crypto from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 export const bundledScaffold = fileURLToPath(new URL('../scaffold/', import.meta.url));
+export const releasedFingerprintsFile = fileURLToPath(new URL('./released-fingerprints.json', import.meta.url));
 const requiredFeatureFiles = ['PLAN.md', 'ACCEPTANCE_MATRIX.md', 'TASKS.md'];
 const optionalFeatureFiles = ['DESIGN.md', 'RESEARCH.md', 'HANDOFF.md'];
 
@@ -84,6 +86,74 @@ export function initProject(target, { dryRun = false, log = console.log } = {})
   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.
+export function fingerprint(content) {
+  const normalized = content.replace(/[\s*_-]/g, '');
+  return crypto.createHash('sha256').update(normalized).digest('hex');
+}
+
+export function getBundledFingerprints() {
+  return Object.fromEntries(getBundledFiles(bundledScaffold).map((rel) => [
+    rel.split(path.sep).join('/'),
+    fingerprint(fs.readFileSync(path.join(bundledScaffold, rel), 'utf8')),
+  ]));
+}
+
+export function updateProject(target, { dryRun = false, force = false, log = console.log } = {}) {
+  const root = path.resolve(target);
+  assertDirectory(root);
+  const released = JSON.parse(fs.readFileSync(releasedFingerprintsFile, 'utf8'));
+  const files = getBundledFiles(bundledScaffold);
+  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');
+    if (!pathExists(destination)) {
+      plan.push({ rel, action: 'create', incoming });
+      continue;
+    }
+    if (!fs.statSync(destination).isFile()) throw new Error(`Not a file: ${destination}`);
+    const current = fingerprint(fs.readFileSync(destination, 'utf8'));
+    const known = released[rel.split(path.sep).join('/')] ?? [];
+    if (current === fingerprint(incoming)) plan.push({ rel, action: 'current' });
+    else if (known.includes(current)) plan.push({ rel, action: 'update', incoming });
+    else if (force) plan.push({ rel, action: 'overwrite', incoming });
+    else plan.push({ rel, action: 'modified' });
+  }
+
+  const labels = {
+    create: dryRun ? 'would create' : 'create',
+    update: dryRun ? 'would update' : 'update',
+    overwrite: dryRun ? 'would overwrite' : 'overwrite',
+  };
+  for (const { rel, action, incoming } of plan) {
+    if (action === 'current') continue;
+    if (action === 'modified') {
+      log(`skip   ${rel} (modified locally)`);
+      continue;
+    }
+    if (!dryRun) {
+      const destination = path.join(root, rel);
+      fs.mkdirSync(path.dirname(destination), { recursive: true });
+      fs.writeFileSync(destination, incoming);
+    }
+    log(`${labels[action]} ${rel}${action === 'overwrite' ? ' (local changes discarded)' : ''}`);
+  }
+
+  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.`);
+  if (modified.length) {
+    log('Skipped files differ from every released version, so they were left alone.');
+    log(`Compare them with the new versions in ${bundledScaffold} and merge by hand, or rerun with --force to overwrite them.`);
+  }
+  return { plan: plan.map(({ rel, action }) => ({ rel, action })), modified };
+}
+
 export function slugify(value) {
   const slug = value.normalize('NFKD').replace(/[\u0300-\u036f]/g, '')
     .toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "scaffold-agent-specs",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "A tiny, spec-driven workflow scaffold for AI coding agents",
   "type": "module",
   "license": "MIT",
@@ -18,7 +18,10 @@
   },
   "scripts": {
     "test": "node --test",
-    "pack:check": "npm pack --dry-run"
+    "pack:check": "npm pack --dry-run",
+    "format": "npx --yes prettier@3 --write \"scaffold/**/*.md\"",
+    "format:check": "npx --yes prettier@3 --check \"scaffold/**/*.md\"",
+    "fingerprints": "node scripts/record-fingerprints.js"
   },
   "keywords": [
     "agents",
@@ -28,5 +31,13 @@
     "claude-code",
     "codex"
   ],
-  "author": "rob-pasc"
+  "author": "rob-pasc",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rob-pasc/scaffold-agent-specs.git"
+  },
+  "homepage": "https://github.com/rob-pasc/scaffold-agent-specs#readme",
+  "bugs": {
+    "url": "https://github.com/rob-pasc/scaffold-agent-specs/issues"
+  }
 }

package/scaffold/.agent-specs/templates/adr/ADR.md

@@ -13,14 +13,14 @@
 
 ## Decision
 
-[State the decision *actually adopted*, its boundaries, and the principal rationale.]
+[State the decision _actually adopted_, its boundaries, and the principal rationale.]
 
 ## Alternatives considered
 
-| Alternative | Benefits | Why not chosen |
-| --- | --- | --- |
-| [Option A] | [Benefits] | [Tradeoffs] |
-| [Option B] | [Benefits] | [Tradeoffs] |
+| Alternative | Benefits   | Why not chosen |
+| ----------- | ---------- | -------------- |
+| [Option A]  | [Benefits] | [Tradeoffs]    |
+| [Option B]  | [Benefits] | [Tradeoffs]    |
 
 ## Consequences
 

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

@@ -5,10 +5,10 @@
 
 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.
 
-| 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] |
-| AC-002 | FR-002 | [Expected result, including important edge case] | [Test name or manual procedure] | Not run | [Add evidence when verified] |
+| 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] |
+| AC-002 | FR-002      | [Expected result, including important edge case] | [Test name or manual procedure] | Not run | [Add evidence when verified] |
 
 ## Result legend
 

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

@@ -27,7 +27,7 @@
 
 ## Alternatives and tradeoffs
 
-[Material design options and reasons for preferring the proposed one. Significant project-wide *adopted* choices should be recorded later as ADRs.]
+[Material design options and reasons for preferring the proposed one. Significant project-wide _adopted_ choices should be recorded later as ADRs.]
 
 ## Open technical decisions
 

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

@@ -3,10 +3,8 @@
 - **Feature ID:** `feature-NNN-kebab-case`
 - **Scope status:** Approved by user
 - **Scope approval date:** [YYYY-MM-DD]
-- **Implementation status:** Not started
-- **Technical readiness:** To be assessed before implementation
 
-> Replace bracketed prompts with specifics from the approved discussion. This file records *scope and intent*, not a claim that a technical design has been accepted.
+> Replace bracketed prompts with specifics from the approved discussion. This file records _scope and intent_, not a claim that a technical design has been accepted. Track progress in `TASKS.md`, not here.
 
 ## Summary
 
@@ -35,7 +33,7 @@
 
 ## Non-functional requirements and constraints
 
-[Performance, accessibility, security, privacy, compatibility, operational or design constraints *actually relevant* to this feature. State 'None identified' if appropriate.]
+[Performance, accessibility, security, privacy, compatibility, operational or design constraints _actually relevant_ to this feature. State 'None identified' if appropriate.]
 
 ## User journeys and edge cases
 
@@ -55,8 +53,8 @@
 
 ## Scope change log
 
-| Date | Change | User approval |
-| --- | --- | --- |
+| Date         | Change                 | User approval                                |
+| ------------ | ---------------------- | -------------------------------------------- |
 | [YYYY-MM-DD] | Initial approved scope | [Explicit approval reference / conversation] |
 
 ## References

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

@@ -15,9 +15,9 @@
 
 ## Alternatives evaluated
 
-| Option | Evidence / strengths | Limitations / risks |
-| --- | --- | --- |
-| [Option A] | [Evidence] | [Risks] |
+| Option     | Evidence / strengths | Limitations / risks |
+| ---------- | -------------------- | ------------------- |
+| [Option A] | [Evidence]           | [Risks]             |
 
 ## Recommendation and confidence
 

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

@@ -1,10 +1,18 @@
 # Implementation Tasks: [Feature title]
 
 - **Feature ID:** `feature-NNN-kebab-case`
-- **Status:** Not started
+- **Status:** Specified
 
 This is the **authoritative progress checklist**. Draft ordered, independently verifiable tasks after scope approval. Map tasks to acceptance criteria where practical. Check a task only after its work is actually complete.
 
+`Status` above is the feature's only lifecycle status. Use one of:
+
+- `Specified`: specs written; readiness not yet checked.
+- `Ready`: readiness checked before implementation; remaining blockers are listed below.
+- `In progress`: implementation underway.
+- `Implemented (verification pending)`: tasks done, but some acceptance criteria are not yet `Pass`.
+- `Complete`: every acceptance criterion is `Pass`, or the user has explicitly accepted the exceptions.
+
 ## Tasks
 
 - [ ] **T-001:** [First actionable implementation step] (supports `AC-001`)

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

@@ -1,6 +1,6 @@
 # Architecture Overview
 
-> **Optional project document.** Create under `docs/ARCHITECTURE.md` when the system is complex enough to benefit from a maintained overview. Describe the *current implemented system*, not hypothetical future architecture. Refer to ADRs for the reasons behind lasting choices.
+> **Optional project document.** Create under `docs/ARCHITECTURE.md` when the system is complex enough to benefit from a maintained overview. Describe the _current implemented system_, not hypothetical future architecture. Refer to ADRs for the reasons behind lasting choices.
 
 ## System at a glance
 
@@ -8,9 +8,9 @@
 
 ## Components and responsibilities
 
-| Component | Responsibility | Key dependencies |
-| --- | --- | --- |
-| [Component] | [Responsibility] | [Dependencies] |
+| Component   | Responsibility   | Key dependencies |
+| ----------- | ---------------- | ---------------- |
+| [Component] | [Responsibility] | [Dependencies]   |
 
 ## Important data and request flows
 

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

@@ -2,9 +2,9 @@
 
 > **Optional project document.** Create under `docs/GLOSSARY.md` when the domain has terms whose precise meaning matters across features. Prefer a short, authoritative definition over repeated explanations in feature plans.
 
-| Term | Meaning in this project | Notes / related terms |
-| --- | --- | --- |
-| [Domain term] | [Precise definition] | [Distinctions, links, examples if useful] |
+| Term          | Meaning in this project | Notes / related terms                     |
+| ------------- | ----------------------- | ----------------------------------------- |
+| [Domain term] | [Precise definition]    | [Distinctions, links, examples if useful] |
 
 ## Usage notes (if needed)
 

package/scaffold/AGENTS.md

@@ -18,7 +18,7 @@ For **new features**, follow this sequence:
 1. **Discover:** Discuss the idea with the user. Understand the problem, users, expected behavior, constraints, boundaries, and unresolved questions. Do not implement the feature or create its feature directory during discovery.
 2. **Propose:** Present a concise scope summary covering the goal, in-scope and out-of-scope behavior, important acceptance outcomes, assumptions, and consequential open questions. Explicitly offer **accept / revise / discard**.
 3. **Get approval:** Treat only a clear, affirmative user response as scope approval. If the user revises the proposal, summarize the revised scope and seek approval again. If discarded, do not create feature artifacts.
-4. **Specify:** After approval, create `docs/features/feature-NNN-kebab-case/` and populate `PLAN.md`, `ACCEPTANCE_MATRIX.md`, and `TASKS.md` from `.agent-specs/templates/feature/`. You may run `scaffold-agent-specs feature "Title" --approved` (or its `npx` equivalent) to create files; the CLI does not write the approved requirements for you. Add `DESIGN.md` for substantial UX/technical design and `RESEARCH.md` for findings worth preserving, only when needed. Create `HANDOFF.md` when a real session handoff is useful. Record the approved scope faithfully. Mark proposed technical choices as proposed, not approved.
+4. **Specify:** After approval, create `docs/features/feature-NNN-kebab-case/` and populate `PLAN.md`, `ACCEPTANCE_MATRIX.md`, and `TASKS.md` from `.agent-specs/templates/feature/`, following the steps in [`docs/WORKFLOW.md`](docs/WORKFLOW.md) (Phase 3). Add `DESIGN.md` for substantial UX/technical design and `RESEARCH.md` for findings worth preserving, only when needed. Create `HANDOFF.md` when a real session handoff is useful. Record the approved scope faithfully. Mark proposed technical choices as proposed, not approved.
 5. **Stop at the spec boundary:** After writing the feature documents, summarize what was created and stop. **Do not start implementation** until the user explicitly requests it, possibly in a later session.
 6. **Implement and verify:** On an explicit implementation request, review the feature documents and relevant code. Resolve blockers, surface consequential technical choices, then execute tasks, validate acceptance criteria, and keep the documents current.
 7. **Finish:** Update related documentation, capture architectural decisions actually adopted, report verification evidence and remaining limitations, and mark the feature complete only when acceptance criteria are satisfied or exceptions explicitly accepted by the user.
@@ -28,14 +28,14 @@ Existing-feature work and ordinary fixes should follow the user's requested scop
 ### Scope changes and technical decisions
 
 - An approved feature scope is the baseline. Ask for renewed approval before materially changing promised behavior, exclusions, or acceptance criteria.
-- Technical implementation details can evolve within that scope. Surface decisions that introduce major dependencies, migrations, security implications, substantial complexity, or broad architectural consequences before committing to them.
+- Technical implementation details can evolve within that scope. Surface decisions that introduce major dependencies, migrations that modify or delete existing data, security implications, substantial complexity, or broad architectural consequences before committing to them.
 - Keep proposed decisions in the feature `PLAN.md`. Add a project-wide ADR **when a significant architectural decision has actually been adopted**, typically after implementation. For consequential decisions adopted earlier, record the ADR at adoption rather than losing the rationale. Never turn an unimplemented proposal into an accepted ADR.
 
 ## Feature documentation contracts
 
-- **`PLAN.md`** explains *why and what*, including approved scope, requirements, constraints, risks, and the proposed technical direction.
+- **`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. Keep items small and link them to acceptance IDs where practical.
+- **`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.
@@ -50,16 +50,22 @@ 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/`. 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/`. 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. Do not mark blocked or incomplete work as done.
+- 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.
 
-## Git commit conventions
+## 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.
+
+- 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.
+- Don't push, rewrite or amend existing history, or change branches without the user's request.
 
 Use **Conventional Commit-style** subjects with a meaningful scope:
 
@@ -74,7 +80,6 @@ Use **Conventional Commit-style** subjects with a meaningful scope:
 - Use a lowercase type and a short, recognizable scope (app, package, or subsystem). Write an imperative, descriptive subject; aim to stay within 72 characters.
 - For nontrivial changes, write a **prose body** explaining the substance and rationale, not a dump of filenames or generic boilerplate. Separate the subject and body with a blank line, and wrap prose at roughly 72–80 columns.
 - Keep commits focused and truthful. Note breaking changes explicitly when applicable.
-- Do not create a commit unless the user requests it or has explicitly authorized committing as part of the current task.
 
 Example:
 

package/scaffold/docs/WORKFLOW.md

@@ -29,16 +29,26 @@ Ask the user to **accept, revise, or discard**.
 
 ## Phase 3: Specify (after accepted scope)
 
-Choose `feature-NNN-kebab-case`, using the next available ID above the current maximum (starting with `001`). Once the user approves, optionally use `scaffold-agent-specs feature "Title" --approved` (or its `npx` equivalent) to create the directory from templates. The flag acknowledges explicit approval; the CLI does not verify the conversation or write the actual scope. Create the directory and populate:
+Create the feature directory by hand:
 
-| File | Purpose | Required? |
-| --- | --- | --- |
-| `PLAN.md` | Approved product scope, requirements, constraints, proposed technical approach | Yes |
-| `ACCEPTANCE_MATRIX.md` | Testable criteria plus verification methods, results, and evidence | Yes |
-| `TASKS.md` | Ordered, actionable implementation checklist, mapped to criteria | Yes |
-| `DESIGN.md` | Detailed technical/UX design when complexity warrants it | Optional |
-| `RESEARCH.md` | Durable findings from meaningful investigation | Optional |
-| `HANDOFF.md` | Short-lived context for work that will resume elsewhere | Only if useful |
+1. **Number:** find the highest `NNN` among the existing `docs/features/feature-NNN-*` directories and add one (start at `001`). Never reuse a number.
+2. **Name:** `docs/features/feature-NNN-kebab-case/`, where `kebab-case` is a short slug of the feature title (for example `feature-007-user-statistics-page`).
+3. **Copy:** `PLAN.md`, `ACCEPTANCE_MATRIX.md`, and `TASKS.md` from `.agent-specs/templates/feature/`, plus any optional templates needed (see the table below).
+4. **Fill identifiers:** in every copied file, replace `feature-NNN-kebab-case` with the directory name, the `NNN` in `Feature NNN:` with the number, `[Feature title]` with the title, and `[YYYY-MM-DD]` with today's date.
+5. **Fill content:** replace every remaining bracketed prompt, such as `[First actionable implementation step]`, with content from the approved discussion, and delete template guidance that doesn't apply. No prompts may remain.
+
+(The `scaffold-agent-specs feature` command performs steps 1–4 for people who prefer it; agents don't need it.)
+
+Required and optional documents:
+
+| File                   | Purpose                                                                        | Required?      |
+| ---------------------- | ------------------------------------------------------------------------------ | -------------- |
+| `PLAN.md`              | Approved product scope, requirements, constraints, proposed technical approach | Yes            |
+| `ACCEPTANCE_MATRIX.md` | Testable criteria plus verification methods, results, and evidence             | Yes            |
+| `TASKS.md`             | Ordered, actionable implementation checklist, mapped to criteria               | Yes            |
+| `DESIGN.md`            | Detailed technical/UX design when complexity warrants it                       | Optional       |
+| `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.
 
@@ -47,8 +57,8 @@ Write the approved scope into `PLAN.md`. Draft acceptance criteria and tasks tha
 ## 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.
-- Seek human input before significant new dependencies, migrations, security-sensitive choices, or changes to approved behavior. Technical refinement that stays within scope usually needs no additional approval.
+- Check readiness: requirements coherent, blockers identified, implementation direction sensible, verification approach practical. Record any blockers under "Dependencies and blockers" in `TASKS.md`, then set its status to `Ready`, and to `In progress` once work starts.
+- Seek human input before significant new dependencies, migrations that modify or delete existing data, security-sensitive choices, or changes to approved behavior. Purely additive migrations (for example, a new table or store that leaves existing data untouched) need no prior approval, but record them in the plan and report them. Technical refinement that stays within scope usually needs no additional approval.
 - 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.
@@ -60,16 +70,17 @@ Write the approved scope into `PLAN.md`. Draft acceptance criteria and tasks tha
 - 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.
 - 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.
 
 ## 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, not architectural rationale.
+- `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.
 - `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.
+- 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/`.
 
 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.

package/scaffold/docs/features/README.md

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