@stdd/cli 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Azamat Almazbek uulu
+
+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

@@ -0,0 +1,211 @@
+<h1 align="center">stdd</h1>
+
+<p align="center"><strong>S</strong>pec + <strong>T</strong>est <strong>D</strong>riven <strong>D</strong>evelopment — a markdown-first methodology kit for teams building software with AI coding agents.</p>
+
+<p align="center">
+  <a href="https://github.com/vsem-azamat/stdd/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/vsem-azamat/stdd/actions/workflows/ci.yml/badge.svg" /></a>
+  <a href="https://www.npmjs.com/package/@stdd/cli"><img alt="npm version" src="https://img.shields.io/npm/v/%40stdd%2Fcli?style=flat-square" /></a>
+  <img alt="node 20+" src="https://img.shields.io/badge/node-20%2B-brightgreen?style=flat-square" />
+  <img alt="zero dependencies" src="https://img.shields.io/badge/dependencies-0-blue?style=flat-square" />
+  <a href="./LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-blue?style=flat-square" /></a>
+</p>
+
+```text
+→ the docs edit IS the spec — reviewed before any code
+→ tests gate behavior; visuals are design-first
+→ working artifacts are never committed
+→ one agent-neutral source, compiled per agent
+→ mechanics over discipline — what can be checked, CI checks
+```
+
+## Why
+
+AI coding agents amplify a quiet failure mode: **committed working artifacts**.
+Plans and spec files written for one change land in the repo, go stale, and
+keep winning code search — an agent greps the tree, finds a convincing
+month-old spec that a newer doc contradicts, and confidently builds the wrong
+thing. Popular SDD frameworks make this worse by design: change folders and
+archives accumulate authoritative-looking text with no machine-readable
+authority.
+
+stdd inverts the model. Your permanent documentation tree is the **single**
+source of truth. The edit to that tree is the spec — it comes first, in a
+reviewable diff, before the failing test; the failing test comes before the
+implementation. Everything ephemeral lives where ephemeral things belong:
+rationale in the PR description, history in git, deferred designs as dated
+project-log records. What can be verified mechanically, CI verifies; the
+rest is a written contract you review against — not folklore.
+
+## The loop
+
+```mermaid
+flowchart LR
+    A["Classify<br/>the change"] --> B{"Behavior<br/>change?"}
+    B -- "implementation-only" --> E["Implement"]
+    B -- "yes" --> C["Read docs →<br/><b>edit docs = the spec</b><br/>(first reviewable diff)"]
+    C --> D["Failing<br/>test"]
+    D --> E
+    E --> F["Verify"]
+    F --> G["PR evidence<br/>(CI-checked)"]
+
+    C -. "frontend visual work:<br/>design-first — build, review<br/>screenshots, then test behavior" .-> E
+```
+
+## Where knowledge lives
+
+One truth inside the tree; everything ephemeral outside it — so an agent
+grepping the repo can only find the present. The one dated exception, the
+project log, is marked machine-readably (`authority: non-canonical`
+frontmatter) and the generated agent instructions forbid searching it
+unless the user explicitly asks for history or deferred work.
+
+```mermaid
+flowchart TD
+    CH(["a change"])
+
+    subgraph TREE["in the repository — what agents grep"]
+        DOCS["<b>docs/</b> — canonical truth<br/>present tense, single source"]
+        LOG["docs/project/ — dated records<br/>deferred designs, decisions<br/><i>non-canonical</i>"]
+        STDD[".stdd/ — method + playbooks"]
+    end
+
+    subgraph OUT["outside the tree — explicit access only"]
+        PR["PR description<br/>rationale, alternatives, scope"]
+        GIT["git history<br/>what changed and why"]
+        PAD["session scratchpad<br/>plans, task lists"]
+    end
+
+    CH -- "durable rules" --> DOCS
+    CH -- "deferred design" --> LOG
+    CH -- "rationale" --> PR
+    CH -- "history" --> GIT
+    CH -- "plans, sequencing" --> PAD
+```
+
+## See it in action
+
+```text
+You: We need admins to adjust an order's price before invoicing.
+
+AI:  [stdd-brainstorming] One question: order-level or per-item? …
+     Agreed: order-level signed adjustment, review-status only, reason
+     required, customer notified.
+
+AI:  Commit 1 — docs/domain/pricing.md: "Manual Price Adjustment" rules.
+     (the spec, reviewable on its own)
+AI:  Commit 2 — failing integration test for the new rules.
+AI:  Commit 3 — implementation; test green; verification output attached.
+
+PR body:
+     Docs updated first: docs/domain/pricing.md
+     Decisions and alternatives: per-item adjustment rejected because …
+
+CI:  stdd check     ✓ no committed working artifacts, no temporal narrative
+     stdd check-pr  ✓ evidence line names the changed docs
+```
+
+## Quick start
+
+```bash
+npm install -g @stdd/cli
+cd your-project
+stdd init --tools claude,codex
+```
+
+`stdd init` installs `.stdd/` (the method contract + playbooks + config),
+generates Claude Code skills, and prints the section to add to your
+`AGENTS.md` for Codex and any other agent that reads it. Everything it
+generates is recorded with content hashes in `.stdd/manifest.json`, so
+`check` and `doctor` detect hand edits and stale copies of any generated
+file — not just version drift.
+
+Not sure where an existing repo stands? Get a report in seconds:
+
+```console
+$ npx @stdd/cli doctor
+✗ 6 committed working artifacts may mislead coding agents
+✗ 2 canonical docs contain temporal narrative
+✓ generated files match stdd v0.0.1
+✗ AGENTS.md has no STDD section — paste .stdd/AGENTS-snippet.md
+```
+
+Then wire the guards into CI:
+
+```yaml
+- run: npx @stdd/cli check                                # tree invariants
+- env:
+    PR_BODY: ${{ github.event.pull_request.body }}
+  run: printf '%s' "$PR_BODY" | npx @stdd/cli check-pr -  # docs evidence line
+```
+
+## Commands
+
+| Command | What it does |
+| --- | --- |
+| `stdd init [dir] [--tools claude,codex]` | Install `.stdd/` and compile playbooks per agent |
+| `stdd doctor [dir]` | Adoption health report: setup, canonical docs, misleading artifacts, drift — exits 1 on findings |
+| `stdd check [dir]` | CI guard: no committed working artifacts, no temporal narrative in canonical docs, no stale or hand-edited generated files |
+| `stdd check-pr <file\|->` | CI guard: PR body carries exactly one non-empty docs evidence line |
+
+All checks are configured in `.stdd/config.json` (glob patterns for
+forbidden artifacts, canonical docs, temporal phrases).
+
+## What's in the box
+
+| Path | Contents |
+| --- | --- |
+| [`method/`](method/README.md) | The STDD contract: the loop, the rules, the exceptions |
+| [`playbooks/`](playbooks/) | Agent-neutral playbooks: brainstorming, planning, debugging, worktrees |
+| [`templates/`](templates/) | PR description and deferred-design templates |
+| [`adapters/`](adapters/README.md) | How playbooks compile per agent |
+| [`cli/`](cli/) | Zero-dependency Node CLI |
+
+## The method in five rules
+
+1. **Classify first.** Behavior changes (anything observable) pass the full
+   loop; implementation-only changes skip the docs step.
+2. **The docs edit is the spec.** Missing or stale docs are updated before
+   tests and code, as the first reviewable unit of the change.
+3. **Red before green.** A failing test gates every behavior change —
+   except frontend *visual* work, which is design-first: build, review
+   screenshots, then test only real behavior contracts.
+4. **Working artifacts are never committed.** Rationale → PR description;
+   history → git; deferred designs → dated project-log entries.
+5. **Evidence, not claims.** Every PR states `Docs updated first:` /
+   `Docs checked, no change needed:` / `Docs not applicable:` — naming the
+   docs or the reason. CI rejects a missing, duplicated, or bare label.
+
+The full contract: [`method/README.md`](method/README.md).
+
+## How it compares
+
+**vs. [OpenSpec](https://github.com/Fission-AI/OpenSpec)** — OpenSpec models
+changes as committed folders that archive into the repo; specs accumulate
+alongside a separate docs reality. stdd keeps one truth (your docs tree),
+borrows OpenSpec's best mechanics (delta discipline, drift detection,
+init/update UX), and rejects the archive.
+
+**vs. [Superpowers](https://github.com/obra/superpowers)** — great process
+content, but Claude-only and delivered through plugin hooks. stdd rewrites
+the process agent-neutrally and compiles it for every agent your team runs.
+
+**vs. nothing** — chat context evaporates; agents build before agreeing on
+scope; stale plans mislead the next session. stdd fixes the workflow, not
+the model.
+
+## Development
+
+```bash
+npm ci
+npm test          # node:test — unit + CLI integration
+npm run check     # Biome (Rust) — lint + format, CI mode
+npm run format    # Biome — write fixes
+npm run selfcheck # stdd check on this repo (dogfooding)
+```
+
+This repository follows its own method: PRs carry a docs evidence line
+(enforced by CI via `stdd check-pr`), and no working artifacts are committed.
+
+## License
+
+[MIT](LICENSE)

package/adapters/README.md

@@ -0,0 +1,38 @@
+# Adapters
+
+Playbooks are agent-neutral markdown with frontmatter (`name`, `description`,
+`when`). Adapters compile them into what each agent consumes. `stdd init`
+runs the adapters; re-run it after upgrading stdd to refresh the output.
+
+## Common output
+
+Every init installs `.stdd/` into the target repo:
+
+```
+.stdd/
+├── method.md          # the STDD contract (copy of method/README.md)
+├── playbooks/         # agent-neutral playbooks
+└── config.json        # stdd check configuration
+```
+
+`.stdd/` is committed — it is methodology, not a working artifact.
+
+## claude (Claude Code)
+
+Writes one skill per playbook to `.claude/skills/<name>/SKILL.md`:
+frontmatter maps `name`/`description` directly; the body is the playbook
+body. Skills are self-contained copies — regenerate, never hand-edit.
+
+## codex (and any agent that reads AGENTS.md)
+
+Writes `.stdd/AGENTS-snippet.md` and prints it. Paste (or `@`-include) the
+snippet into the repo's `AGENTS.md`. The snippet is short: it points the
+agent at `.stdd/method.md` and lists the playbooks with their `when` lines.
+
+## Design rules for adapters
+
+- One source of truth: adapters copy or point, never fork playbook content.
+- No agent-specific incantations inside `playbooks/` — if an agent needs
+  special framing, that framing lives in the adapter.
+- Calm imperative prose. No all-caps compliance shouting: if a rule needs
+  shouting to be followed, it needs a `stdd check` rule instead.

package/cli/lib.mjs

@@ -0,0 +1,124 @@
+import { createHash } from "node:crypto";
+
+/** Content fingerprint used by the generated-files manifest. */
+export function sha256(content) {
+	return `sha256:${createHash("sha256").update(content).digest("hex")}`;
+}
+
+export const DEFAULT_CONFIG = {
+	// Working-artifact paths that must never be committed. `stdd check` fails
+	// if any tracked file matches. Deliberately narrow — widen per repo.
+	forbiddenArtifacts: ["docs/**/plans/**", "**/*.agent-plan.md", "**/*.agent-spec.md"],
+	// Canonical docs must describe the present, in English. `stdd check`
+	// flags temporal narrative that belongs in git history or a PR
+	// description. Fenced code blocks are skipped.
+	canonicalDocs: ["docs/domain/**/*.md", "docs/product/**/*.md"],
+	temporalPhrases: ["previously", "no longer", "used to be", "before this change"],
+};
+
+export const EVIDENCE_LABELS = [
+	"Docs updated first",
+	"Docs checked, no change needed",
+	"Docs not applicable",
+];
+
+const EVIDENCE_MATCHERS = EVIDENCE_LABELS.map((label) => ({
+	label,
+	re: new RegExp(`^${label}:[ \\t]*(.*)$`, "i"),
+}));
+
+/**
+ * Find docs evidence lines in a PR body. Only lines that start at the
+ * beginning of a line count — quoted templates (`> Docs …`) and fenced code
+ * blocks do not. Returns `{ label, content }` per hit; a bare label yields
+ * empty content.
+ */
+export function findEvidenceLines(body) {
+	const hits = [];
+	let inFence = false;
+	for (const line of body.replaceAll("\r\n", "\n").split("\n")) {
+		if (/^\s*(```|~~~)/.test(line)) {
+			inFence = !inFence;
+			continue;
+		}
+		if (inFence) continue;
+		for (const { label, re } of EVIDENCE_MATCHERS) {
+			const m = re.exec(line);
+			if (m) hits.push({ label, content: m[1].trim() });
+		}
+	}
+	return hits;
+}
+
+/**
+ * Tiny glob dialect: `*` matches within a path segment, `**` matches across
+ * segments. No `?`, braces, or character classes — by design.
+ */
+export function globToRegExp(glob) {
+	const segments = glob.split("/");
+	const parts = segments.map((segment, i) => {
+		const last = i === segments.length - 1;
+		if (segment === "**") return last ? ".*" : "(?:[^/]+/)*";
+		const escaped = segment.replace(/[.+?^${}()|[\]\\]/g, "\\$&").replaceAll("*", "[^/]*");
+		return escaped + (last ? "" : "/");
+	});
+	return new RegExp(`^${parts.join("")}$`);
+}
+
+/** Parse a `---`-fenced frontmatter block. CRLF-tolerant. */
+export function parseFrontmatter(source) {
+	const normalized = source.replaceAll("\r\n", "\n");
+	const match = /^---\n([\s\S]*?)\n---\n?/.exec(normalized);
+	if (!match) return { meta: {}, body: normalized };
+	const meta = {};
+	for (const line of match[1].split("\n")) {
+		const idx = line.indexOf(":");
+		if (idx > 0) meta[line.slice(0, idx).trim()] = line.slice(idx + 1).trim();
+	}
+	return { meta, body: normalized.slice(match[0].length) };
+}
+
+/**
+ * Merge a parsed user config over the defaults and validate shape.
+ * Throws with an actionable message on invalid input.
+ */
+export function mergeConfig(parsed) {
+	const config = { ...DEFAULT_CONFIG, ...parsed };
+	for (const key of ["forbiddenArtifacts", "canonicalDocs", "temporalPhrases"]) {
+		if (!Array.isArray(config[key]) || config[key].some((v) => typeof v !== "string")) {
+			throw new Error(`"${key}" must be an array of strings`);
+		}
+	}
+	return config;
+}
+
+/**
+ * Build a temporal-phrase matcher. Word-ish boundaries on both sides so
+ * hyphenated compounds ("no longer-lived") do not match.
+ */
+export function temporalMatchers(phrases) {
+	return phrases.map((phrase) => ({
+		phrase,
+		re: new RegExp(`(?<![\\w-])${phrase.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}(?![\\w-])`, "i"),
+	}));
+}
+
+/**
+ * Scan markdown lines for temporal narrative, skipping fenced code blocks.
+ * Returns `{ line, phrase }` hits (1-indexed lines).
+ */
+export function scanTemporal(lines, matchers) {
+	const hits = [];
+	let inFence = false;
+	lines.forEach((line, i) => {
+		if (/^\s*(```|~~~)/.test(line)) {
+			inFence = !inFence;
+			return;
+		}
+		if (inFence) return;
+		for (const { phrase, re } of matchers) {
+			if (re.test(line)) hits.push({ line: i + 1, phrase });
+		}
+	});
+	return hits;
+}

