scaffold-agent-specs 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 rob-pasc
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,114 @@
-# Temporary Holding Version
+# scaffold-agent-specs
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A deliberately small, dependency-free CLI for **spec-driven agentic coding**. It installs reusable Markdown instructions and templates into an existing repository, then creates numbered feature folders only after scope approval.
+
+## Requirements
+
+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
+
+From the root of any project:
+
+```sh
+npx scaffold-agent-specs init
+```
+
+When the user and agent have discussed a feature and the user **explicitly accepts its scope**:
+
+```sh
+npx scaffold-agent-specs feature "User statistics page" --approved
+```
+
+This would create `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.
+- `TASKS.md` for the implementation checklist.
+
+Optional files can be requested explicitly:
+
+```sh
+npx scaffold-agent-specs feature "Account dashboard" --approved --design --research
+```
+
+`--handoff` additionally creates the optional short-lived `HANDOFF.md`.
+
+**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.
+
+## `init` installs
+
+```text
+AGENTS.md
+CLAUDE.md
+.agent-specs/
+  templates/
+    adr/ADR.md
+    conventions/CONVENTION.md
+    feature/{PLAN,ACCEPTANCE_MATRIX,TASKS,DESIGN,RESEARCH,HANDOFF}.md
+    project/{ARCHITECTURE,GLOSSARY}.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.
+
+## Commands and safety
+
+| Command | Behavior |
+| --- | --- |
+| `init` | Copy the initial scaffold into the current directory. Never overwrite existing files. |
+| `init --dry-run` | Preview which files would be created or skipped. |
+| `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. |
+| `feature "Title" --approved --handoff` | Include optional handoff. |
+| `feature "Title" --dry-run` | Preview feature creation without confirming approval or writing files. |
+| `--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.
+
+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
+
+```sh
+npm test                # Built-in Node.js test runner
+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).
+
+## License
+
+MIT

package/bin/scaffold-agent-specs.js

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+import { run } from '../lib/cli.js';
+
+try {
+  run(process.argv.slice(2));
+} catch (error) {
+  console.error(`Error: ${error.message}`);
+  process.exitCode = 1;
+}

package/lib/cli.js

@@ -0,0 +1,73 @@
+import fs from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { initProject, createFeature } 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 feature "Feature title" --approved [options]
+  scaffold-agent-specs --version
+  scaffold-agent-specs --help
+
+Options for feature:
+  --approved    Confirm the user explicitly approved the feature's scope
+  --design      Include optional DESIGN.md
+  --research    Include optional RESEARCH.md
+  --handoff     Include optional HANDOFF.md
+  --dry-run     Preview without writing; approval not required for a preview
+  --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.
+`;
+
+export function run(args) {
+  if (!args.length || args.includes('--help') || args.includes('-h') || args[0] === 'help') {
+    console.log(help);
+    return;
+  }
+  if (args.length === 1 && (args[0] === '--version' || args[0] === '-v')) {
+    const pkg = JSON.parse(fs.readFileSync(fileURLToPath(new URL('../package.json', import.meta.url)), 'utf8'));
+    console.log(pkg.version);
+    return;
+  }
+  const [command, ...rest] = args;
+  if (!['init', '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']);
+
+  for (let i = 0; i < rest.length; i++) {
+    const argument = rest[i];
+    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=')) {
+      dir = argument.slice('--dir='.length);
+      if (!dir) throw new Error('Missing path after --dir=.');
+    } else if (allowed.has(argument)) {
+      flags.add(argument);
+    } else if (argument.startsWith('-')) {
+      throw new Error(`Unknown option: ${argument}`);
+    } else {
+      positionals.push(argument);
+    }
+  }
+  if (command === 'init') {
+    if (positionals.length) throw new Error('init takes no positional arguments.');
+    initProject(dir, { dryRun: flags.has('--dry-run') });
+    return;
+  }
+  if (!positionals.length) throw new Error('Missing feature title. Try `feature "User statistics page" --approved`.');
+  createFeature(dir, positionals.join(' '), {
+    approved: flags.has('--approved'),
+    design: flags.has('--design'),
+    research: flags.has('--research'),
+    handoff: flags.has('--handoff'),
+    dryRun: flags.has('--dry-run'),
+  });
+}

