@vpxa/kb 0.1.13 → 0.1.16

package/skills/adr-skill/references/examples.md

@@ -0,0 +1,193 @@
+# ADR Examples
+
+These are filled-out examples showing the same decision at two levels of detail. Use these as reference when drafting ADRs — never leave placeholder text in a real ADR.
+
+## Short Version (Simple Template)
+
+```markdown
+---
+status: accepted
+date: 2025-06-15
+decision-makers: Sarah Chen, Joel
+---
+
+# Use SQLite for local development database
+
+## Context and Problem Statement
+
+Our integration tests require a database but currently hit a shared PostgreSQL instance, causing flaky tests from concurrent writes and slow CI (3+ minute setup per run). We need a fast, isolated database for local dev and CI that doesn't require infrastructure provisioning.
+
+## Decision
+
+Use SQLite (via better-sqlite3) for local development and CI test runs. Production remains on PostgreSQL. We'll use a thin data-access layer that abstracts the database engine, tested against both SQLite and PostgreSQL in CI.
+
+Non-goals: we are NOT migrating production to SQLite or building a full ORM abstraction.
+
+## Consequences
+
+- Good, because CI setup drops from 3+ minutes to ~2 seconds (no DB provisioning)
+- Good, because tests are fully isolated — no shared state between runs
+- Good, because developers can run the full test suite offline
+- Bad, because we must maintain compatibility between SQLite and PostgreSQL SQL dialects
+- Bad, because some PostgreSQL-specific features (JSONB operators, array columns) can't be tested locally
+
+## Implementation Plan
+
+- **Affected paths**: `src/db/client.ts` (new abstraction layer), `src/db/sqlite-client.ts` (new), `src/db/pg-client.ts` (refactored from current inline usage), `tests/setup.ts`, `package.json`
+- **Dependencies**: add `better-sqlite3@11.x` and `@types/better-sqlite3@7.x` as devDependencies; no production dependency changes
+- **Patterns to follow**: existing repository pattern in `src/db/repositories/` — all queries go through repository methods, never raw SQL in business logic
+- **Patterns to avoid**: do not import `better-sqlite3` or `pg` directly outside `src/db/`; do not use PostgreSQL-specific SQL (JSONB operators, `ANY()`, array literals) in shared queries
+
+### Verification
+
+- [ ] `npm test` passes with `DB_ENGINE=sqlite` (default for test env)
+- [ ] `npm test` passes with `DB_ENGINE=postgres` against a real PostgreSQL instance
+- [ ] No imports of `better-sqlite3` or `pg` outside `src/db/`
+- [ ] CI pipeline total time under 90 seconds (was 5+ minutes)
+- [ ] `src/db/client.ts` exports a unified interface used by all repositories
+
+## Alternatives Considered
+
+- Docker PostgreSQL per CI run: Reliable parity, but adds 90s+ startup and requires Docker-in-Docker on CI.
+- In-memory PostgreSQL (pg-mem): Good API compatibility, but incomplete support for our schema (triggers, CTEs) and unmaintained.
+
+## More Information
+
+- Follow-up: create weekly CI job running full suite against real PostgreSQL (#348)
+- Revisit trigger: if dialect-drift bugs exceed 2 per quarter, reconsider Docker PostgreSQL approach
+```
+
+## Long Version (MADR Template)
+
+The same decision with full options analysis:
+
+```markdown
+---
+status: accepted
+date: 2025-06-15
+decision-makers: Sarah Chen, Joel
+consulted: Alex (DBA), Platform team
+informed: Frontend team, QA
+---
+
+# Use SQLite for local development database
+
+## Context and Problem Statement
+
+Our integration tests require a database but currently hit a shared PostgreSQL instance. This causes two problems:
+
+1. Flaky tests from concurrent writes (multiple developers and CI jobs sharing one DB)
+2. Slow CI — each run spends 3+ minutes provisioning and seeding the database
+
+How can we provide a fast, isolated database for local development and CI without sacrificing confidence in production compatibility?
+
+Related: [Use PostgreSQL for production](2025-05-01-use-postgresql-for-production.md) — this decision must not compromise production database choice.
+
+## Decision Drivers
+
+- CI speed: current 3+ minute DB setup is the bottleneck in our 5-minute pipeline
+- Test isolation: zero shared state between parallel test runs
+- Production parity: must catch SQL dialect issues before they hit production
+- Developer experience: should work offline, no external dependencies for `npm test`
+- Maintenance cost: solution should not require a dedicated owner
+
+## Considered Options
+
+- SQLite via better-sqlite3
+- Docker PostgreSQL per CI run
+- In-memory PostgreSQL (pg-mem)
+
+## Decision Outcome
+
+Chosen option: "SQLite via better-sqlite3", because it eliminates the CI bottleneck (2s vs 3+ min), provides full isolation, works offline, and has minimal maintenance cost. The dialect-drift risk is mitigated by a weekly CI job against real PostgreSQL.
+
+### Consequences
+
+- Good, because CI database setup drops from 3+ minutes to ~2 seconds
+- Good, because each test run is fully isolated (file-based DB, no shared state)
+- Good, because developers can run the full test suite offline with zero infrastructure
+- Bad, because we must maintain a data-access abstraction layer to paper over SQL dialect differences
+- Bad, because PostgreSQL-specific features (JSONB operators, array columns, advisory locks) cannot be tested locally
+- Neutral, because the abstraction layer adds ~200 lines of code but also makes future DB migrations easier
+
+## Implementation Plan
+
+- **Affected paths**:
+  - `src/db/client.ts` — new: unified database interface (DatabaseClient type + factory function)
+  - `src/db/sqlite-client.ts` — new: SQLite implementation of DatabaseClient
+  - `src/db/pg-client.ts` — refactor: extract current inline pg usage into DatabaseClient implementation
+  - `src/db/repositories/*.ts` — update: use DatabaseClient instead of direct pg calls
+  - `tests/setup.ts` — update: initialize SQLite by default, read `DB_ENGINE` env var
+  - `tests/fixtures/seed.sql` — update: ensure all seed SQL is dialect-neutral
+  - `.env.test` — new: `DB_ENGINE=sqlite`
+  - `.github/workflows/ci.yml` — update: remove PostgreSQL service container from main CI
+  - `package.json` — add devDependencies
+- **Dependencies**: add `better-sqlite3@11.x`, `@types/better-sqlite3@7.x` as devDependencies
+- **Patterns to follow**:
+  - Repository pattern in `src/db/repositories/` — all database access goes through repository methods
+  - Use parameterized queries exclusively (no string interpolation)
+  - Reference implementation: `src/db/repositories/users.ts` for the expected style
+- **Patterns to avoid**:
+  - Do NOT import `better-sqlite3` or `pg` directly outside `src/db/`
+  - Do NOT use PostgreSQL-specific SQL in shared queries: no `JSONB` operators (`->`, `->>`), no `ANY(ARRAY[...])`, no `ON CONFLICT ... DO UPDATE`
+  - Do NOT use SQLite-specific SQL either — keep queries portable
+- **Configuration**: `DB_ENGINE` env var (`sqlite` | `postgres`), defaults to `sqlite` in test, `postgres` in production
+- **Migration steps**:
+  1. Create `DatabaseClient` interface and SQLite implementation
+  2. Refactor existing pg code into pg implementation
+  3. Update repositories one at a time (each can be a separate PR)
+  4. Update test setup last, once all repositories use the abstraction
+  5. Remove PostgreSQL service container from CI workflow
+
+### Verification
+
+- [ ] `DB_ENGINE=sqlite npm test` passes (all integration tests)
+- [ ] `DB_ENGINE=postgres npm test` passes against a real PostgreSQL 16 instance
+- [ ] `grep -r "from 'better-sqlite3'" src/ --include='*.ts' | grep -v 'src/db/'` returns no results
+- [ ] `grep -r "from 'pg'" src/ --include='*.ts' | grep -v 'src/db/'` returns no results
+- [ ] CI pipeline completes in under 90 seconds (measured on main branch)
+- [ ] `src/db/client.ts` exports `DatabaseClient` interface and `createClient()` factory
+- [ ] `.env.test` sets `DB_ENGINE=sqlite`
+- [ ] Weekly PostgreSQL compatibility CI job exists in `.github/workflows/`
+
+## Pros and Cons of the Options
+
+### SQLite via better-sqlite3
+
+[better-sqlite3](https://github.com/WiseLibs/better-sqlite3) — synchronous SQLite bindings for Node.js.
+
+- Good, because zero infrastructure — just an npm dependency
+- Good, because synchronous API makes test setup/teardown trivial
+- Good, because file-based DBs enable parallelism (one file per test worker)
+- Neutral, because requires a thin abstraction layer (~200 LOC)
+- Bad, because SQL dialect differences (no JSONB, different date handling, no arrays)
+- Bad, because does not exercise PostgreSQL-specific query plans or extensions
+
+### Docker PostgreSQL per CI run
+
+Spin up a fresh PostgreSQL container for each CI job.
+
+- Good, because perfect production parity — same engine, same version
+- Good, because no abstraction layer needed
+- Bad, because adds 90+ seconds to every CI run (image pull + startup + healthcheck)
+- Bad, because requires Docker-in-Docker on CI, adding complexity and security surface
+- Bad, because developers need Docker running locally for `npm test`
+
+### In-memory PostgreSQL (pg-mem)
+
+[pg-mem](https://github.com/oguimbal/pg-mem) — in-memory PostgreSQL emulator for testing.
+
+- Good, because better SQL compatibility than SQLite
+- Good, because no infrastructure needed
+- Bad, because incomplete support for our schema features (triggers, CTEs, lateral joins)
+- Bad, because last published release is 8+ months old — maintenance risk
+- Bad, because debugging failures requires understanding pg-mem's emulation quirks
+
+## More Information
+
+- Follow-up task: create data-access abstraction layer — #347
+- Follow-up task: set up weekly PostgreSQL CI job — #348
+- Related: [Use PostgreSQL for production](2025-05-01-use-postgresql-for-production.md)
+- Revisit trigger: if dialect-drift bugs exceed 2 per quarter, reconsider Docker PostgreSQL approach
+- Code references: after implementation, key files will have `// ADR: 2025-06-15-use-sqlite-for-test-database` comments at entry points
+```

package/skills/adr-skill/references/review-checklist.md

@@ -0,0 +1,77 @@
+# ADR Review Checklist
+
+Use this checklist in Phase 3 to validate an ADR before finalizing. The goal: **could a coding agent read this ADR and start implementing the decision immediately, without asking any clarifying questions?**
+
+## Agent-Readiness Checks
+
+### Context & Problem
+
+- [ ] A reader with no prior context can understand why this decision exists
+- [ ] The trigger is clear (what changed, broke, or is about to break)
+- [ ] No tribal knowledge is assumed — acronyms are defined, systems are named explicitly
+- [ ] Links to relevant issues, PRs, or prior ADRs are included
+
+### Decision
+
+- [ ] The decision is specific enough to act on (not "use a better approach" but "use X for Y")
+- [ ] Scope is bounded — what's in AND what's out (non-goals)
+- [ ] Constraints are explicit and measurable where possible (e.g., "< 200ms p95" not "fast enough")
+
+### Consequences
+
+- [ ] Each consequence is concrete and actionable, not aspirational
+- [ ] Follow-up tasks are identified (migrations, config changes, documentation, new tests)
+- [ ] Risks are stated with mitigation strategies or acceptance rationale
+- [ ] No consequence is a disguised restatement of the decision
+
+### Implementation Plan
+
+- [ ] Affected files/directories are named explicitly (not "the database code" but "src/db/client.ts")
+- [ ] Dependencies to add/remove are specified with version constraints
+- [ ] Patterns to follow reference existing code (not abstract descriptions)
+- [ ] Patterns to avoid are stated (what NOT to do)
+- [ ] Configuration changes are listed (env vars, config files, feature flags)
+- [ ] If replacing something, migration steps are described
+
+### Verification
+
+- [ ] Criteria are checkboxes, not prose
+- [ ] Each criterion is testable — an agent could write a test or run a command to check it
+- [ ] Criteria cover both "it works" (functional) and "it's done right" (structural/architectural)
+- [ ] No criterion is vague ("it performs well" → "p95 latency < 200ms under 100 concurrent requests")
+
+### Options (MADR template)
+
+- [ ] At least two options were genuinely considered (not just "do the thing" vs "do nothing")
+- [ ] Each option has real pros AND cons (not a straw-man comparison)
+- [ ] The justification for the chosen option references specific drivers or tradeoffs
+- [ ] Rejected options explain WHY they were rejected, not just what they are
+
+### Meta
+
+- [ ] Status is set correctly (usually `proposed` for new ADRs)
+- [ ] Date is set
+- [ ] Decision-makers are listed
+- [ ] Title is a verb phrase describing the decision (not the problem)
+- [ ] Filename follows repo conventions
+
+## Quick Scoring
+
+Count the checked items. This isn't a gate — it's a conversation tool.
+
+- **All checked**: Ship it.
+- **1–3 unchecked**: Discuss the gaps with the human. Most can be fixed in a minute.
+- **4+ unchecked**: The ADR needs more work. Go back to Phase 1 for the fuzzy areas.
+
+## Common Failure Modes
+
+| Symptom                                    | Root Cause                             | Fix                                                         |
+| ------------------------------------------ | -------------------------------------- | ----------------------------------------------------------- |
+| "Improve performance" as a consequence     | Vague intent                           | Ask: "improve which metric, by how much, measured how?"     |
+| Only one option listed                     | Decision already made, ADR is post-hoc | Ask: "what did you reject and why?" — capture the reasoning |
+| Context reads like a solution pitch        | Skipped problem framing                | Rewrite context as the problem, move solution to Decision   |
+| Consequences are all positive              | Cherry-picking                         | Ask: "what gets harder? what's the maintenance cost?"       |
+| "We decided to use X" with no why          | Missing justification                  | Ask: "why X over Y?" — the 'over Y' forces comparison       |
+| Implementation Plan says "update the code" | Too abstract                           | Ask: "which files, which functions, what pattern?"          |
+| Verification says "it works"               | Not testable                           | Ask: "what command would you run to prove it works?"        |
+| No affected paths listed                   | Implementation Plan is hand-wavy       | Agent should scan the codebase and propose specific paths   |

package/skills/adr-skill/references/template-variants.md

@@ -0,0 +1,52 @@
+# Template Variants
+
+This skill ships two templates in `assets/templates/`.
+
+## Simple
+
+File: `assets/templates/adr-simple.md`
+
+Use this when:
+
+- The decision is straightforward (one clear winner, minimal tradeoffs)
+- You mainly need "why, what, consequences, how to implement"
+- Alternatives are few and can be dismissed in a sentence each
+- Speed matters more than exhaustive comparison
+
+Sections: Context and Problem Statement → Decision → Consequences → Implementation Plan → Verification → Alternatives Considered (optional) → More Information (optional).
+
+## MADR (Options-Heavy)
+
+File: `assets/templates/adr-madr.md`
+
+Use this when:
+
+- You have multiple real options and want to document structured tradeoffs
+- You need to capture decision drivers explicitly (what criteria mattered)
+- The decision is likely to be revisited and the comparison needs to survive
+- Stakeholders need to see the reasoning process, not just the outcome
+
+Sections: Context and Problem Statement → Decision Drivers (optional) → Considered Options → Decision Outcome → Consequences → Implementation Plan → Verification → Pros and Cons of the Options (optional) → More Information (optional).
+
+This template aligns with [MADR 4.0](https://adr.github.io/madr/) and extends it with agent-first sections.
+
+## Both Templates Share
+
+- **YAML front matter** for metadata (status, date, decision-makers, consulted, informed)
+- **Implementation Plan** — affected paths, dependencies, patterns to follow/avoid, configuration, migration steps. This is what makes the ADR an executable spec for agents.
+- **Verification as checkboxes** — testable criteria an agent can validate after implementation
+- **Agent-first framing**: placeholder text prompts you to be specific, measurable, and self-contained
+- **"More Information" section** for cross-links, follow-ups, and revisit triggers
+- **"Neutral, because..."** as a third argument category alongside Good and Bad
+
+## Choosing Between Them
+
+| Signal                   | Use Simple      | Use MADR     |
+| ------------------------ | --------------- | ------------ |
+| Number of real options   | 1–2             | 3+           |
+| Team size affected       | Small / solo    | Cross-team   |
+| Reversibility            | Easily reversed | Hard to undo |
+| Expected lifetime        | Months          | Years        |
+| Needs stakeholder review | No              | Yes          |
+
+When in doubt, start with Simple. You can always expand to MADR if the discussion reveals more complexity.

package/skills/adr-skill/scripts/bootstrap_adr.js

@@ -0,0 +1,259 @@
+#!/usr/bin/env node
+/**
+ * Bootstrap ADRs in a repo:
+ * - create ADR directory
+ * - create adr/README.md (index) using a template
+ * - create first ADR: "Adopt architecture decision records"
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+function die(msg) {
+  process.stderr.write(`${msg}\n`);
+  process.exit(1);
+}
+
+function parseArgs(argv) {
+  const out = {
+    repoRoot: '.',
+    dir: 'adr',
+    forceIndex: false,
+    indexFile: null,
+    firstTitle: 'Adopt architecture decision records',
+    firstStatus: 'accepted',
+    deciders: '',
+    technicalStory: '',
+    strategy: 'date',
+    json: false,
+  };
+
+  for (let i = 2; i < argv.length; i++) {
+    const a = argv[i];
+    const next = () => {
+      if (i + 1 >= argv.length) die(`Missing value for ${a}`);
+      return argv[++i];
+    };
+
+    if (a === '--repo-root') out.repoRoot = next();
+    else if (a === '--dir') out.dir = next();
+    else if (a === '--force-index') out.forceIndex = true;
+    else if (a === '--index-file') out.indexFile = next();
+    else if (a === '--first-title') out.firstTitle = next();
+    else if (a === '--first-status') out.firstStatus = next();
+    else if (a === '--deciders') out.deciders = next();
+    else if (a === '--technical-story') out.technicalStory = next();
+    else if (a === '--strategy') out.strategy = next();
+    else if (a === '--json') out.json = true;
+    else if (a === '--help' || a === '-h') {
+      process.stdout.write(
+        [
+          'Usage: node bootstrap_adr.js [options]',
+          '',
+          'Options:',
+          '  --repo-root <path>     Repo root (default: .)',
+          '  --dir <path>           ADR directory (default: adr)',
+          '  --index-file <path>    Override index file path (relative to repo root unless absolute)',
+          '  --force-index          Overwrite index file if it exists',
+          '  --first-title <text>   Title for initial ADR',
+          '  --first-status <text>  Status for initial ADR (default: accepted)',
+          '  --strategy date|slug|auto  Filename strategy for initial ADR (default: date)',
+          '  --json                 Output machine-readable JSON (default: off)',
+          '',
+        ].join('\n'),
+      );
+      process.exit(0);
+    } else {
+      die(`Unknown arg: ${a}`);
+    }
+  }
+
+  if (!['auto', 'date', 'slug'].includes(out.strategy)) die(`Invalid --strategy: ${out.strategy}`);
+  return out;
+}
+
+function loadReadmeTemplate() {
+  const skillRoot = path.resolve(__dirname, '..');
+  const templatePath = path.join(skillRoot, 'assets', 'templates', 'adr-readme.md');
+  if (!fs.existsSync(templatePath)) die(`README template not found: ${templatePath}`);
+  return fs.readFileSync(templatePath, 'utf8');
+}
+
+function writeIndex(indexFile, adrDirName, { force }) {
+  if (fs.existsSync(indexFile) && !force) return;
+  const content = loadReadmeTemplate().replaceAll('{ADR_DIR}', adrDirName);
+  fs.mkdirSync(path.dirname(indexFile), { recursive: true });
+  fs.writeFileSync(indexFile, `${content.trimEnd()}\n`, 'utf8');
+}
+
+function slugify(text) {
+  const t = String(text || '')
+    .trim()
+    .toLowerCase();
+  const noQuotes = t.replace(/['"`]/g, '');
+  const dashed = noQuotes.replace(/[^a-z0-9]+/g, '-').replace(/-{2,}/g, '-');
+  const trimmed = dashed.replace(/^-+/, '').replace(/-+$/, '');
+  return trimmed || 'decision';
+}
+
+function toPosix(p) {
+  return p.split(path.sep).join('/');
+}
+
+function generateFirstAdr({ title, status, date, deciders, adrDir }) {
+  const deciderLine = deciders
+    ? String(deciders)
+        .split(',')
+        .map((s) => s.trim())
+        .filter(Boolean)
+        .join(', ')
+    : '';
+
+  return `---
+status: ${status}
+date: ${date}
+decision-makers: ${deciderLine}
+---
+
+# ${title}
+
+## Context and Problem Statement
+
+Architecture decisions in this project are made implicitly — through code, conversations, and tribal knowledge. When a new contributor (human or AI agent) joins the codebase, there is no record of *why* things are built the way they are. This makes it hard to:
+
+- Understand whether a pattern is intentional or accidental
+- Know if a past decision still applies or has been superseded
+- Avoid relitigating decisions that were already carefully considered
+
+We need a lightweight, version-controlled way to capture decisions where the code lives.
+
+## Decision
+
+Adopt Architecture Decision Records (ADRs) using the MADR 4.0 format, stored in \`${adrDir}/\`.
+
+Conventions:
+- One ADR per file, named \`YYYY-MM-DD-title-with-dashes.md\`
+- New ADRs start as \`proposed\`, move to \`accepted\` or \`rejected\`
+- Superseded ADRs link to their replacement
+- ADRs are written to be self-contained — a coding agent should be able to read one and implement the decision without further context
+
+## Consequences
+
+* Good, because decisions are discoverable and version-controlled alongside the code
+* Good, because new contributors (human or agent) can understand the "why" behind architecture choices
+* Good, because the team builds a shared decision log that prevents relitigating settled questions
+* Bad, because writing ADRs takes time — though a good ADR saves more time than it costs
+* Neutral, because ADRs require periodic review to mark outdated decisions as deprecated or superseded
+
+## Alternatives Considered
+
+* No formal records: Continue making decisions in conversations and code comments. Rejected because context is lost and decisions get relitigated.
+* Wiki or Notion pages: Capture decisions outside the repo. Rejected because they drift out of sync with the code and are not version-controlled.
+* Lightweight RFCs: More heavyweight process with formal review cycles. Rejected as overkill for most decisions — ADRs can scale up to RFC-level detail when needed.
+`;
+}
+
+function updateIndexFile(indexFile, { relLink, title, status, date }) {
+  if (!fs.existsSync(indexFile)) return;
+  const content = fs.readFileSync(indexFile, 'utf8');
+  if (content.includes(relLink)) return;
+
+  const entryLine = `- [${title}](${relLink}) (${status}, ${date})`;
+
+  // Append after "## ADRs" heading if found, otherwise append at end
+  const normalized = content.replace(/\r\n/g, '\n');
+  const lines = normalized.split('\n');
+  const headingIdx = lines.findIndex((l) => /^##\s+ADRs\s*$/i.test(l));
+
+  if (headingIdx !== -1) {
+    // Insert after the heading (and any blank line after it)
+    let insertAt = headingIdx + 1;
+    while (insertAt < lines.length && lines[insertAt].trim() === '') insertAt++;
+    lines.splice(insertAt, 0, entryLine);
+  } else {
+    lines.push(entryLine);
+  }
+
+  fs.writeFileSync(indexFile, lines.join('\n'), 'utf8');
+}
+
+function main() {
+  const args = parseArgs(process.argv);
+
+  const repoRoot = path.resolve(process.cwd(), args.repoRoot);
+  if (!fs.existsSync(repoRoot)) die(`Repo root does not exist: ${repoRoot}`);
+
+  const adrDir = path.resolve(repoRoot, args.dir);
+  fs.mkdirSync(adrDir, { recursive: true });
+
+  const indexFile = args.indexFile
+    ? path.isAbsolute(args.indexFile)
+      ? args.indexFile
+      : path.resolve(repoRoot, args.indexFile)
+    : path.join(adrDir, 'README.md');
+
+  const indexExistedBefore = fs.existsSync(indexFile);
+  writeIndex(indexFile, args.dir, { force: args.forceIndex });
+  const indexWritten = fs.existsSync(indexFile) && (!indexExistedBefore || args.forceIndex);
+
+  // Create the first ADR as a filled-out decision (not a blank template).
+  const relIndex = path.isAbsolute(indexFile) ? path.relative(repoRoot, indexFile) : indexFile;
+  const today = new Date().toISOString().slice(0, 10);
+
+  const firstAdrContent = generateFirstAdr({
+    title: args.firstTitle,
+    status: args.firstStatus,
+    date: today,
+    deciders: args.deciders,
+    adrDir: args.dir,
+  });
+
+  // Determine filename using same logic as new_adr.js
+  const strategy = args.strategy === 'auto' ? 'date' : args.strategy;
+  let firstAdrFilename;
+  if (strategy === 'date') {
+    firstAdrFilename = `${today}-${slugify(args.firstTitle)}.md`;
+  } else {
+    firstAdrFilename = `${slugify(args.firstTitle)}.md`;
+  }
+  const firstAdrPath = path.join(adrDir, firstAdrFilename);
+  fs.writeFileSync(firstAdrPath, `${firstAdrContent.trimEnd()}\n`, 'utf8');
+
+  // Update index
+  const relLink = toPosix(path.relative(path.dirname(indexFile), firstAdrPath));
+  updateIndexFile(indexFile, {
+    relLink,
+    title: args.firstTitle,
+    status: args.firstStatus,
+    date: today,
+  });
+
+  if (args.json) {
+    const payload = {
+      repoRoot,
+      adrDir,
+      adrDirRelPath: toPosix(path.relative(repoRoot, adrDir)),
+      indexPath: indexFile,
+      indexRelPath: toPosix(relIndex),
+      indexExistedBefore,
+      indexWritten,
+      firstAdr: {
+        createdAdrPath: firstAdrPath,
+        createdAdrRelPath: toPosix(path.relative(repoRoot, firstAdrPath)),
+        title: args.firstTitle,
+        status: args.firstStatus,
+        strategy,
+        date: today,
+      },
+      date: today,
+    };
+    process.stdout.write(`${JSON.stringify(payload)}\n`);
+    return;
+  }
+
+  process.stdout.write(`${firstAdrPath}\n`);
+  process.stdout.write(`Bootstrapped ADRs at ${adrDir} (${today})\n`);
+  process.stdout.write(`Index: ${indexFile}\n`);
+}
+
+main();