@sabaiway/agent-workflow-kit 1.0.0

package/references/scripts/check-docs-size.test.mjs

@@ -0,0 +1,180 @@
+import { describe, it, beforeEach, afterEach } from 'node:test';
+import { expect } from './_expect-shim.mjs';
+import { mkdtemp, writeFile, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import {
+  parseFrontmatter,
+  parseStaleAfter,
+  computeToday,
+  inspectFile,
+  buildIndex,
+  checkIndexFreshness,
+} from './check-docs-size.mjs';
+
+describe('parseFrontmatter', () => {
+  it('extracts scalar fields from valid YAML frontmatter', () => {
+    const text = '---\ntype: reference\nmaxLines: 500\nstaleAfter: 30d\n---\n\nbody.';
+    const fm = parseFrontmatter(text);
+    expect(fm).toEqual({
+      type: 'reference',
+      maxLines: '500',
+      staleAfter: '30d',
+    });
+  });
+
+  it('returns null when no frontmatter block is present', () => {
+    expect(parseFrontmatter('just body text\n')).toBeNull();
+  });
+
+  it('skips lines that do not match key:value pattern', () => {
+    const text = '---\ntype: reference\n# stray comment\nmaxLines: 100\n---\n';
+    const fm = parseFrontmatter(text);
+    expect(fm).toEqual({ type: 'reference', maxLines: '100' });
+  });
+});
+
+describe('parseStaleAfter', () => {
+  it('parses Nd into Number', () => {
+    expect(parseStaleAfter('7d')).toBe(7);
+    expect(parseStaleAfter('30d')).toBe(30);
+  });
+
+  it('returns null for "never", empty, or undefined', () => {
+    expect(parseStaleAfter('never')).toBeNull();
+    expect(parseStaleAfter('')).toBeNull();
+    expect(parseStaleAfter(undefined)).toBeNull();
+  });
+
+  it('returns null for invalid formats', () => {
+    expect(parseStaleAfter('7days')).toBeNull();
+    expect(parseStaleAfter('7')).toBeNull();
+  });
+});
+
+describe('computeToday', () => {
+  it('parses YYYY-MM-DD into UTC-midnight Date', () => {
+    const d = computeToday('2026-05-24');
+    expect(d.toISOString()).toBe('2026-05-24T00:00:00.000Z');
+  });
+
+  it('returns a Date when todayStr is null (no-throw smoke)', () => {
+    const d = computeToday(null);
+    expect(d).toBeInstanceOf(Date);
+    expect(Number.isNaN(d.getTime())).toBe(false);
+  });
+});
+
+describe('inspectFile', () => {
+  let dir;
+
+  beforeEach(async () => {
+    dir = await mkdtemp(join(tmpdir(), 'check-docs-size-test-'));
+  });
+
+  afterEach(async () => {
+    await rm(dir, { recursive: true, force: true });
+  });
+
+  it('reports no errors and no warnings for an in-cap, fresh file', async () => {
+    const path = join(dir, 'fresh.md');
+    await writeFile(
+      path,
+      '---\ntype: reference\nlastUpdated: 2026-05-24\nstaleAfter: 30d\nmaxLines: 100\n---\n\n# OK\n',
+    );
+    const result = await inspectFile(path, computeToday('2026-05-24'));
+    expect(result.errors).toEqual([]);
+    expect(result.warnings).toEqual([]);
+  });
+
+  it('reports an error when lineCount > maxLines', async () => {
+    const path = join(dir, 'big.md');
+    const body = '\n'.repeat(20); // 20 lines of body → total ~26
+    await writeFile(
+      path,
+      `---\ntype: reference\nlastUpdated: 2026-05-24\nstaleAfter: 30d\nmaxLines: 5\n---\n\n# Too big${body}`,
+    );
+    const result = await inspectFile(path, computeToday('2026-05-24'));
+    expect(result.errors.some((e) => /lines > maxLines/.test(e))).toBe(true);
+  });
+
+  it('reports an error when frontmatter is missing maxLines', async () => {
+    const path = join(dir, 'no-cap.md');
+    await writeFile(path, '---\ntype: reference\nlastUpdated: 2026-05-24\n---\n\nbody.\n');
+    const result = await inspectFile(path, computeToday('2026-05-24'));
+    expect(result.errors).toContain('frontmatter missing maxLines');
+  });
+
+  it('reports a warning when lastUpdated is older than staleAfter window', async () => {
+    const path = join(dir, 'stale.md');
+    await writeFile(
+      path,
+      '---\ntype: reference\nlastUpdated: 2026-01-01\nstaleAfter: 30d\nmaxLines: 100\n---\n\nbody.\n',
+    );
+    const result = await inspectFile(path, computeToday('2026-05-24'));
+    expect(result.warnings.length).toBeGreaterThan(0);
+    expect(result.warnings[0]).toMatch(/staleAfter/);
+    expect(result.errors).toEqual([]);
+  });
+
+  it('reports a single error when frontmatter is missing entirely', async () => {
+    const path = join(dir, 'no-fm.md');
+    await writeFile(path, '# Just a body, no frontmatter.\n');
+    const result = await inspectFile(path, computeToday('2026-05-24'));
+    expect(result.frontmatter).toBeNull();
+    expect(result.errors).toContain('missing YAML frontmatter');
+  });
+});
+
+// Synthetic row matching the shape produced by `inspectFile` + `formatRow`.
+const makeRow = (path, overrides = {}) => ({
+  path,
+  lineCount: 50,
+  frontmatter: { type: 'reference', maxLines: '100', lastUpdated: '2026-05-29', staleAfter: '30d' },
+  errors: [],
+  warnings: [],
+  ...overrides,
+});
+
+describe('buildIndex', () => {
+  it('is deterministic, sorts rows by path, and excludes index.md itself', () => {
+    const rows = [
+      makeRow('docs/ai/index.md'),
+      makeRow('docs/ai/b.md'),
+      makeRow('docs/ai/a.md'),
+    ];
+    const out = buildIndex(rows, '2026-05-29');
+    expect(out).toBe(buildIndex(rows, '2026-05-29')); // deterministic
+    expect(out).not.toMatch(/\[`index\.md`\]/); // index.md row excluded
+    expect(out.indexOf('a.md')).toBeLessThan(out.indexOf('b.md')); // sorted
+    expect(out).toMatch(/lastUpdated: 2026-05-29/); // header date is the argument
+  });
+});
+
+// `checkIndexFreshness` drives the `--check-index` exit code:
+//   fresh === true  → script exits 0
+//   fresh === false → script exits 1 ("index stale, regenerate with --write-index")
+describe('checkIndexFreshness', () => {
+  const rows = [makeRow('docs/ai/a.md'), makeRow('docs/ai/b.md')];
+
+  it('reports fresh when on-disk matches the regenerated index (→ exit 0)', () => {
+    const onDisk = buildIndex(rows, '2026-05-29');
+    expect(checkIndexFreshness(rows, onDisk).fresh).toBe(true);
+  });
+
+  it('reports stale when a source row drifted, e.g. line count changed (→ exit 1)', () => {
+    const onDisk = buildIndex(rows, '2026-05-29');
+    const drifted = [makeRow('docs/ai/a.md', { lineCount: 999 }), makeRow('docs/ai/b.md')];
+    expect(checkIndexFreshness(drifted, onDisk).fresh).toBe(false);
+  });
+
+  it('reports stale when index.md is missing entirely (→ exit 1)', () => {
+    expect(checkIndexFreshness(rows, null).fresh).toBe(false);
+  });
+
+  it('does NOT flag stale on a mere day-rollover with unchanged content (uses on-disk header date)', () => {
+    const onDisk = buildIndex(rows, '2026-05-01'); // index regenerated weeks ago
+    // Same source rows, "today" is later — content unchanged, so it must stay fresh.
+    expect(checkIndexFreshness(rows, onDisk).fresh).toBe(true);
+  });
+});

package/references/scripts/install-git-hooks.mjs

@@ -0,0 +1,83 @@
+#!/usr/bin/env node
+// Idempotent installer for the project's git hooks.
+//
+// Installs `.git/hooks/pre-commit` running the docs cap-validator + index-freshness
+// gate + changelog/issues rotation-freshness checks + the `scripts/` test
+// suite, so docs files cannot drift over their declared `maxLines`, the auto-generated
+// `index.md` navigator cannot silently fall out of sync, stale archive entries never
+// reach a commit, and regressions to the scripts themselves are caught at commit time.
+//
+// Package-manager-agnostic: the hook calls the scripts via `node` directly (no pnpm/npm
+// assumption). Re-running is safe — the script detects a previously installed hook via
+// the MAGIC_MARKER comment and rewrites only that file.
+//
+// To bypass once (only when truly justified): `git commit --no-verify`.
+
+import { writeFile, readFile, mkdir, chmod } from 'node:fs/promises';
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, resolve, basename } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const ROOT = resolve(__dirname, '..');
+const HOOKS_DIR = resolve(ROOT, '.git/hooks');
+const PRE_COMMIT_PATH = resolve(HOOKS_DIR, 'pre-commit');
+
+const readProjectName = () => {
+  try {
+    const pkg = JSON.parse(readFileSync(resolve(ROOT, 'package.json'), 'utf8'));
+    if (pkg.name) return pkg.name;
+  } catch {
+    /* no package.json — fall back to repo dir basename */
+  }
+  return basename(ROOT);
+};
+
+const MAGIC_MARKER = `# ${readProjectName()}:install-git-hooks.mjs`;
+
+const PRE_COMMIT_CONTENT = `#!/usr/bin/env bash
+${MAGIC_MARKER}
+# Auto-installed by scripts/install-git-hooks.mjs (run it from "prepare" or by hand).
+# Runs the docs cap-validator + index-freshness gate + rotation-freshness checks
+# + the scripts/ test suite before every commit, so files cannot drift over their
+# declared maxLines, the auto-generated index.md cannot silently go stale, stale
+# archive entries never reach a commit, and regressions to the scripts are caught.
+set -e
+node scripts/check-docs-size.mjs
+node scripts/check-docs-size.mjs --check-index
+node scripts/archive-changelog.mjs --check
+node scripts/archive-issues.mjs --check
+node --test scripts/*.test.mjs
+`;
+
+const main = async () => {
+  if (!existsSync(resolve(ROOT, '.git'))) {
+    console.log('[install-git-hooks] .git directory not found — skipping (not a git checkout).');
+    return;
+  }
+  await mkdir(HOOKS_DIR, { recursive: true });
+
+  if (existsSync(PRE_COMMIT_PATH)) {
+    const existing = await readFile(PRE_COMMIT_PATH, 'utf8');
+    if (existing.includes(MAGIC_MARKER) && existing === PRE_COMMIT_CONTENT) {
+      console.log('[install-git-hooks] pre-commit already up to date.');
+      return;
+    }
+    if (!existing.includes(MAGIC_MARKER)) {
+      console.warn(
+        '[install-git-hooks] WARNING: .git/hooks/pre-commit exists and was not installed by this script. Refusing to overwrite — remove or merge it manually.',
+      );
+      process.exit(1);
+    }
+  }
+
+  await writeFile(PRE_COMMIT_PATH, PRE_COMMIT_CONTENT, 'utf8');
+  await chmod(PRE_COMMIT_PATH, 0o755);
+  console.log('[install-git-hooks] installed .git/hooks/pre-commit (docs caps + index freshness + archive checks + scripts/ tests).');
+};
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/references/templates/AGENTS.md