package/lib/scaffold.js

@@ -0,0 +1,175 @@
+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));
+const requiredFeatureFiles = ['PLAN.md', 'ACCEPTANCE_MATRIX.md', 'TASKS.md'];
+const optionalFeatureFiles = ['DESIGN.md', 'RESEARCH.md', 'HANDOFF.md'];
+
+function assertDirectory(dir) {
+  let stats;
+  try {
+    stats = fs.statSync(dir);
+  } catch {
+    throw new Error(`Target directory does not exist: ${dir}`);
+  }
+  if (!stats.isDirectory()) throw new Error(`Not a directory: ${dir}`);
+}
+
+function pathExists(p) {
+  try {
+    fs.lstatSync(p);
+    return true;
+  } catch (error) {
+    if (error.code === 'ENOENT') return false;
+    throw error;
+  }
+}
+
+// Refuse to write through existing symlinked descendants of the chosen root.
+// This also prevents accidentally writing through a symlink under docs/.
+function assertSafePath(root, destination) {
+  const relative = path.relative(root, destination);
+  if (relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+    throw new Error(`Refusing to write outside target directory: ${destination}`);
+  }
+  let current = root;
+  for (const component of relative.split(path.sep)) {
+    if (!component) continue;
+    current = path.join(current, component);
+    if (pathExists(current) && fs.lstatSync(current).isSymbolicLink()) {
+      throw new Error(`Refusing to write through symlink: ${current}`);
+    }
+  }
+}
+
+function getBundledFiles(dir, base = dir) {
+  return fs.readdirSync(dir, { withFileTypes: true }).flatMap((item) => {
+    const full = path.join(dir, item.name);
+    if (item.isDirectory()) return getBundledFiles(full, base);
+    if (!item.isFile()) throw new Error(`Unsupported scaffold entry: ${full}`);
+    return [path.relative(base, full)];
+  }).sort();
+}
+
+export function initProject(target, { dryRun = false, log = console.log } = {}) {
+  const root = path.resolve(target);
+  assertDirectory(root);
+  const files = getBundledFiles(bundledScaffold);
+  const created = [];
+  const skipped = [];
+
+  // Preflight before writing anything.
+  for (const rel of files) {
+    assertSafePath(root, path.join(root, rel));
+  }
+
+  for (const rel of files) {
+    const destination = path.join(root, rel);
+    if (pathExists(destination)) {
+      skipped.push(rel);
+      log(`skip   ${rel} (already exists)`);
+      continue;
+    }
+    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);
+    }
+    created.push(rel);
+    log(`${dryRun ? 'would create' : 'create'} ${rel}`);
+  }
+
+  log(`${dryRun ? 'Preview:' : 'Initialized:'} ${created.length} ${dryRun ? 'to create' : 'created'}, ${skipped.length} skipped.`);
+  return { created, skipped };
+}
+
+export function slugify(value) {
+  const slug = value.normalize('NFKD').replace(/[\u0300-\u036f]/g, '')
+    .toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
+  if (!slug) throw new Error('Feature title must include letters or numbers.');
+  if (slug.length > 80) throw new Error('Feature title is too long after conversion to a slug (max 80 characters).');
+  return slug;
+}
+
+function nextFeatureNumber(featuresDir) {
+  const existing = fs.readdirSync(featuresDir, { withFileTypes: true });
+  const ids = existing.filter((item) => item.isDirectory())
+    .map((item) => /^feature-(\d+)-/.exec(item.name))
+    .filter(Boolean).map((match) => Number(match[1]));
+  return (ids.length ? Math.max(...ids) : 0) + 1;
+}
+
+function localDate() {
+  const d = new Date();
+  const year = d.getFullYear();
+  const month = String(d.getMonth() + 1).padStart(2, '0');
+  const day = String(d.getDate()).padStart(2, '0');
+  return `${year}-${month}-${day}`;
+}
+
+function fillFeatureTemplate(contents, { title, id, slug, date }) {
+  return contents.replaceAll('feature-NNN-kebab-case', `feature-${id}-${slug}`)
+    .replaceAll('[Feature title]', title)
+    .replaceAll('Feature NNN:', `Feature ${id}:`)
+    .replaceAll('[YYYY-MM-DD]', date);
+}
+
+export function createFeature(target, title, {
+  approved = false, design = false, research = false, handoff = false,
+  dryRun = false, log = console.log,
+} = {}) {
+  const root = path.resolve(target);
+  assertDirectory(root);
+  if (!title || !title.trim()) throw new Error('Provide a feature title.');
+  if (!approved && !dryRun) {
+    throw new Error('Feature scope must be approved first. Re-run with --approved after explicit user approval.');
+  }
+  const slug = slugify(title.trim());
+  const templateDir = path.join(root, '.agent-specs', 'templates', 'feature');
+  const featuresDir = path.join(root, 'docs', 'features');
+  const files = [...requiredFeatureFiles, ...optionalFeatureFiles.filter((file) => (
+    (file === 'DESIGN.md' && design) ||
+    (file === 'RESEARCH.md' && research) ||
+    (file === 'HANDOFF.md' && handoff)
+  ))];
+  // 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.');
+  }
+  for (const filename of files) {
+    const template = path.join(templateDir, filename);
+    assertSafePath(root, template);
+    if (!fs.existsSync(template) || !fs.statSync(template).isFile()) {
+      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));
+  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' });
+      }
+    } 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 };
+}

