ai-engineering-kit 0.1.0

package/template/skills/core-workflow/review/SKILL.md

@@ -0,0 +1,127 @@
+---
+name: review
+description: Two-axis review of the diff between HEAD and a user-supplied fixed point — Standards (does the code follow the active guidelines under docs/foundations/ plus CLAUDE.md?) and Spec (does the code faithfully implement the originating PRD/plan in ai/prds/ and ai/plans/?). Runs both axes as parallel sub-agents and writes the aggregated report to a new file in ai/reviews/. Use when the user wants to review a branch, work-in-progress changes, or asks to "review since X".
+---
+
+# Review
+
+Two-axis review of the diff between `HEAD` and a fixed point the user supplies:
+
+- **Standards** — does the code conform to this repo's documented standards?
+- **Spec** — does the code faithfully implement the originating PRD / plan?
+
+Both axes run as **parallel sub-agents** so they don't pollute each other's context. Findings are aggregated into a new file in `ai/reviews/`.
+
+This project does not use GitHub issues for specs — PRDs live in `ai/prds/`, plans in `ai/plans/`, brainstorms in `ai/brainstorms/`. The Spec axis reads those files, not an issue tracker.
+
+## Process
+
+### 1. Pin the fixed point
+
+Ask: "Review against what — a branch, a commit SHA, or a tag?" Do not proceed without an answer. Do not assume `main`.
+
+Capture once:
+
+- Diff: `git diff <fixed-point>...HEAD` (three-dot, against merge-base)
+- Commits: `git log <fixed-point>..HEAD --oneline`
+- Current branch: `git rev-parse --abbrev-ref HEAD`
+
+### 2. Identify the spec sources
+
+Match the current branch slug against filenames in `ai/prds/` and `ai/plans/`:
+
+- Strip prefixes like `feat/`, `fix/`, `refactor/`, `chore/` from the branch name.
+- Look for any file in `ai/prds/` or `ai/plans/` whose name contains the slug.
+- If nothing matches there, check `ai/brainstorms/`.
+
+If multiple files match (typical — a PRD plus its plan), use **all** of them. If nothing matches, ask the user where the spec is. If they confirm there isn't one, skip the Spec sub-agent and note "no spec available" in the report.
+
+### 3. Identify the standards sources
+
+The Standards sub-agent always reads:
+
+- `CLAUDE.md`
+- `docs/foundations/project-guidelines.md`
+- `docs/foundations/testing-principles.md`
+
+And conditionally, based on what the diff touches:
+
+- `docs/foundations/technical-decisions.md` — when the change picks a new technology, pattern, or architectural shape, or contradicts an existing decision.
+- Any other reference docs the project ships under `docs/` (e.g. domain rules, audit-event conventions, security or compliance policies, vendor references) that the diff touches.
+
+Do **not** re-check what tooling already enforces (`pnpm lint`, `pnpm typecheck`, `pnpm lint:deps`).
+
+### 4. Spawn both sub-agents in parallel
+
+Send a single message with two `Agent` tool calls (`subagent_type=general-purpose`).
+
+**Standards sub-agent prompt** — include the diff command, the commit list, the list of standards-source files, and this brief:
+
+> Read the standards docs listed. Then read the diff. For every place the diff violates a documented standard, output one entry in this format:
+>
+> ```
+> ### `<relative/path>:<line>`
+>
+> ```<lang>
+> <2–3 lines of the offending code>
+> ```
+>
+> <one paragraph: cite the standard (doc + rule) and say what to change>
+> ```
+>
+> Prefix judgement calls with `[judgement]`. Skip anything tooling enforces (lint, typecheck, dep-cruiser). Under 500 words total.
+
+**Spec sub-agent prompt** — include the diff command, the commit list, the paths and contents of the matched PRD/plan/brainstorm files, and this brief:
+
+> Read the spec(s) listed. Then read the diff. Use the same `### \`<file>:<line>\`` entry format. Group findings into three buckets, each as its own H3 section:
+>
+> - **Missing** — requirements the spec asked for that are missing or partial
+> - **Scope creep** — behaviour in the diff that wasn't asked for
+> - **Wrong** — requirements that look implemented but where the implementation doesn't match the spec
+>
+> Quote the relevant spec line (with the spec file path) for each finding. Under 500 words total.
+
+If step 2 found no spec, skip this sub-agent.
+
+### 5. Write the review file
+
+Create `ai/reviews/` if it doesn't exist. Write the report to `ai/reviews/<YYYY-MM-DD>-<branch-slug>.md` using the template below. Do **not** overwrite an existing file — if one with the same name already exists, append `-2`, `-3`, etc.
+
+<review-template>
+# Review: `<branch>` against `<fixed-point>`
+
+> Date: <YYYY-MM-DD>
+> Branch: `<branch>`
+> Base: `<fixed-point>`
+> Spec sources: <list of matched ai/prds + ai/plans paths, or "none">
+> Standards sources: CLAUDE.md, docs/foundations/project-guidelines.md, docs/foundations/testing-principles.md<, plus any conditional docs>
+
+<!-- For coding agents: address each entry by editing the referenced file:line, then delete the entry. -->
+
+## Standards
+
+<standards sub-agent output verbatim, or "No findings.">
+
+## Spec
+
+<spec sub-agent output verbatim, or "No spec source matched the branch — Spec axis skipped.">
+
+## Summary
+
+- Standards: <N> findings (<M> hard, <K> judgement)
+- Spec: <N> findings (missing: <m>, scope creep: <s>, wrong: <w>)
+- Worst single issue: <one-line description, or "none">
+</review-template>
+
+### 6. Report inline
+
+Print the path of the new review file and the **Summary** block to the user. Do not paste the full report back into the conversation — it lives in the file so an agent can address findings later by editing each `file:line` and deleting the entry.
+
+## Why two axes
+
+A change can pass one axis and fail the other:
+
+- Code that follows every standard but implements the wrong thing → **Standards pass, Spec fail.**
+- Code that does exactly what the spec asked for but breaks project conventions → **Spec pass, Standards fail.**
+
+Reporting them separately stops one axis from masking the other.