@@ -0,0 +1,78 @@
+# AI Agent Algorithm — {{PROJECT_NAME}}
+
+> **Execution protocol for AI agents working on this project.**
+> **This file is your entry point. Read it first, then follow the Memory Map.**
+> `AGENTS.md` is the cross-agent standard — Codex / Cursor / Windsurf / Copilot read it natively. Tool-specific aliases (e.g. `CLAUDE.md` for Claude Code) are symlinks to this file — single source, no duplication.
+
+---
+
+## 🧭 Memory Map
+
+All project knowledge lives in `docs/ai/`. Layered, lazy-loaded context:
+
+- **Always-loaded** — this file + [`docs/ai/index.md`](./docs/ai/index.md) (auto-generated navigator).
+- **On-demand** — read a specific `docs/ai/` file only when its "Read When" applies.
+- **Hierarchical** — subdirectory `AGENTS.md` files (with a `CLAUDE.md` symlink for Claude Code) load automatically when you work in that folder.
+- **Archive** — `docs/ai/history/` (rolling: HOT changelog → WARM `recent.md` → COLD per-month).
+
+| File | Read When... | Update When... |
+|------|--------------|----------------|
+| [`docs/ai/handover.md`](./docs/ai/handover.md) | **Start of every session** | End of session if context changed |
+| [`docs/ai/active_plan.md`](./docs/ai/active_plan.md) | Picking next task | Completing a task |
+| [`docs/ai/current_state.md`](./docs/ai/current_state.md) | Need system overview | After feature completion |
+| [`docs/ai/technical_specification.md`](./docs/ai/technical_specification.md) | App overview & data models | Data-model changes |
+| [`docs/ai/pages/index.md`](./docs/ai/pages/index.md) | Understanding a page | Page behaviour changes |
+| [`docs/ai/architecture.md`](./docs/ai/architecture.md) | Understanding structure | Architecture changes |
+| [`docs/ai/known_issues.md`](./docs/ai/known_issues.md) | Debugging | New issue discovered |
+| [`docs/ai/decisions.md`](./docs/ai/decisions.md) | Considering alternatives | New ADR |
+| [`docs/ai/changelog.md`](./docs/ai/changelog.md) | Reviewing history | After each session |
+| [`docs/ai/env_commands.md`](./docs/ai/env_commands.md) | Need a command | Commands change |
+| [`docs/ai/tech_reference.md`](./docs/ai/tech_reference.md) | Need a pattern | New reusable pattern |
+| [`docs/ai/agent_rules.md`](./docs/ai/agent_rules.md) | **Before any code change** | Protocol changes |
+
+---
+
+## 🚀 Session Protocols
+
+Start-of-session, during-work, and task-completion procedures live in [`docs/ai/agent_rules.md`](./docs/ai/agent_rules.md) §1. **Read it before any code change.**
+
+Planning (plan files, vocabulary, lifecycle, mandatory Cleanup) → the project's planning skill / `docs/ai/agent_rules.md` §"Planning Workflow".
+
+---
+
+## 🚫 Hard Constraints
+
+> Adapt to this stack — remove rows that don't apply. Style rules should be linter-enforced, not prose.
+
+| Rule | Enforcement |
+|------|-------------|
+| No `export default` (named exports only) | Linter |
+| No `any` / no unsafe casts | Linter / type-checker |
+| Functional style (no mutation in app code) | Linter |
+| No single-letter variables | Code review |
+| Interactive elements semantic (button/link, not div+onClick) | Linter / a11y |
+| No hardcoded colors — design tokens only | Code review |
+| No business logic in components → hooks/services | Architecture review |
+| No changes without tests (TDD) | Required |
+| Check page docs before changes; update them after | Process |
+| Ask user before committing | Process |
+| Every page has an HTML-validity / a11y E2E test | Required |
+| **No silent failures** — structured logging on every rejected action | Required |
+
+---
+
+## 💡 Quick Commands
+
+| Need | Command |
+|------|---------|
+| Dev server | `{{DEV_COMMAND}}` |
+| All checks | `{{LINT}} && {{TYPECHECK}} && {{TEST}}` |
+| E2E tests | `{{E2E_COMMAND}}` |
+| Docs caps + index freshness | `{{DOCS_CHECK}} && {{DOCS_INDEX_CHECK}}` |
+| Find pattern | `grep -r "pattern" src/` |
+
+Full reference → [`docs/ai/env_commands.md`](./docs/ai/env_commands.md).
+
+---
+
+**Rule:** This file stays CONCISE (≤100 lines). Details go to `docs/ai/`. Never bloat this file.