package/package.json

@@ -1,6 +1,32 @@
 {
   "name": "scaffold-agent-specs",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "A tiny, spec-driven workflow scaffold for AI coding agents",
+  "type": "module",
+  "license": "MIT",
+  "bin": {
+    "scaffold-agent-specs": "./bin/scaffold-agent-specs.js"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "scaffold/",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "test": "node --test",
+    "pack:check": "npm pack --dry-run"
+  },
+  "keywords": [
+    "agents",
+    "agentic-coding",
+    "spec-driven-development",
+    "scaffolding",
+    "claude-code",
+    "codex"
+  ],
+  "author": "rob-pasc"
+}

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

@@ -0,0 +1,35 @@
+# ADR-NNN: [Decision title]
+
+- **Status:** Accepted
+- **Date adopted:** [YYYY-MM-DD]
+- **Related feature(s):** [Link(s), if any]
+- **Supersedes:** [ADR link or None]
+
+> Create this record only after a significant architectural decision is actually adopted. A proposal is not an accepted decision. Name the file `adr-NNN-kebab-case.md` using the next unused number.
+
+## Context
+
+[What circumstances and constraints made a durable decision necessary? What forces or tradeoffs mattered?]
+
+## Decision
+
+[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] |
+
+## Consequences
+
+[Positive and negative effects, risks, operational obligations, and follow-ups.]
+
+## Implementation / validation references
+
+[Links to related code, tests, feature docs, or PRs showing how the decision was adopted.]
+
+## Supersession notes (if applicable)
+
+[When a new ADR supersedes this decision, link it here; preserve the original decision as history.]

package/scaffold/.agent-specs/templates/conventions/CONVENTION.md

@@ -0,0 +1,19 @@
+# [Topic] Conventions
+
+> **Optional project document.** When a stable convention applies across multiple features, copy this template to `docs/conventions/[topic].md`. Keep concrete rules here, not generic agent-process instructions. Prefer existing formatters, linters, and tooling as the source of truth for mechanically enforced rules.
+
+## Scope
+
+[Which parts of the repository or kinds of changes follow this convention?]
+
+## Rules
+
+- [Specific actionable rule and rationale, when it would otherwise be unclear]
+
+## Examples (if useful)
+
+[Short preferred and discouraged examples, or links to representative code.]
+
+## Exceptions and evolution
+
+[Known exceptions, how to propose changes, and links to relevant ADRs or tooling.]

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

@@ -0,0 +1,24 @@
+# Acceptance Matrix: [Feature title]
+
+- **Feature ID:** `feature-NNN-kebab-case`
+- **Verification status:** Not started
+
+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] |
+
+## Result legend
+
+- **Not run:** Not verified yet.
+- **Pass:** Verified with evidence recorded above.
+- **Fail:** Verified behavior does not meet the criterion.
+- **Blocked:** Verification cannot proceed; explain why.
+
+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.
+
+## 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