package/cli/stdd.mjs

@@ -0,0 +1,363 @@
+#!/usr/bin/env node
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+	DEFAULT_CONFIG,
+	findEvidenceLines,
+	globToRegExp,
+	mergeConfig,
+	parseFrontmatter,
+	scanTemporal,
+	sha256,
+	temporalMatchers,
+} from "./lib.mjs";
+
+const PKG_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const VERSION = JSON.parse(fs.readFileSync(path.join(PKG_ROOT, "package.json"), "utf8")).version;
+const KNOWN_TOOLS = ["claude", "codex"];
+const STAMP = `generated by stdd v${VERSION} — do not edit, re-run \`stdd init\``;
+
+function fail(message) {
+	console.error(`stdd: ${message}`);
+	process.exit(1);
+}
+
+function listTrackedFiles(dir) {
+	try {
+		const out = execFileSync("git", ["-C", dir, "ls-files", "-z"], {
+			encoding: "utf8",
+			stdio: ["ignore", "pipe", "ignore"],
+		});
+		const files = out.split("\0").filter(Boolean);
+		if (files.length > 0) return files;
+	} catch {
+		// not a git repo — fall through to a filesystem walk
+	}
+	const files = [];
+	const walk = (rel) => {
+		for (const entry of fs.readdirSync(path.join(dir, rel), { withFileTypes: true })) {
+			if (entry.name === ".git" || entry.name === "node_modules") continue;
+			const relPath = rel ? `${rel}/${entry.name}` : entry.name;
+			if (entry.isDirectory()) walk(relPath);
+			else files.push(relPath);
+		}
+	};
+	walk("");
+	return files;
+}
+
+function loadPlaybooks() {
+	const dir = path.join(PKG_ROOT, "playbooks");
+	return fs
+		.readdirSync(dir)
+		.filter((f) => f.endsWith(".md"))
+		.map((f) => {
+			const source = fs.readFileSync(path.join(dir, f), "utf8");
+			const { meta, body } = parseFrontmatter(source);
+			if (!meta.name || !meta.description) {
+				fail(`playbook ${f} is missing required frontmatter (name, description)`);
+			}
+			return { file: f, source, meta, body };
+		});
+}
+
+function loadConfig(targetDir) {
+	const configPath = path.join(targetDir, ".stdd", "config.json");
+	if (!fs.existsSync(configPath)) return DEFAULT_CONFIG;
+	let parsed;
+	try {
+		parsed = JSON.parse(fs.readFileSync(configPath, "utf8"));
+	} catch (err) {
+		fail(`.stdd/config.json is not valid JSON: ${err.message}`);
+	}
+	try {
+		return mergeConfig(parsed);
+	} catch (err) {
+		fail(`.stdd/config.json: ${err.message}`);
+	}
+}
+
+function init(targetDir, tools) {
+	const stddDir = path.join(targetDir, ".stdd");
+	fs.mkdirSync(path.join(stddDir, "playbooks"), { recursive: true });
+	// Every generated file is recorded here (repo-relative path → content
+	// hash) and written to .stdd/manifest.json, so check/doctor can detect
+	// hand edits, deletions, and stale copies. User-owned files (config.json)
+	// are deliberately not recorded.
+	const generated = {};
+	const writeGenerated = (relPath, content) => {
+		fs.writeFileSync(path.join(targetDir, ...relPath.split("/")), content);
+		generated[relPath] = sha256(content);
+	};
+
+	writeGenerated(".stdd/method.md", fs.readFileSync(path.join(PKG_ROOT, "method", "README.md"), "utf8"));
+	const playbooks = loadPlaybooks();
+	for (const pb of playbooks) {
+		writeGenerated(`.stdd/playbooks/${pb.file}`, pb.source);
+	}
+	const configPath = path.join(stddDir, "config.json");
+	if (!fs.existsSync(configPath)) {
+		fs.writeFileSync(configPath, `${JSON.stringify(DEFAULT_CONFIG, null, "\t")}\n`);
+	}
+	console.log(`Installed .stdd/ (method, ${playbooks.length} playbooks, config)`);
+
+	if (tools.includes("claude")) {
+		for (const pb of playbooks) {
+			const skillDir = path.join(targetDir, ".claude", "skills", pb.meta.name);
+			fs.mkdirSync(skillDir, { recursive: true });
+			const skill =
+				`---\nname: ${pb.meta.name}\ndescription: ${pb.meta.description}\n---\n\n` +
+				`<!-- ${STAMP} -->\n\n${pb.body}`;
+			writeGenerated(`.claude/skills/${pb.meta.name}/SKILL.md`, skill);
+		}
+		console.log(`Installed ${playbooks.length} Claude Code skills under .claude/skills/`);
+	}
+
+	if (tools.includes("codex")) {
+		const lines = [
+			`<!-- ${STAMP} -->`,
+			"",
+			"## STDD",
+			"",
+			"This repository follows the STDD method: read `.stdd/method.md` before",
+			"any behavior change and follow its loop (docs edit is the spec → failing",
+			"test → implement → verify → PR evidence).",
+			"",
+			"Do not search the project log (dated entries marked",
+			"`authority: non-canonical`, e.g. `docs/project/`) unless the user",
+			"explicitly asks for historical rationale or deferred work — it records",
+			"past decisions and future intentions, never the present.",
+			"",
+			"Playbooks in `.stdd/playbooks/`:",
+			"",
+			...playbooks.map((pb) => `- \`${pb.file}\` — ${pb.meta.when ?? pb.meta.description}`),
+		];
+		const snippet = `${lines.join("\n")}\n`;
+		writeGenerated(".stdd/AGENTS-snippet.md", snippet);
+		console.log("\nAdd this to your AGENTS.md (also saved to .stdd/AGENTS-snippet.md):\n");
+		console.log(snippet);
+	}
+
+	const manifest = { generatedBy: "stdd", version: VERSION, files: generated };
+	fs.writeFileSync(path.join(stddDir, "manifest.json"), `${JSON.stringify(manifest, null, "\t")}\n`);
+}
+
+/**
+ * Shared repository scan for `check` and `doctor`: committed working
+ * artifacts, canonical docs and their temporal-narrative hits, and stale
+ * generated files (a stale stamp means the CLI was upgraded without
+ * re-running `stdd init`).
+ */
+function scanRepo(targetDir, config) {
+	const files = listTrackedFiles(targetDir);
+
+	const forbidden = config.forbiddenArtifacts.map(globToRegExp);
+	const artifacts = files.filter((file) => forbidden.some((re) => re.test(file)));
+
+	const canonical = config.canonicalDocs.map(globToRegExp);
+	const canonicalFiles = files.filter((file) => canonical.some((re) => re.test(file)));
+	const matchers = temporalMatchers(config.temporalPhrases);
+	const temporal = [];
+	for (const file of canonicalFiles) {
+		const lines = fs.readFileSync(path.join(targetDir, file), "utf8").split("\n");
+		for (const hit of scanTemporal(lines, matchers)) temporal.push({ file, ...hit });
+	}
+
+	return { artifacts, canonicalFiles, temporal, stale: scanGeneratedDrift(targetDir) };
+}
+
+/**
+ * Generated-file drift, as `{ file, message }` findings. With a manifest
+ * (written by `stdd init`), every generated file is verified by content
+ * hash. Without one (repo initialized by an older stdd), fall back to the
+ * version stamp inside Claude skills.
+ */
+function scanGeneratedDrift(targetDir) {
+	const stale = [];
+	const manifestPath = path.join(targetDir, ".stdd", "manifest.json");
+	if (fs.existsSync(manifestPath)) {
+		let manifest;
+		try {
+			manifest = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
+		} catch {
+			return [{ file: ".stdd/manifest.json", message: "is not valid JSON — re-run stdd init" }];
+		}
+		if (manifest.version !== VERSION) {
+			stale.push({
+				file: ".stdd/manifest.json",
+				message: `written by stdd v${manifest.version}, CLI is v${VERSION} — re-run stdd init`,
+			});
+		}
+		for (const [file, hash] of Object.entries(manifest.files ?? {})) {
+			const filePath = path.join(targetDir, ...file.split("/"));
+			if (!fs.existsSync(filePath)) {
+				stale.push({ file, message: "listed in .stdd/manifest.json but missing — re-run stdd init" });
+			} else if (sha256(fs.readFileSync(filePath, "utf8")) !== hash) {
+				stale.push({ file, message: "edited by hand or stale — re-run stdd init" });
+			}
+		}
+		return stale;
+	}
+
+	const stampRe = /generated by stdd v([0-9][^\s]*) —/;
+	const skillsDir = path.join(targetDir, ".claude", "skills");
+	if (fs.existsSync(skillsDir)) {
+		for (const name of fs.readdirSync(skillsDir)) {
+			const skillPath = path.join(skillsDir, name, "SKILL.md");
+			if (!fs.existsSync(skillPath)) continue;
+			const m = stampRe.exec(fs.readFileSync(skillPath, "utf8"));
+			if (m && m[1] !== VERSION) {
+				stale.push({
+					file: `.claude/skills/${name}/SKILL.md`,
+					message: `generated by stdd v${m[1]}, CLI is v${VERSION} — re-run stdd init`,
+				});
+			}
+		}
+	}
+	return stale;
+}
+
+function check(targetDir) {
+	const config = loadConfig(targetDir);
+	const { artifacts, temporal, stale } = scanRepo(targetDir, config);
+	const violations = [
+		...artifacts.map((file) => `${file}: committed working artifact (forbiddenArtifacts)`),
+		...temporal.map(
+			(hit) => `${hit.file}:${hit.line}: temporal narrative in canonical doc ("${hit.phrase}")`,
+		),
+		...stale.map((s) => `${s.file}: ${s.message}`),
+	];
+
+	if (violations.length > 0) {
+		console.error(`stdd check: ${violations.length} violation(s)\n`);
+		for (const v of violations) console.error(`  ${v}`);
+		process.exit(1);
+	}
+	console.log("stdd check: OK");
+}
+
+function doctor(targetDir) {
+	const count = (n, singular, plural) => `${n} ${n === 1 ? singular : plural}`;
+	let failed = false;
+	const report = (ok, message) => {
+		console.log(`${ok ? "✓" : "✗"} ${message}`);
+		if (!ok) failed = true;
+	};
+
+	const installed = fs.existsSync(path.join(targetDir, ".stdd", "method.md"));
+	report(installed, installed ? ".stdd/ installed" : ".stdd/ is not installed — run stdd init");
+
+	const config = loadConfig(targetDir);
+	const { artifacts, canonicalFiles, temporal, stale } = scanRepo(targetDir, config);
+
+	report(
+		canonicalFiles.length > 0,
+		canonicalFiles.length > 0
+			? `canonical docs present (${count(canonicalFiles.length, "file", "files")})`
+			: "no canonical docs found — create docs/domain/ or docs/product/, or adjust canonicalDocs",
+	);
+
+	report(
+		artifacts.length === 0,
+		artifacts.length === 0
+			? "no committed working artifacts"
+			: `${count(artifacts.length, "committed working artifact", "committed working artifacts")} may mislead coding agents`,
+	);
+
+	const temporalFiles = new Set(temporal.map((hit) => hit.file)).size;
+	report(
+		temporalFiles === 0,
+		temporalFiles === 0
+			? "canonical docs describe the present (no temporal narrative)"
+			: `${count(temporalFiles, "canonical doc contains", "canonical docs contain")} temporal narrative`,
+	);
+
+	report(
+		stale.length === 0,
+		stale.length === 0
+			? `generated files match stdd v${VERSION}`
+			: `${count(stale.length, "generated file is", "generated files are")} stale — re-run stdd init`,
+	);
+
+	const agentsPath = path.join(targetDir, "AGENTS.md");
+	if (fs.existsSync(agentsPath)) {
+		const hasSection = /^## STDD$/m.test(fs.readFileSync(agentsPath, "utf8"));
+		report(
+			hasSection,
+			hasSection
+				? "AGENTS.md carries the STDD section"
+				: "AGENTS.md has no STDD section — paste .stdd/AGENTS-snippet.md",
+		);
+	}
+
+	if (failed) process.exit(1);
+}
+
+function checkPr(prBodyFile) {
+	const body =
+		prBodyFile === "-" || !prBodyFile ? fs.readFileSync(0, "utf8") : fs.readFileSync(prBodyFile, "utf8");
+	const matches = findEvidenceLines(body);
+	if (matches.length === 0) {
+		fail(
+			"PR body has no docs evidence line. Add exactly one of:\n" +
+				"  Docs updated first: <docs>\n" +
+				"  Docs checked, no change needed: <docs + reason>\n" +
+				"  Docs not applicable: <why implementation-only>",
+		);
+	}
+	if (matches.length > 1) {
+		fail("PR body has more than one docs evidence line — keep exactly one.");
+	}
+	if (matches[0].content === "") {
+		fail(`"${matches[0].label}:" names no evidence — list the docs or the reason after the colon.`);
+	}
+	console.log("stdd check-pr: OK");
+}
+
+// --- argument parsing (strict: unknown flags are errors) ---
+const [, , command, ...rest] = process.argv;
+let tools = null;
+const positional = [];
+for (let i = 0; i < rest.length; i++) {
+	const arg = rest[i];
+	if (arg === "--tools" || arg.startsWith("--tools=")) {
+		if (command !== "init") fail(`--tools is only valid for "stdd init"`);
+		const value = arg.includes("=") ? arg.slice("--tools=".length) : (rest[++i] ?? "");
+		tools = value.split(",").filter(Boolean);
+		if (tools.length === 0) fail("--tools requires a value, e.g. --tools claude,codex");
+		const unknown = tools.filter((t) => !KNOWN_TOOLS.includes(t));
+		if (unknown.length > 0) {
+			fail(`unknown tool(s): ${unknown.join(", ")} (known: ${KNOWN_TOOLS.join(", ")})`);
+		}
+	} else if (arg.startsWith("--")) {
+		fail(`unknown flag: ${arg}`);
+	} else {
+		positional.push(arg);
+	}
+}
+if (positional.length > 1) fail(`unexpected argument: ${positional[1]}`);
+const targetDir = path.resolve(positional[0] ?? ".");
+
+switch (command) {
+	case "init":
+		init(targetDir, tools ?? KNOWN_TOOLS);
+		break;
+	case "check":
+		check(targetDir);
+		break;
+	case "doctor":
+		doctor(targetDir);
+		break;
+	case "check-pr":
+		checkPr(positional[0]);
+		break;
+	case "--version":
+	case "version":
+		console.log(VERSION);
+		break;
+	default:
+		console.log("Usage: stdd <init|check|check-pr|doctor> [dir|pr-body-file] [--tools claude,codex]");
+		process.exit(command ? 1 : 0);
+}