package/references/templates/active_plan.md

@@ -0,0 +1,31 @@
+---
+type: state
+lastUpdated: {{DATE}}
+scope: sprint
+staleAfter: 30d
+owner: active_plan
+maxLines: 60
+---
+
+# Active Plan
+
+> Tasks ordered by priority. ONE task at a time. Mark done immediately.
+
+## Immediate Priority
+
+### Task 1 — Fill domain-specific docs after first real work
+**Why:** bootstrap seeded structure; real content comes from the first task.
+**Acceptance Criteria:**
+- [ ] `current_state.md` / `architecture.md` reflect reality
+- [ ] First page spec created under `pages/`
+- [ ] Tests passing, docs updated
+
+---
+
+## Next Up (queue)
+
+- [ ] TODO — short reason
+
+## Parking Lot (ideas, not committed)
+
+- TODO

package/references/templates/agent_rules.md

@@ -0,0 +1,85 @@
+---
+type: protocol
+lastUpdated: {{DATE}}
+scope: permanent
+staleAfter: 90d
+owner: none
+maxLines: 150
+---
+
+# AI Agent Rules & Self-Review Protocol — {{PROJECT_NAME}}
+
+Every AI agent working on this project **must** adhere to this protocol before writing code, modifying files, or presenting solutions.
+
+---
+
+## 1. Session Protocols
+
+### 1.1. Start of Session
+Read in order, then confirm before starting:
+1. `docs/ai/handover.md` — where we left off.
+2. `docs/ai/active_plan.md` — pick ONE task from "Immediate Priority".
+3. Confirm with the user: *"I'm taking task X. Confirm?"*
+
+### 1.2. During Work
+**Before any feature:** read the relevant page spec (`docs/ai/pages/<page>.md`). If behaviour changes, update the spec FIRST so docs and code never diverge.
+
+**For every code change:**
+1. Grep for similar implementations — reuse existing patterns.
+2. Check the design-system layer for an existing component; if missing, add it there FIRST, then use it.
+3. Verify changes align with `docs/ai/pages/<page>.md`; for a new page, create a full spec.
+4. Follow §2 (Self-Review): functional style, named exports, full variable names, no magic literals.
+5. Write/update tests FIRST (TDD): unit for pure functions, E2E for user flows.
+6. Run quality checks: lint, type-check, tests.
+
+### 1.3. Task Completion
+Before claiming "done":
+1. Run all quality gates (lint + type-check + tests) — all green.
+2. Update docs: `current_state.md` (feature ready), `changelog.md` (entry), `handover.md` (**REPLACE** the last-session block — session delta, never append; older deltas live in `changelog.md` → `history/`), `pages/<page>.md` (matches implementation). Only bump "Last Updated" when content actually changed.
+3. Run the docs cap-validator + index-freshness gate (pre-commit also enforces). On failure: trim the offending file, or run the changelog rotation if the offender is `changelog.md`.
+4. If the work executed a plan file — run that plan's final **Phase: Cleanup** (see the planning skill / §5). Without it the plan is not done.
+5. **Ask before committing** (§4): report lint / type-check / test counts + docs status, then wait for explicit approval. DO NOT auto-commit.
+
+---
+
+## 2. Self-Review Checklist
+
+Before proposing changes or committing, review against:
+
+### 2.1. Real-World Context
+- Respects the user's locale (translations, decimal separators, encodings/BOM for non-ASCII exports).
+
+### 2.2. Clean Code
+- **No magic literals** — extract string/numeric constants to named consts at module level.
+- **DRY** — no duplicated logic.
+
+### 2.3. Strict Compliance
+- Only `const` (no `let`); no classes — pure functions, closures, modules.
+- Components as arrow functions; no unsafe `any` / casts.
+- Functions start with a verb (`computeTotal`, `getList`).
+
+### 2.4. Quality Gates
+- Always run type-checker, linter, and all tests before committing.
+
+---
+
+## 3. Token & Session Optimization
+
+Split a complex task across sessions for **focus and review hygiene**, not because the window is small. Modern long-context models (e.g. Opus 4.8) hold large working sets well, and a stable always-loaded layer (`AGENTS.md` + `index.md`) stays prompt-cache-warm across turns — split too eagerly and you pay re-boot + cache-miss cost for nothing.
+
+- **Split (separate sessions)** when the *change* is large enough to deserve an isolated review checkpoint: creates/deletes a source or test file, touches several files, alters a dependency / core config / data model / routes, or needs new E2E tests. These are review-hygiene triggers, independent of context size.
+- **Run inline** for small, self-contained work: a few files, no new files, no dependency/schema/route change, light discussion (typos, tweaks, single-line fixes, test additions).
+- **Context size is a soft, secondary signal** — split only when the working context is genuinely large *relative to the window* or you notice degraded recall, never at a fixed token count. Prefer the planning skill's **session-continuity heuristic**: keep going in-session when the accumulated context IS the execution payload (targeted-deep reads of the exact files you'll edit); split when it was broad fan-out noise.
+
+---
+
+## 4. User Interaction
+
+1. **Don't rush to commit.** Prepare changes, run local quality checks, report progress with test outcomes.
+2. **Get explicit approval** before staging/committing or moving to the next phase.
+
+---
+
+## 5. Planning Workflow
+
+All plan-file rules — vocabulary (Plan → Phase → Step → Substep), lifecycle (`docs/plans/<slug>.md`, gitignored, never committed), the mandatory final **Phase: Cleanup**, the `docs/plans/queue.md` series-index, "all work in plans", the plan-then-execute split — live in the project's planning skill. It is the single source of truth and overrides the generic `writing-plans` skill.