@@ -0,0 +1,40 @@
+# Feature Design: [Feature title]
+
+- **Feature ID:** `feature-NNN-kebab-case`
+- **Design status:** Proposed (not automatically approved with feature scope)
+
+> **Optional.** Create when technical or interaction design needs more detail than `PLAN.md`. Keep approved user-visible scope in `PLAN.md`; use this document for the implementation design. Omit irrelevant sections rather than filling them with boilerplate.
+
+## Design goals and constraints
+
+[The technical/UX qualities and constraints that shape the approach. Refer to requirement IDs, rather than repeating the full feature specification.]
+
+## Proposed solution
+
+[Concise architecture and principal components. Include a small diagram when it clarifies relationships.]
+
+## User experience and states (if relevant)
+
+[UI structure, interactions, loading/empty/error states, permissions, accessibility, and responsive behavior.]
+
+## Data flow and interfaces (if relevant)
+
+[Data ownership, schemas, API boundaries, integration points, migration or compatibility needs. Refer to machine-readable contracts if they exist.]
+
+## Failure modes and operational considerations (if relevant)
+
+[Security/privacy, performance, error recovery, observability, deployment, or rollout concerns.]
+
+## Alternatives and tradeoffs
+
+[Material design options and reasons for preferring the proposed one. Significant project-wide *adopted* choices should be recorded later as ADRs.]
+
+## Open technical decisions
+
+- [Open question, whether it blocks implementation, and who needs to decide]
+
+## References
+
+- Approved scope: [`PLAN.md`](./PLAN.md)
+- Requirements and checks: [`ACCEPTANCE_MATRIX.md`](./ACCEPTANCE_MATRIX.md)
+- [Any relevant convention, architecture documentation, or adopted ADR]

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

@@ -0,0 +1,27 @@
+# Handoff: [Feature title]
+
+- **Feature ID:** `feature-NNN-kebab-case`
+- **Updated:** [YYYY-MM-DD HH:MM and time zone, if useful]
+- **Current state:** [In progress / Blocked / Ready for verification / Other]
+
+> **Optional, short-lived file.** Create when an agent or session needs a resumption snapshot. `TASKS.md` remains authoritative for progress; the plan and acceptance matrix remain authoritative for scope and verification.
+
+## Where work stands
+
+[Brief summary of the current implementation state and the specific active task ID.]
+
+## Recent changes
+
+[Relevant files, commits, and decisions made since the previous handoff.]
+
+## Checks performed
+
+[Exact commands and outcomes, including failures and checks not run.]
+
+## Blockers and cautions
+
+[Unanswered questions, risks, brittle parts, local setup requirements, or 'None'.]
+
+## Next action
+
+[One concrete next step, with any commands/files needed to resume.]

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

@@ -0,0 +1,67 @@
+# Feature NNN: [Feature title]
+
+- **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.
+
+## Summary
+
+[One or two paragraphs explaining what this feature does and why it matters.]
+
+## Problem and desired outcome
+
+- **Problem:** [What is difficult or impossible today?]
+- **Desired outcome:** [What should be different for users?]
+- **Target users / stakeholders:** [Who benefits?]
+
+## Approved scope
+
+### In scope
+
+- [Behavior or capability explicitly agreed with the user]
+
+### Out of scope
+
+- [Explicit exclusion or intentionally deferred capability]
+
+## Functional requirements
+
+- **FR-001:** [Observable behavior, with important edge cases where relevant]
+- **FR-002:** [Additional requirement, if needed]
+
+## Non-functional requirements and constraints
+
+[Performance, accessibility, security, privacy, compatibility, operational or design constraints *actually relevant* to this feature. State 'None identified' if appropriate.]
+
+## User journeys and edge cases
+
+[Key flows, empty/error states, permissions, failure modes, or representative examples.]
+
+## Proposed technical approach
+
+[Initial implementation direction based on repository inspection. Clearly mark unresolved choices and significant tradeoffs. The user approved feature scope, not automatically this approach.]
+
+## Dependencies and risks
+
+- [Dependency, prerequisite, migration risk, or 'None identified']
+
+## Assumptions and open questions
+
+- [Question or assumption; mark **Blocking** when implementation cannot responsibly proceed without an answer]
+
+## Scope change log
+
+| Date | Change | User approval |
+| --- | --- | --- |
+| [YYYY-MM-DD] | Initial approved scope | [Explicit approval reference / conversation] |
+
+## References
+
+- Acceptance criteria: [`ACCEPTANCE_MATRIX.md`](./ACCEPTANCE_MATRIX.md)
+- Implementation tasks: [`TASKS.md`](./TASKS.md)
+- Related ADRs: [Links added only after decisions are adopted]
+- Optional detailed design/research: [Link to `DESIGN.md` and/or `RESEARCH.md` only when created]

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