package/template/skills/core-workflow/setup-foundations/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: setup-foundations
+description: Define a new project's foundation docs — product vision, seed technical decisions, code guidelines, and testing principles — through a guided interview that reads the kickoff brainstorm. Use right after kickoff and before the first PRD, or when a project's docs/foundations/ are still stubs.
+---
+
+# Setup Foundations
+
+Run once near the start of a project — after `kickoff` and before `write-prd` —
+to turn the empty `docs/foundations/` stubs into real, project-specific docs.
+Works for any stack; never assume TypeScript/Node.
+
+## Read first
+
+1. The most recent brainstorm in `ai/brainstorms/` — the MVP exploration and the
+   primary context, since this skill runs before any PRD exists.
+2. Any PRD in `ai/prds/` — usually none yet on the first run; present only if the
+   skill is re-run later in the project's life.
+3. The current stub docs in `docs/foundations/` — fill them in place; keep useful
+   structure rather than clobbering it.
+4. The existing source tree, when the workspace was added to a project that
+   already has code — explore it for stack, conventions, and structure so the
+   docs describe the real codebase, not a greenfield ideal.
+
+## Produce, in order
+
+Interview one question at a time, recommending an answer for each. Each doc builds
+on the previous one. Present each finished doc to the user for confirmation before
+moving to the next. Where a question can be answered from the brainstorm, answer it
+instead of asking.
+
+### 1. docs/foundations/product-vision.md
+
+Confirm and fill: what we're building, users, core surfaces, constraints, out of
+scope. Distil from the kickoff brainstorm; ask only where it is silent or ambiguous.
+
+### 2. docs/foundations/technical-decisions.md
+
+Interview on the stack and the first architectural choices: language/runtime,
+framework, datastore and ORM, testing tools, deployment model, and any major
+patterns. Capture each as a dated ADR entry (Context / Decision / Consequences)
+using the format already in the file, replacing the example placeholder entry.
+
+### 3. docs/foundations/project-guidelines.md
+
+Draft from the decisions above: project structure, layering and dependency rules,
+naming conventions, error handling, interfaces vs types, and the non-negotiable
+rules. Keep it lean — a greenfield project's guidelines start small and grow.
+
+### 4. docs/foundations/testing-principles.md
+
+Draft a test strategy by layer, what to mock versus exercise for real, test
+structure and naming, and the non-negotiable testing rules — consistent with the
+test tooling chosen in step 2.
+
+## When done
+
+Confirm the four docs read correctly together. The project is then ready for
+`write-prd`.

package/template/skills/core-workflow/verify-completion/SKILL.md

@@ -0,0 +1,20 @@
+---
+name: verify-completion
+description: Validate that a task is truly complete before reporting it done. Use when about to claim a task, feature, or fix is complete — run pnpm verify, confirm interaction tests cover new service methods, and confirm no TODOs remain in changed files.
+---
+
+# Verify Completion
+
+Run this before declaring any task done. Never claim completion without passing all steps.
+
+## Checklist
+
+- [ ] Run `pnpm verify` (lint + typecheck + deps + tests) — must pass clean
+- [ ] Every new or modified service method has at least one interaction test
+- [ ] No `TODO`, `FIXME`, or `@ts-ignore` introduced in changed files
+- [ ] Architecture boundaries respected — `pnpm lint:deps` passes
+- [ ] Original task requirements are fully met (re-read the request before confirming)
+
+## On failure
+
+Fix the issue before reporting done. Do not skip steps or mark items complete without running them.

