@vpxa/aikit 0.1.1

package/scaffold/general/skills/adr-skill/assets/templates/adr-simple.md

@@ -0,0 +1,46 @@
+---
+status: '{proposed | accepted | rejected | deprecated | superseded by [title](YYYY-MM-DD-title.md)}'
+date: { YYYY-MM-DD }
+decision-makers: '{list everyone who owns the decision}'
+---
+
+# {short title, representative of solved problem and found solution}
+
+## Context and Problem Statement
+
+{Why does this decision need to happen now? What constraints exist? Include enough background that someone (or an agent) reading this for the first time can understand without follow-up questions.}
+
+## Decision
+
+{What are we choosing to do? Be specific — include scope and non-goals.}
+
+## Consequences
+
+- Good, because {positive consequence}
+- Bad, because {negative consequence}
+- …
+
+## Implementation Plan
+
+- **Affected paths**: {files and directories that change}
+- **Dependencies**: {packages to add/remove/update}
+- **Patterns to follow**: {existing code patterns to match}
+- **Patterns to avoid**: {what NOT to do}
+
+### Verification
+
+- [ ] {how to confirm the decision was implemented correctly}
+- [ ] {another verification criterion}
+
+<!-- Optional — remove if not needed -->
+
+## Alternatives Considered
+
+- {Alternative 1}: {Why it was rejected, in one or two sentences.}
+- {Alternative 2}: {Why it was rejected.}
+
+<!-- Optional — remove if not needed -->
+
+## More Information
+
+{Related ADRs, PRs, issues, docs, or conditions that would trigger revisiting this decision.}

package/scaffold/general/skills/adr-skill/references/adr-conventions.md

@@ -0,0 +1,95 @@
+# ADR Conventions (Reference)
+
+## Directory
+
+If the repo already has an ADR directory, keep it.
+
+If the repo has no ADR directory, choose based on project size:
+
+- **`docs/decisions/`** — MADR default, recommended for projects with existing `docs/` structure.
+- **`adr/`** — simpler alternative for smaller repos.
+
+Detection order (used by scripts): `contributing/decisions/`, `docs/decisions/`, `adr/`, `docs/adr/`, `docs/adrs/`, `decisions/`.
+
+## Filename Conventions
+
+Pattern: `YYYY-MM-DD-title-with-dashes.md`
+
+- `YYYY-MM-DD` is the ADR creation date (matches the `date` frontmatter field).
+- Title uses lowercase, dashes, present-tense imperative verb phrase.
+- Examples: `2025-06-15-choose-database.md`, `2025-07-01-adopt-adrs.md`
+- Multiple ADRs on the same date are fine — the slug suffix disambiguates them.
+
+If a repo already uses slug-only filenames (no date prefix), follow that convention.
+
+## Minimal Sections
+
+At minimum, every ADR must clearly include:
+
+1. **Context**: why the decision exists now, what constraints/drivers apply.
+2. **Decision**: what is chosen.
+3. **Consequences**: what becomes easier/harder, risks, costs, follow-ups.
+
+For agent-first ADRs, also ensure:
+
+- Constraints are explicit and measurable
+- Non-goals are stated
+- Follow-up tasks are identified
+
+## Status Values
+
+Track status in YAML front matter:
+
+```yaml
+---
+status: proposed
+date: 2025-06-15
+decision-makers: Alice, Bob
+---
+```
+
+Common statuses:
+
+| Status                        | Meaning                                                       |
+| ----------------------------- | ------------------------------------------------------------- |
+| `proposed`                    | Under discussion, not yet decided                             |
+| `accepted`                    | Decision is active and should be followed                     |
+| `rejected`                    | Considered but explicitly not adopted                         |
+| `deprecated`                  | Was accepted but no longer applies — explain replacement path |
+| `superseded by [title](link)` | Replaced by a newer ADR — always link both ways               |
+
+## YAML Front Matter Fields
+
+| Field             | Required | Description                                              |
+| ----------------- | -------- | -------------------------------------------------------- |
+| `status`          | Yes      | Current lifecycle state                                  |
+| `date`            | Yes      | Date of last status change (YYYY-MM-DD)                  |
+| `decision-makers` | Yes      | People who own the decision                              |
+| `consulted`       | No       | Subject-matter experts consulted (two-way communication) |
+| `informed`        | No       | Stakeholders kept up-to-date (one-way communication)     |
+
+The `consulted` and `informed` fields follow the RACI model and are useful for audit trails in larger teams.
+
+## Mutability
+
+- Prefer appending new information with a date stamp over rewriting existing content.
+- If a decision is replaced, create a new ADR and explicitly supersede the old one.
+- Status changes and after-action notes are fine to edit in-place.
+
+## Categories (Large Projects)
+
+For repos accumulating many ADRs, use subdirectories:
+
+```
+contributing/decisions/   # or docs/decisions/
+  backend/
+    2025-06-15-use-postgres.md
+  frontend/
+    2025-06-20-use-react.md
+  infrastructure/
+    2025-07-01-use-terraform.md
+```
+
+Date prefixes are local to each category. Choose a categorization scheme early (by architectural layer, by domain, by team) and document it in the index.
+
+Alternative: use tags or a flat structure with a searchable index. Subdirectories are simpler and work with all tools.

package/scaffold/general/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/scaffold/general/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/scaffold/general/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.