package/references/templates/architecture.md

@@ -0,0 +1,49 @@
+---
+type: reference
+lastUpdated: {{DATE}}
+scope: permanent
+staleAfter: 90d
+owner: none
+maxLines: 350
+---
+
+# Architecture
+
+> How the code is organized. Layers, boundaries, where new code goes.
+
+## Layers
+
+```
+UI Components       ← {{src/components/}}
+    ↓
+Hooks / Composition ← {{src/hooks/}}
+    ↓
+Services (pure)     ← {{src/services/}}
+    ↓
+State / Storage     ← {{src/store/ or src/data/}}
+    ↓
+Types / Schemas     ← {{src/types/}}
+```
+
+## Module Boundaries
+
+- **Components** — render only. No fetching, no business logic.
+- **Hooks** — orchestration; combine services + state.
+- **Services** — pure functions. Easy to test.
+- **State** — single source of truth per domain.
+
+## File Tree (top level)
+
+```
+{{FILL FROM REAL src/}}
+```
+
+## Extension Points
+
+- Add a new page → {{where + what to update}}
+- Add a new domain entity → {{where}}
+- Add a new shared component → {{where + docs to update}}
+
+## Split policy (when this file nears its cap)
+
+At ~90% of `maxLines`, split the deepest detail into `architecture-details.md` and keep this file high-level. Record the split as an ADR. Bumping the cap instead of splitting is a conscious exception, justified in that ADR.