@@ -0,0 +1,32 @@
+# Feature Research: [Feature title]
+
+- **Feature ID:** `feature-NNN-kebab-case`
+- **Research status:** Exploratory
+
+> **Optional.** Use only when investigation produces findings worth preserving. Research is evidence for planning, not approval of a feature scope or technical decision. Distinguish observations from assumptions.
+
+## Question / motivation
+
+[What needed investigation, and what decision or requirement could the findings inform?]
+
+## Findings
+
+[Concise, supported observations; include links, versions, dates, and repository evidence where useful.]
+
+## Alternatives evaluated
+
+| Option | Evidence / strengths | Limitations / risks |
+| --- | --- | --- |
+| [Option A] | [Evidence] | [Risks] |
+
+## Recommendation and confidence
+
+[If appropriate, recommend an approach, explain remaining uncertainty, and say what would validate it. Do not present it as adopted.]
+
+## Open questions / follow-up
+
+- [Question or next experiment, if any]
+
+## Sources and references
+
+[Links to relevant code, documentation, prototypes, measurements, or external resources.]

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

@@ -0,0 +1,20 @@
+# Implementation Tasks: [Feature title]
+
+- **Feature ID:** `feature-NNN-kebab-case`
+- **Status:** Not started
+
+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.
+
+## Tasks
+
+- [ ] **T-001:** [First actionable implementation step] (supports `AC-001`)
+- [ ] **T-002:** [Next actionable implementation step] (supports `AC-001`, `AC-002`)
+- [ ] **T-003:** [Tests, verification, and relevant docs updates] (supports `AC-001`, `AC-002`)
+
+## Dependencies and blockers
+
+- [None identified, or list blocking task IDs / questions and responsible next steps]
+
+## Progress notes
+
+[Only durable information needed to interpret task state. Put architecture rationale in `PLAN.md` or adopted ADRs, and test results in `ACCEPTANCE_MATRIX.md`.]

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

@@ -0,0 +1,33 @@
+# 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.
+
+## System at a glance
+
+[What the system does and which major parts it comprises.]
+
+## Components and responsibilities
+
+| Component | Responsibility | Key dependencies |
+| --- | --- | --- |
+| [Component] | [Responsibility] | [Dependencies] |
+
+## Important data and request flows
+
+[Key runtime interactions, integrations, and data ownership. Add a diagram only if it improves clarity.]
+
+## Boundaries and cross-cutting concerns
+
+[Deployment, trust boundaries, security, data persistence, observability, failure handling, or other topics relevant to this system.]
+
+## Architecture decisions and conventions
+
+[Link to relevant ADRs and applicable docs/conventions files, without duplicating their contents.]
+
+## Known limitations and evolution
+
+[Current constraints and intentional technical debt; distinguish proposed work from implemented behavior.]
+
+## Last reviewed
+
+[YYYY-MM-DD and relevant change/commit, if useful]

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

@@ -0,0 +1,11 @@
+# Project Glossary
+
+> **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] |
+
+## Usage notes (if needed)
+
+[Ambiguous, deprecated, or easily confused terms, with preferred wording.]

package/scaffold/AGENTS.md