package/method/README.md

@@ -0,0 +1,141 @@
+# The STDD Method
+
+This is the working contract. It is written for the agent or developer doing
+the change, in the order the work happens.
+
+## Sources of truth
+
+Every repository adopting STDD names a **permanent docs tree** (for example
+`docs/`) with an explicit hierarchy — typically product intent above domain
+rules above implementation layers. When layers disagree, stop and reconcile
+before implementing.
+
+Three artifacts make claims about behavior, each in its own way:
+
+- **Docs are the intended contract** — what the system is supposed to do.
+- **Tests are the executable contract** — what the system provably does.
+- **Code is the observed implementation** — what the system actually does.
+
+A disagreement between them blocks implementation until they are reconciled.
+None silently overrides the others: stale docs get corrected, wrong tests get
+fixed, accidental behavior gets documented or removed — each resolution is an
+explicit decision, not a default in favor of any one artifact.
+
+## The loop
+
+```
+classify → read docs → docs edit (the spec) → failing test → implement → verify → PR evidence
+```
+
+1. **Classify the change.**
+   - *Behavior:* anything a user, operator, or downstream system can observe —
+     workflows, pricing, states, permissions, API contracts, copy with
+     business meaning.
+   - *Implementation-only:* refactors, lint fixes, build plumbing, mechanical
+     dependency updates that alter no behavior or architecture contract.
+2. **Read the relevant docs first.** For behavior changes, read the matching
+   source-of-truth documents before proposing anything.
+3. **Edit the docs — that edit is the spec.** If the docs are missing, stale,
+   or ambiguous, update them before tests and code. Make the docs edit the
+   first reviewable unit — the first commit where commits are used, otherwise
+   the opening docs-only diff of the PR — so the behavior contract can be
+   reviewed on its own. If the docs already cover the behavior, do not add
+   duplicate prose — record that they were checked (see PR evidence).
+4. **Write the failing test.** Red before green. Exception below.
+5. **Implement** until the test passes, then refactor.
+6. **Verify with the narrowest meaningful command.** Never claim "done",
+   "fixed", or "clean" without fresh verification evidence.
+7. **State PR evidence.** Every PR carries exactly one of:
+   - `Docs updated first:` — list the changed docs;
+   - `Docs checked, no change needed:` — list the docs and the reason;
+   - `Docs not applicable:` — why the change is implementation-only.
+
+   The line must name its evidence — docs paths or a reason. A bare label
+   with nothing after the colon fails `stdd check-pr`, and only a line
+   starting at the beginning of a line counts (quoted templates and code
+   blocks do not).
+
+## The frontend exception: design-first
+
+Frontend **visual** work — layout, styling, markup structure, presentation
+copy, component composition — is design-first, not test-first. A
+failing-test-first loop forces the visual outcome to be specified before it
+is explored; brittle rendering assertions then punish every design iteration.
+
+The exception covers presentation, not meaning. Copy with business meaning —
+prices, statuses, permissions, legal text, anything a user relies on as a
+fact — is **behavior**: it goes through the docs edit and the normal loop.
+Only its visual arrangement is design-first.
+
+- Build the visual part freely; verify it visually (screenshots reviewed by a
+  human).
+- Never write tests asserting static copy, class names, or pure rendering
+  output.
+- After the visual part settles, add tests only for real behavior contracts:
+  hooks, formatters, state transitions, eligibility and conditional logic,
+  accessibility roles.
+- Client-side **logic** follows the normal loop.
+
+## Working artifacts are never committed
+
+Plans, spec files, todo lists, handoff notes, and execution logs are working
+artifacts. They help one session and go stale immediately after. Committed,
+they outrank fresher docs in code search and become a second source of truth.
+
+Where their content belongs instead:
+
+| Content | Home |
+| --- | --- |
+| Durable rules (behavior, architecture, conventions) | The permanent docs tree, same PR |
+| Design rationale, scope decisions, rejected alternatives | The PR description |
+| Designs for deferred (not yet implemented) work | Dated entries in the project log (e.g. `docs/project/`) |
+| Task lists, sequencing | Ephemeral: session scratchpad, PR body |
+
+The project log is **not canonical**: its entries are dated records of
+decisions and future intentions, never a description of the present. Cite
+canonical docs for how the system behaves; cite the project log only for why
+something is deferred or was decided.
+
+Because a plain `grep` cannot tell authority levels apart, the boundary is
+made machine-readable on both sides. Every project-log entry starts with
+frontmatter declaring itself non-canonical:
+
+```yaml
+---
+authority: non-canonical
+status: deferred
+---
+```
+
+And the agent instructions `stdd init` generates carry a retrieval rule: do
+not search the project log unless the user explicitly asks for historical
+rationale or deferred work.
+
+`stdd check` enforces the artifact ban in CI; `stdd check-pr` enforces the
+PR evidence line; `stdd doctor` reports a repository's overall adoption
+health (setup, canonical docs, misleading artifacts, generated-file drift). The rest of the method is review discipline — anything
+that later proves mechanically checkable should move into `stdd check`.
+
+## Bug fixes and refactors
+
+- **Bug fix:** reproduce the symptom in a test before editing. Fix the root
+  cause, not the symptom.
+- **Refactor:** prove behavior preservation with existing tests, typecheck,
+  or focused characterization tests. No docs edit needed when behavior and
+  contracts are unchanged.
+
+## Style for docs
+
+Concise. Short, direct sentences. Do not omit words that carry meaning. One
+rule lives in one document — link, don't duplicate. Canonical docs are
+written in English and describe the **present**: temporal narrative
+("previously", "no longer") belongs in git history and PR descriptions —
+`stdd check` flags it.
+
+## What stdd does not cover
+
+stdd is a process contract, not an engineering standard. Architecture rules,
+dependency-injection styles, error-handling policy, tenant/auth/data safety,
+and database-migration policy stay in the adopting team's own contract
+(typically `AGENTS.md`) and docs tree. stdd tells you *where* such rules
+live and *when* they must be written — not what they should say.