package/references/templates/changelog.md

@@ -0,0 +1,24 @@
+---
+type: history
+lastUpdated: {{DATE}}
+scope: permanent
+staleAfter: never
+owner: none
+maxLines: 700
+---
+
+# AI Session Changelog
+
+> One entry per session. Newest at the top. Entries roll off to `history/recent.md` (WARM) then `history/YYYY-MM.md` (COLD) via the archive script.
+> Heading format is load-bearing for rotation: `## YYYY.MM.DD — <title>`.
+
+## {{DATE}} — Bootstrap
+
+**Goal:** Initialise the AI-agent memory system.
+**Changes:**
+- Created `AGENTS.md` (entry point) + `CLAUDE.md` symlink.
+- Created `docs/ai/` with the spec files + `pages/`.
+- Installed the docs cap-validator / index-freshness / archive scripts + pre-commit hook.
+- Recorded the real stack, scripts, and architecture into the relevant files.
+
+**Quality gates:** n/a (no code changes).

package/references/templates/current_state.md

@@ -0,0 +1,36 @@
+---
+type: state
+lastUpdated: {{DATE}}
+scope: permanent
+staleAfter: 30d
+owner: current_state
+maxLines: 120
+---
+
+# Current State
+
+> Snapshot of what's built and what works. Updated after each feature completion.
+
+## Stack
+
+| Layer | Tool |
+|-------|------|
+| Language | {{LANGUAGE}} |
+| Framework | {{FRAMEWORK}} |
+| Package manager | {{PACKAGE_MANAGER}} |
+| Test runner | {{TEST_RUNNER}} |
+| Linter | {{LINTER}} |
+
+## Feature Status
+
+| Feature | Status | Notes |
+|---------|--------|-------|
+| AI memory system | ✅ Ready | Bootstrapped {{DATE}} |
+| {{FEATURE}} | 🟡 In progress / ⛔ Blocked | {{note}} |
+
+## Quality Gates
+
+- lint: {{N}} errors / {{M}} warnings
+- type-check: {{clean / N errors}}
+- unit tests: {{N passed in M files}}
+- E2E tests: {{N passed}}