@@ -0,0 +1,87 @@
+# 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.
+
+## 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.
+- Keep the human in control of scope and significant architectural tradeoffs.
+
+## Feature workflow and approval gates
+
+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.
+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.
+
+Existing-feature work and ordinary fixes should follow the user's requested scope; do not force a new feature directory for every small change.
+
+### 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.
+- 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.
+- **`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.
+- **`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 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/`. 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.
+- Call out unresolved failures, missing coverage, migrations, and follow-up work explicitly.
+
+## Git commit conventions
+
+Use **Conventional Commit-style** subjects with a meaningful scope:
+
+```text
+<type>(<scope>): <imperative summary>
+
+<Prose describing what changed and why it matters.>
+```
+
+- Example subjects: `feat(web): introduce user statistics page`, `fix(api): reject invalid date ranges`, `docs(adr): record reporting storage decision`.
+- Common types: `feat`, `fix`, `refactor`, `test`, `docs`, `chore`, `perf`, `build`, `ci`.
+- 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:
+
+```text
+feat(web): introduce user statistics page
+
+Add a date-range filter and daily activity chart so users can inspect
+engagement without exporting raw events. Reuse the existing reporting
+endpoint to keep the change within the current data architecture.
+```

package/scaffold/CLAUDE.md

@@ -0,0 +1,6 @@
+# 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.

package/scaffold/docs/WORKFLOW.md

@@ -0,0 +1,75 @@
+# Spec-driven Feature Workflow
+
+This document expands the feature lifecycle required by [`AGENTS.md`](../AGENTS.md). Feature specifications live in `docs/features/`; reusable templates live in `.agent-specs/templates/`.
+
+## Phase 1: Discover (conversation only)
+
+- Read existing code and documentation when relevant, then explore the user's idea collaboratively.
+- Ask focused clarifying questions, using the agent's interactive question interface where available or normal chat otherwise. Prefer small, purposeful batches over long questionnaires.
+- Establish the problem, target users, expected behaviors, important edge cases, constraints, dependencies, and exclusions.
+- Offer sensible defaults and surface tradeoffs; do not silently make consequential product decisions.
+- Do **not** create a feature directory, commit a spec, or implement the feature yet.
+
+## Phase 2: Propose and decide (human gate)
+
+Present a readable summary with:
+
+1. **Goal and motivation**: what problem the feature solves.
+2. **Expected behavior**: key user journeys and observable outcomes.
+3. **Scope**: clearly distinguished in-scope and out-of-scope work.
+4. **Acceptance expectations**: how success will be recognized.
+5. **Assumptions, risks, and open questions**: especially choices that affect cost or design.
+
+Ask the user to **accept, revise, or discard**.
+
+- **Accept:** proceed to specification.
+- **Revise:** discuss, re-propose, and seek explicit approval again.
+- **Discard:** stop without creating feature artifacts.
+- Silence, vague assent, or approval of a different subject does not count as approval.
+
+## 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:
+
+| 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.
+
+**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.
+- 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.
+- 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.
+
+## Phase 5: Verify and close
+
+- 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.
+- 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.
+
+## 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.
+- `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.
+- `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/adr/README.md

@@ -0,0 +1,8 @@
+# Architecture Decision Records
+
+Record **significant architectural decisions actually adopted** by this project here. Do not create speculative ADRs during feature discovery or initial specification; capture proposals in the relevant `PLAN.md` instead. If a consequential decision is adopted before the feature is fully implemented, write its ADR at the point of adoption.
+
+- The reusable format lives in `.agent-specs/templates/adr/ADR.md`; keep templates out of this directory.
+- Number real ADRs `adr-001-short-description.md`, `adr-002-short-description.md`, and so on. Never renumber an existing ADR.
+- Describe context, the adopted decision, alternatives, consequences, and relevant feature/code references.
+- If a decision is replaced later, preserve the original historical record and link to its superseding ADR rather than rewriting history.

package/scaffold/docs/features/README.md

@@ -0,0 +1,17 @@
+# Feature Specifications
+
+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.
+
+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.
+
+Required documents (copied from `.agent-specs/templates/feature/`):
+
+- `PLAN.md`: approved scope and proposed approach.
+- `ACCEPTANCE_MATRIX.md`: testable outcomes and verification evidence.
+- `TASKS.md`: implementation checklist.
+
+`DESIGN.md` is optional for substantial technical or interaction design. `RESEARCH.md` is optional for reusable investigation findings. `HANDOFF.md` is optional and should be created when an agent or session needs to transfer working context. Do not create empty optional documents just to satisfy a checklist.
+
+After creating and populating the specs, **stop** and await a separate implementation request. See [`docs/WORKFLOW.md`](../WORKFLOW.md) for the full lifecycle.