package/package.json

@@ -0,0 +1,50 @@
+{
+	"name": "@stdd/cli",
+	"version": "0.0.1",
+	"description": "Spec + Test Driven Development — a markdown-first methodology kit for teams building software with AI coding agents",
+	"type": "module",
+	"bin": {
+		"stdd": "cli/stdd.mjs"
+	},
+	"files": [
+		"cli/",
+		"method/",
+		"playbooks/",
+		"templates/",
+		"adapters/"
+	],
+	"scripts": {
+		"test": "node --test",
+		"check": "biome ci .",
+		"format": "biome check --fix .",
+		"selfcheck": "node cli/stdd.mjs check ."
+	},
+	"engines": {
+		"node": ">=20"
+	},
+	"keywords": [
+		"sdd",
+		"tdd",
+		"stdd",
+		"spec-driven-development",
+		"test-driven-development",
+		"ai-agents",
+		"claude-code",
+		"codex",
+		"methodology",
+		"workflow"
+	],
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/vsem-azamat/stdd.git"
+	},
+	"bugs": {
+		"url": "https://github.com/vsem-azamat/stdd/issues"
+	},
+	"homepage": "https://github.com/vsem-azamat/stdd#readme",
+	"author": "Azamat Almazbek uulu",
+	"license": "MIT",
+	"devDependencies": {
+		"@biomejs/biome": "^2.3.8"
+	}
+}