package/references/templates/decisions.md

@@ -0,0 +1,44 @@
+---
+type: reference
+lastUpdated: {{DATE}}
+scope: permanent
+staleAfter: never
+owner: none
+maxLines: 500
+---
+
+# Architecture Decision Records (ADRs)
+
+> Every significant choice that has long-term consequences. Newest at the bottom. Link related ADRs with `[[AD-XXX]]`.
+
+## AD-001 — Adopt AI-agent memory system (`docs/ai/`)
+
+**Date:** {{DATE}}
+**Status:** Accepted
+
+**Context.** Multi-session AI work loses context between runs. Without a structured handover, each new session re-reads code, re-discovers decisions, and repeats past mistakes.
+
+**Decision.** Adopt a Memory Map in `AGENTS.md` (entry point — the cross-agent standard; tool aliases like `CLAUDE.md` symlink to it) + structured files under `docs/ai/`. Define three protocols (Start / During / Complete). Enforce frontmatter caps + index freshness + 3-tier archive via a pre-commit hook. Deployed via the `agent-workflow-kit` skill.
+
+**Rationale.** Single entry + structured spec files = constant boot-up cost regardless of project size. ADRs prevent litigating the same decision twice. `pages/<page>.md` keeps behaviour canonical (docs > assumptions). Caps + archive keep files scannable as history grows.
+
+**Consequences.**
+- ➕ Faster session start, less drift between agents.
+- ➕ ADRs as institutional memory; honest `known_issues.md`.
+- ➖ Discipline cost: docs updated alongside code.
+- ➖ A set of markdown files + scripts to maintain.
+
+---
+
+## AD-002 — {{Next decision}}
+
+**Date:** {{DATE}}
+**Status:** Proposed / Accepted / Superseded
+
+**Context.** {{...}}
+**Decision.** {{...}}
+**Consequences.** {{...}}
+
+---
+
+> When this file nears ~90% of its cap, move the oldest Accepted/Superseded ADRs to `decisions-archive.md` (keep the IDs + a one-line pointer here) and record the split. Bumping the cap instead of splitting is a conscious exception, justified in an ADR.