package/template/skills/core-workflow/write-prd/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: write-prd
+description: Create a PRD through user interview, codebase exploration, and module design, then save it as a local markdown file in ai/prds/. Use when user wants to write a PRD, create a product requirements document, or plan a new feature.
+---
+
+This skill will be invoked when the user wants to create a PRD. You may skip steps if you don't consider them necessary.
+
+1. Ask the user for a long, detailed description of the problem they want to solve and any potential ideas for solutions.
+
+2. Explore the repo to verify their assertions and understand the current state of the codebase.
+
+3. Interview the user relentlessly about every aspect of this plan until you reach a shared understanding. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one.
+
+4. Sketch out the major modules you will need to build or modify to complete the implementation. Actively look for opportunities to extract deep modules that can be tested in isolation.
+
+A deep module (as opposed to a shallow module) is one which encapsulates a lot of functionality in a simple, testable interface which rarely changes.
+
+Check with the user that these modules match their expectations. Check with the user which modules they want tests written for.
+
+5. Once you have a complete understanding of the problem and solution, use the template below to write the PRD. Save it to `ai/prds/<YYYY-MM-DD>-<slug>.md`. To track externally, run `gh issue create` (or your tracker's equivalent) on the file after.
+
+<prd-template>
+
+## Problem Statement
+
+The problem that the user is facing, from the user's perspective.
+
+## Solution
+
+The solution to the problem, from the user's perspective.
+
+## User Stories
+
+A LONG, numbered list of user stories. Each user story should be in the format of:
+
+1. As an <actor>, I want a <feature>, so that <benefit>
+
+<user-story-example>
+1. As a mobile bank customer, I want to see balance on my accounts, so that I can make better informed decisions about my spending
+</user-story-example>
+
+This list of user stories should be extremely extensive and cover all aspects of the feature.
+
+## Implementation Decisions
+
+A list of implementation decisions that were made. This can include:
+
+- The modules that will be built/modified
+- The interfaces of those modules that will be modified
+- Technical clarifications from the developer
+- Architectural decisions
+- Schema changes
+- API contracts
+- Specific interactions
+
+Do NOT include specific file paths or code snippets. They may end up being outdated very quickly.
+
+## Testing Decisions
+
+A list of testing decisions that were made. Include:
+
+- A description of what makes a good test (only test external behavior, not implementation details)
+- Which modules will be tested
+- Prior art for the tests (i.e. similar types of tests in the codebase)
+
+## Out of Scope
+
+A description of the things that are out of scope for this PRD.
+
+## Further Notes
+
+Any further notes about the feature.
+
+</prd-template>

package/template/skills/core-workflow/write-skill/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: write-skill
+description: Create new agent skills with proper structure, progressive disclosure, and bundled resources. Use when user wants to create, write, or build a new skill.
+---
+
+# Writing Skills
+
+## Process
+
+1. **Gather requirements** - ask user about:
+   - What task/domain does the skill cover?
+   - What specific use cases should it handle?
+   - Does it need executable scripts or just instructions?
+   - Any reference materials to include?
+
+2. **Draft the skill** - create:
+   - SKILL.md with concise instructions
+   - Additional reference files if content exceeds 500 lines
+   - Utility scripts if deterministic operations needed
+
+3. **Review with user** - present draft and ask:
+   - Does this cover your use cases?
+   - Anything missing or unclear?
+   - Should any section be more/less detailed?
+
+## Skill Structure
+
+```
+skill-name/
+├── SKILL.md           # Main instructions (required)
+├── REFERENCE.md       # Detailed docs (if needed)
+├── EXAMPLES.md        # Usage examples (if needed)
+└── scripts/           # Utility scripts (if needed)
+    └── helper.js
+```
+
+## SKILL.md Template
+
+```md
+---
+name: skill-name
+description: Brief description of capability. Use when [specific triggers].
+---
+
+# Skill Name
+
+## Quick start
+
+[Minimal working example]
+
+## Workflows
+
+[Step-by-step processes with checklists for complex tasks]
+
+## Advanced features
+
+[Link to separate files: See [REFERENCE.md](REFERENCE.md)]
+```
+
+## Description Requirements
+
+The description is **the only thing your agent sees** when deciding which skill to load. It's surfaced in the system prompt alongside all other installed skills. Your agent reads these descriptions and picks the relevant skill based on the user's request.
+
+**Goal**: Give your agent just enough info to know:
+
+1. What capability this skill provides
+2. When/why to trigger it (specific keywords, contexts, file types)
+
+**Format**:
+
+- Max 1024 chars
+- Write in third person
+- First sentence: what it does
+- Second sentence: "Use when [specific triggers]"
+
+**Good example**:
+
+```
+Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when user mentions PDFs, forms, or document extraction.
+```
+
+**Bad example**:
+
+```
+Helps with documents.
+```
+
+The bad example gives your agent no way to distinguish this from other document skills.
+
+## When to Add Scripts
+
+Add utility scripts when:
+
+- Operation is deterministic (validation, formatting)
+- Same code would be generated repeatedly
+- Errors need explicit handling
+
+Scripts save tokens and improve reliability vs generated code.
+
+## When to Split Files
+
+Split into separate files when:
+
+- SKILL.md exceeds 100 lines
+- Content has distinct domains (finance vs sales schemas)
+- Advanced features are rarely needed
+
+## Review Checklist
+
+After drafting, verify:
+
+- [ ] Description includes triggers ("Use when...")
+- [ ] SKILL.md under 100 lines
+- [ ] No time-sensitive info
+- [ ] Consistent terminology
+- [ ] Concrete examples included
+- [ ] References one level deep