package/playbooks/brainstorming.md

@@ -0,0 +1,43 @@
+---
+name: stdd-brainstorming
+description: Shape a fuzzy idea into an agreed behavior contract before any plan or code
+when: A non-trivial change is requested and the requirements, scope, or approach are not yet pinned down.
+---
+
+# Brainstorming
+
+The goal is agreement on **what** and **why** before anyone invests in **how**.
+The output is not a document — it is a shared understanding that becomes a
+docs edit and a PR description.
+
+## Process
+
+1. **Understand the current state first.** Read the relevant docs and the code
+   the change will touch. Questions asked from ignorance waste the other
+   side's time; questions asked from knowledge sharpen the idea.
+2. **Ask one question at a time.** Prefer questions that eliminate whole
+   branches of the design space: who is it for, what triggers it, what must
+   never happen, what is explicitly out of scope.
+3. **Challenge scope creep in both directions.** If the idea is bigger than
+   the need, say so and propose the smaller version. If the stated need hides
+   a larger real problem, surface it.
+4. **Propose 2–3 approaches with a recommendation.** For each: one paragraph,
+   the trade-off that actually matters, and what it costs later. Recommend
+   one; do not present a menu without an opinion.
+5. **Converge on the behavior contract.** State the agreed behavior as rules
+   precise enough to test. Confirm them explicitly.
+
+## Output
+
+- The agreed rules become the **docs edit** (the spec) — the first commit of
+  the branch.
+- The rationale, rejected alternatives, and scope decisions go into the
+  **PR description** when the branch opens.
+- Nothing from this conversation is committed as a standalone file.
+
+## Anti-patterns
+
+- Jumping to implementation detail while behavior is still unsettled.
+- Asking multiple stacked questions at once.
+- Writing a "spec document" instead of editing the real docs.
+- Agreeing silently: if you disagree with the direction, say so with reasons.