package/references/templates/env_commands.md

@@ -0,0 +1,41 @@
+---
+type: reference
+lastUpdated: {{DATE}}
+scope: permanent
+staleAfter: 90d
+owner: none
+maxLines: 120
+---
+
+# Environment & Commands
+
+> Single reference for all dev/build/test/lint commands. (Mature projects may fold this into a project command skill.)
+
+## Setup
+
+```bash
+{{install command}}
+```
+
+## Daily Loop
+
+| Need | Command |
+|------|---------|
+| Dev server | `{{DEV_COMMAND}}` |
+| Build | `{{BUILD_COMMAND}}` |
+| Lint | `{{LINT}}` |
+| Type-check | `{{TYPECHECK}}` |
+| Unit tests | `{{TEST}}` |
+| Unit tests (one file) | `{{TEST}} {{path/file}}` |
+| E2E tests | `{{E2E_COMMAND}}` |
+| Docs caps | `{{DOCS_CHECK}}` |
+| Docs index (regenerate) | `{{DOCS_INDEX}}` |
+| Docs index (freshness gate) | `{{DOCS_INDEX_CHECK}}` |
+| Changelog rotation | `{{DOCS_ARCHIVE}}` |
+| All checks (pre-commit) | `{{LINT}} && {{TYPECHECK}} && {{TEST}}` |
+
+## Git Conventions
+
+- Branches: `{{convention}}`
+- Commit style: `{{e.g. Conventional Commits}}`
+- PR target: `{{branch}}`