package/playbooks/debugging.md

@@ -0,0 +1,36 @@
+---
+name: stdd-debugging
+description: Find and fix the root cause of a defect, not its symptom
+when: A bug, crash, failing test, or unexplained behavior is reported.
+---
+
+# Debugging
+
+The discipline: no edit before a reproduction, no fix before a diagnosis.
+
+## Process
+
+1. **Reproduce first.** Turn the report into a deterministic reproduction —
+   ideally a failing test. If you cannot reproduce it, you are not debugging
+   yet; you are gathering facts.
+2. **Read the actual error.** The full message, the stack, the logs around
+   it. Do not pattern-match a familiar-looking symptom to a known failure —
+   verify the evidence supports *this* cause.
+3. **Form one hypothesis and test it cheaply.** Predict what you will observe
+   if the hypothesis is true, then look. One hypothesis at a time; a change
+   made under two hypotheses proves neither.
+4. **Fix the root cause minimally.** The smallest change that removes the
+   cause. Resist drive-by cleanup — it obscures the fix in review.
+5. **Keep the reproduction as a regression test.** Red before the fix, green
+   after, committed with it.
+6. **Verify the fix in the original context**, not only in the reduced
+   reproduction.
+
+## Stop rules
+
+- Two failed fix attempts mean the diagnosis is wrong. Stop editing, go back
+  to step 2, and widen what you consider suspect — including your own
+  earlier changes and the test itself.
+- If the evidence contradicts the reported story, surface the contradiction
+  instead of forcing a fix that matches the story.
+- A fix you cannot explain is not a fix. Do not ship it.

package/playbooks/planning.md

@@ -0,0 +1,39 @@
+---
+name: stdd-planning
+description: Turn an agreed behavior contract into an executable, verifiable sequence of work
+when: The behavior contract is agreed (docs edit drafted or committed) and the change is large enough to need ordered steps.
+---
+
+# Planning
+
+A plan is a disposable working artifact: it guides one execution and is thrown
+away. It is never committed as a file — its home is the PR description (for
+the durable summary) and the session's scratchpad (for the working copy).
+
+## Structure
+
+A good plan has, in order:
+
+1. **Intent** — one paragraph: the problem and the agreed direction.
+2. **Docs delta** — which permanent docs change and how (added / modified /
+   removed rules, named per target file). This is the spec surface of the
+   plan; keep it exact so the docs edit is mechanical.
+3. **Steps** — each step small enough to verify independently. Per step:
+   - what changes (files, functions);
+   - the failing test that gates it (or the visual check, for frontend
+     visual work — see the design-first exception in the method);
+   - the verification command.
+4. **Out of scope** — what this change deliberately does not do.
+5. **Risks** — what could invalidate the plan and how you would notice.
+
+## Rules
+
+- Order steps so the system stays green between them.
+- Write verification per step, not one "run all tests" at the end.
+- A step that cannot fail its check is not a step — merge it into another.
+- When execution contradicts the plan, update the plan, do not force the
+  plan onto reality. If the *intent* changed, stop and re-enter
+  brainstorming.
+- Keep the durable parts flowing to their homes as you go: rules → docs
+  edit, rationale → PR description. The plan itself must stay deletable at
+  any moment without information loss.

package/playbooks/worktrees.md

@@ -0,0 +1,39 @@
+---
+name: stdd-worktrees
+description: Work in an isolated workspace without fighting the platform's native isolation
+when: Starting implementation work that should not disturb the user's current checkout.
+---
+
+# Isolated Workspaces
+
+## Order of preference
+
+1. **Detect existing isolation.** If you are already in a linked worktree or
+   a platform-managed sandbox, use it. Never nest worktrees. (Check:
+   `git rev-parse --git-dir` differs from `--git-common-dir`, and you are not
+   in a submodule.)
+2. **Use the platform's native worktree tool** if one exists. Manual
+   `git worktree add` alongside a native tool creates state the platform
+   cannot see or clean up.
+3. **Fall back to `git worktree add`** only when neither applies:
+   - Put worktrees in a dedicated ignored directory (`.worktrees/` at the
+     repo root by default).
+   - Verify the directory is git-ignored **before** creating the worktree;
+     add it to `.gitignore` first if not.
+   - Branch from the repository's integration branch unless told otherwise.
+
+## After creating
+
+- Run the project's dependency setup (install, build) so the workspace is
+  self-sufficient.
+- Run the narrowest baseline verification before changing anything. If the
+  baseline is already red, report it and ask before proceeding — otherwise
+  you cannot tell your breakage from pre-existing breakage.
+
+## Shared state warnings
+
+- The git stash stack is shared across all worktrees of one repository.
+  Prefer a temporary WIP commit over stashing; if you must stash, tag the
+  entry and apply (not pop) by its SHA.
+- Never `cd` out of your assigned worktree into the main checkout to "fix
+  something quickly" — open work there belongs to someone else.

package/templates/deferred-design.md

@@ -0,0 +1,44 @@
+# Deferred Design Template
+
+A design for work that is agreed but not yet scheduled. Lives as a **dated
+entry** in the project log (e.g. `docs/project/`), never as a spec file next
+to canonical docs. Delete the entry when the work ships or is abandoned.
+
+The frontmatter is mandatory: it is the machine-readable marker that keeps
+agent retrieval authority-aware — canonical docs never carry
+`authority: non-canonical`, project-log entries always do.
+
+```markdown
+---
+authority: non-canonical
+status: deferred
+---
+
+# <Title>
+
+Last updated: <YYYY-MM-DD>
+
+- Status: Deferred | Decision needed | Ready | Blocked
+- Priority: High | Medium | Low
+
+## Problem
+
+<What hurts and who it hurts. Impact if never done.>
+
+## Agreed direction
+
+<The design, as rules precise enough to implement from. Note explicitly that
+this describes FUTURE behavior — canonical docs still describe the present.>
+
+## Why deferred
+
+<The reason it is not being done now.>
+
+## Resume condition
+
+<The concrete trigger that should restart this work.>
+
+## Acceptance criteria
+
+<How we will know it is done.>
+```

package/templates/pr-description.md

@@ -0,0 +1,35 @@
+# PR Description Template
+
+The PR description is the durable home for everything that is not a rule:
+rationale, scope decisions, rejected alternatives. Copy, fill, delete unused
+sections.
+
+```markdown
+## Why
+
+<The problem, one paragraph. Link the discussion if there was one.>
+
+## What changed
+
+<Behavior first, implementation second. Bullets.>
+
+## Decisions and alternatives
+
+<Choices made and what was rejected, with the reason. This is the section
+future readers will thank you for — it never goes in the docs tree.>
+
+## Out of scope
+
+<What this PR deliberately does not do.>
+
+## Docs evidence
+
+<Exactly one of:>
+Docs updated first: <list of changed docs>
+Docs checked, no change needed: <docs + reason>
+Docs not applicable: <why implementation-only>
+
+## Verification
+
+<Commands run and their results. Screenshots for visual work.>
+```