ai-engineering-kit 0.1.0

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "ai-engineering-kit",
+  "version": "0.1.0",
+  "description": "An opinionated, agent-agnostic AI-development kit — disciplined skills plus a structured workspace — installed and updated through one npx command.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Ebert Mota",
+  "homepage": "https://github.com/ebertmota/ai-engineering-kit#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ebertmota/ai-engineering-kit.git"
+  },
+  "keywords": [
+    "ai",
+    "agent",
+    "claude-code",
+    "codex",
+    "skills",
+    "scaffold",
+    "cli"
+  ],
+  "bin": {
+    "ai-engineering-kit": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "template",
+    "NOTICE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@clack/prompts": "^0.7.0"
+  },
+  "devDependencies": {
+    "@changesets/cli": "^2.27.0",
+    "@types/node": "^22.0.0",
+    "tsup": "^8.0.0",
+    "tsx": "^4.0.0",
+    "typescript": "^5.4.0",
+    "vitest": "^2.0.0"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsx src/cli.ts",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "verify": "pnpm typecheck && pnpm test",
+    "release": "pnpm verify && changeset publish"
+  }
+}

package/template/agents/claude-code.CLAUDE.md

@@ -0,0 +1,88 @@
+# {{PROJECT_NAME}} — Claude Code Instructions
+
+## Skills
+
+When a project skill in `ai/skills/` and a global skill share the same name or similar trigger, always prefer the project skill.
+
+## Starting a new project
+
+For a freshly scaffolded project, set up the foundations before building:
+
+1. `ai/skills/kickoff/SKILL.md` — brainstorm the MVP (writes to `ai/brainstorms/`).
+2. `ai/skills/setup-foundations/SKILL.md` — fill in `docs/foundations/` (vision, technical decisions, code & test guidelines).
+3. `ai/skills/write-prd/SKILL.md` — first PRD.
+4. `ai/skills/plan-feature/SKILL.md` → `ai/skills/implement/SKILL.md` — plan, then build.
+
+## When to read reference docs
+
+Read docs only when relevant — do not load all of them upfront.
+
+**Before implementing, refactoring, or fixing anything:** read `docs/foundations/project-guidelines.md`. It defines architecture, conventions, naming rules, and non-negotiable rules. Follow it strictly.
+
+**Before writing or modifying any test:** read `docs/foundations/testing-principles.md`. It defines which test type to use for each layer, what to mock, and what not to test.
+
+**Before introducing a new technology, pattern, or architectural shape:** read `docs/foundations/technical-decisions.md` for prior decisions and record the new one there.
+
+**Before planning a feature or writing a PRD/plan:** read `docs/foundations/product-vision.md` for product context, then `ai/prds/` and `ai/plans/` for in-flight work, and any relevant brainstorm in `ai/brainstorms/`.
+
+**When picking up in-flight work or the user mentions continuity:** read the relevant plan in `ai/plans/` — its checkboxes are the authoritative record of what is done and what is next.
+
+## Reference Docs
+
+Canonical (long-lived, under `docs/foundations/`):
+
+- `docs/foundations/project-guidelines.md` — architecture and development guidelines
+- `docs/foundations/testing-principles.md` — testing strategy by layer
+- `docs/foundations/technical-decisions.md` — running log of architecture/technology decisions
+- `docs/foundations/product-vision.md` — product vision and strategic context
+
+Other durable docs (start empty; promote knowledge here as it emerges):
+
+- `docs/system/` — how our own code works (per-flow specs, event/contract conventions)
+- `docs/references/` — how external systems we integrate with work (vendor APIs, protocols)
+- `docs/operations/` — what to do when something needs human action (runbooks)
+- `docs/debt/` — structured registries of deferred or known work
+
+Development artefacts (ephemeral, under `ai/`):
+
+- `ai/brainstorms/` — requirements and exploratory docs
+- `ai/prds/` — feature PRDs for tracked initiatives
+- `ai/plans/` — phased implementation plans for in-flight PRDs; status lives in their checkboxes
+- `ai/reviews/` — two-axis (Standards / Spec) review reports from the `review` skill
+- `ai/runbooks/` — operational notes used during implementation or maintenance
+- `ai/research/` — exploratory research notes
+- `ai/templates/` — reusable templates for generated artifacts
+
+## Skills
+
+Project workflows live in `ai/skills/`. Read only the matching `SKILL.md`, not every skill upfront:
+
+- `ai/skills/load-context/SKILL.md` — starting or resuming in-flight work, or when continuity matters
+- `ai/skills/kickoff/SKILL.md` — stress-test or clarify a plan/design through focused questioning
+- `ai/skills/setup-foundations/SKILL.md` — fill in `docs/foundations/` (vision, technical decisions, code & test guidelines) from the kickoff brainstorm; run before the first PRD
+- `ai/skills/write-prd/SKILL.md` — turn a feature idea into a PRD saved in `ai/prds/`
+- `ai/skills/plan-feature/SKILL.md` — turn a PRD into a phased implementation plan
+- `ai/skills/implement/SKILL.md` — build features or fix bugs with TDD / red-green-refactor
+- `ai/skills/investigate-bug/SKILL.md` — triage a bug and produce a root-cause / TDD fix plan in `ai/bugs/`
+- `ai/skills/explore-design/SKILL.md` — compare API/module interface designs
+- `ai/skills/plan-refactor/SKILL.md` — plan a refactor in small safe steps
+- `ai/skills/audit-architecture/SKILL.md` — look for architectural improvements and testability gaps
+- `ai/skills/review/SKILL.md` — two-axis (Standards / Spec) review of a branch
+- `ai/skills/verify-completion/SKILL.md` — use before saying work is complete
+- `ai/skills/write-skill/SKILL.md` — create or update a project skill
+
+## Commands
+
+```bash
+# edit for your project
+pnpm lint
+pnpm typecheck
+pnpm test
+pnpm test:unit
+pnpm test:integration
+pnpm verify      # lint + typecheck + test
+```
+
+## Commits
+
+Never commit on behalf of the user unless explicitly asked.

package/template/agents/codex.AGENTS.md

@@ -0,0 +1,82 @@
+# {{PROJECT_NAME}} — Codex Instructions
+
+## Primary Rules
+
+This file is the entry point. Keep detailed guidance in canonical docs and read those docs only when relevant.
+
+Non-negotiable:
+
+- Before implementing, refactoring, or fixing code, read `docs/foundations/project-guidelines.md` and follow it.
+- Before writing or modifying tests, read `docs/foundations/testing-principles.md` and follow it.
+- Before introducing a new technology, pattern, or architectural shape, read `docs/foundations/technical-decisions.md` and record the new decision there.
+- Before planning a feature, PRD, or implementation approach, read `docs/foundations/product-vision.md` for product context.
+- Before claiming a task is complete, use `ai/skills/verify-completion/SKILL.md` and run the relevant verification command. Prefer `pnpm verify` when practical.
+- Never commit unless the user explicitly asks.
+
+## Starting a new project
+
+For a freshly scaffolded project, set up the foundations first:
+
+1. `ai/skills/kickoff/SKILL.md` — brainstorm the MVP (writes to `ai/brainstorms/`).
+2. `ai/skills/setup-foundations/SKILL.md` — fill in `docs/foundations/` (vision, technical decisions, code & test guidelines).
+3. `ai/skills/write-prd/SKILL.md` — first PRD, then `plan-feature` and `implement`.
+
+## Project Workflows
+
+Project workflows live in `ai/skills/`. If a project workflow and a global Codex skill overlap, prefer the project workflow.
+
+Read only the matching `SKILL.md`, not every skill upfront:
+
+- `ai/skills/load-context/SKILL.md` — starting or resuming in-flight work, or when continuity matters.
+- `ai/skills/kickoff/SKILL.md` — stress-test or clarify a plan/design through focused questioning.
+- `ai/skills/setup-foundations/SKILL.md` — fill in `docs/foundations/` from the kickoff brainstorm; run before the first PRD.
+- `ai/skills/write-prd/SKILL.md` — turn a feature idea into a PRD saved in `ai/prds/`.
+- `ai/skills/plan-feature/SKILL.md` — turn a PRD into a phased implementation plan.
+- `ai/skills/implement/SKILL.md` — build features or fix bugs with TDD/red-green-refactor.
+- `ai/skills/investigate-bug/SKILL.md` — triage a bug and produce a root-cause/TDD fix plan in `ai/bugs/`.
+- `ai/skills/explore-design/SKILL.md` — compare API/module interface designs.
+- `ai/skills/plan-refactor/SKILL.md` — plan a refactor in small safe steps.
+- `ai/skills/audit-architecture/SKILL.md` — look for architectural improvements and testability gaps.
+- `ai/skills/review/SKILL.md` — two-axis (Standards / Spec) review of a branch.
+- `ai/skills/verify-completion/SKILL.md` — use before saying work is complete.
+- `ai/skills/write-skill/SKILL.md` — create or update a project skill.
+
+## Reference Docs
+
+Read these only when the task touches the area:
+
+- `docs/foundations/project-guidelines.md` — architecture, naming, layering, error handling, and development rules.
+- `docs/foundations/testing-principles.md` — what to test by layer, what to mock, and test structure.
+- `docs/foundations/technical-decisions.md` — running log of architecture/technology decisions.
+- `docs/foundations/product-vision.md` — product context.
+
+Other durable docs (start empty; promote knowledge here as it emerges):
+
+- `docs/system/` — how our own code works (per-flow specs, event/contract conventions).
+- `docs/references/` — how external systems we integrate with work (vendor APIs, protocols).
+- `docs/operations/` — what to do when something needs human action (runbooks).
+- `docs/debt/` — structured registries of deferred or known work.
+
+Development context under `ai/` (ephemeral — durable knowledge belongs in `docs/`):
+
+- `ai/brainstorms/` — exploratory notes.
+- `ai/prds/` — product requirements.
+- `ai/plans/` — implementation plans; status lives in their checkboxes.
+- `ai/reviews/` — review reports.
+- `ai/runbooks/` — operational notes.
+- `ai/research/` — research notes.
+- `ai/templates/` — reusable templates.
+
+When picking up existing work, read the matching plan in `ai/plans/` — its checkboxes are the authoritative record of what is done and what is next — plus the originating PRD in `ai/prds/`.
+
+## Commands
+
+```bash
+# edit for your project
+pnpm lint
+pnpm typecheck
+pnpm test
+pnpm test:unit
+pnpm test:integration
+pnpm verify       # lint + typecheck + test
+```

package/template/docs/foundations/product-vision.md

@@ -0,0 +1,21 @@
+# Product Vision
+
+## What we're building
+
+_one paragraph: the product in plain language_
+
+## Users
+
+_who uses this and why_
+
+## Core surfaces
+
+_the main things users do_
+
+## Constraints
+
+_non-negotiables: regulatory, technical, business_
+
+## Out of scope
+
+_what we explicitly do not do_

package/template/docs/foundations/project-guidelines.md

@@ -0,0 +1,19 @@
+# Project Guidelines
+
+## Stack
+_languages, frameworks, datastore, key libraries_
+
+## Project Structure
+_top-level layout and what lives where_
+
+## Architecture & Layers
+_layers and how dependencies flow_
+
+## Naming Conventions
+_files, types, classes_
+
+## Error Handling
+_how failures are signalled and mapped_
+
+## Non-Negotiable Rules
+_the hard rules for this codebase_

package/template/docs/foundations/technical-decisions.md

@@ -0,0 +1,50 @@
+# Technical Decisions
+
+A running log of architecture- and technology-level decisions for this project.
+One entry per decision, newest first. Capture the *why*, not just the *what* — the
+reasoning is what future readers (human or agent) need when they hit the same fork.
+
+This is canonical, long-lived documentation. It outlives any single PRD, plan, or
+feature, which is why it lives under `docs/foundations/` and not in the ephemeral
+`ai/` workspace.
+
+## When to add an entry
+
+Add a decision when the change:
+
+- picks a new technology, library, framework, or external service,
+- introduces a new pattern or architectural shape (a layer, a boundary, a
+  cross-cutting convention), or
+- contradicts or supersedes an earlier decision recorded here.
+
+Routine code that follows existing conventions does **not** need an entry — those
+conventions belong in `project-guidelines.md`.
+
+## Format
+
+Each entry uses this shape:
+
+```
+## <YYYY-MM-DD> — <short decision title>
+
+**Status:** accepted | superseded by <link> | reversed
+
+**Context.** What forced a choice? What constraints applied?
+
+**Decision.** What we chose, stated plainly.
+
+**Consequences.** What this makes easier, what it makes harder, and what we
+explicitly gave up.
+```
+
+---
+
+## <YYYY-MM-DD> — Example: replace the placeholder, then delete this entry
+
+**Status:** accepted
+
+**Context.** Describe the problem and the constraints that ruled options in or out.
+
+**Decision.** State the choice in one or two sentences.
+
+**Consequences.** Note the trade-offs you accepted and the doors you closed.

package/template/docs/foundations/testing-principles.md

@@ -0,0 +1,13 @@
+# Testing Principles
+
+## Strategy by layer
+_which test type per layer, and what each covers_
+
+## What to mock
+_what is mocked vs. exercised for real, by layer_
+
+## Test structure
+_naming, file layout, fixtures/factories_
+
+## Non-Negotiable Rules
+_the hard testing rules for this codebase_

package/template/skills/core-workflow/audit-architecture/REFERENCE.md

@@ -0,0 +1,78 @@
+# Reference
+
+## Dependency Categories
+
+When assessing a candidate for deepening, classify its dependencies:
+
+### 1. In-process
+
+Pure computation, in-memory state, no I/O. Always deepenable — just merge the modules and test directly.
+
+### 2. Local-substitutable
+
+Dependencies that have local test stand-ins (e.g., PGLite for Postgres, in-memory filesystem). Deepenable if the test substitute exists. The deepened module is tested with the local stand-in running in the test suite.
+
+### 3. Remote but owned (Ports & Adapters)
+
+Your own services across a network boundary (microservices, internal APIs). Define a port (interface) at the module boundary. The deep module owns the logic; the transport is injected. Tests use an in-memory adapter. Production uses the real HTTP/gRPC/queue adapter.
+
+Recommendation shape: "Define a shared interface (port), implement an HTTP adapter for production and an in-memory adapter for testing, so the logic can be tested as one deep module even though it's deployed across a network boundary."
+
+### 4. True external (Mock)
+
+Third-party services (Stripe, Twilio, etc.) you don't control. Mock at the boundary. The deepened module takes the external dependency as an injected port, and tests provide a mock implementation.
+
+## Testing Strategy
+
+The core principle: **replace, don't layer.**
+
+- Old unit tests on shallow modules are waste once boundary tests exist — delete them
+- Write new tests at the deepened module's interface boundary
+- Tests assert on observable outcomes through the public interface, not internal state
+- Tests should survive internal refactors — they describe behavior, not implementation
+
+## Issue Template
+
+<issue-template>
+
+## Problem
+
+Describe the architectural friction:
+
+- Which modules are shallow and tightly coupled
+- What integration risk exists in the seams between them
+- Why this makes the codebase harder to navigate and maintain
+
+## Proposed Interface
+
+The chosen interface design:
+
+- Interface signature (types, methods, params)
+- Usage example showing how callers use it
+- What complexity it hides internally
+
+## Dependency Strategy
+
+Which category applies and how dependencies are handled:
+
+- **In-process**: merged directly
+- **Local-substitutable**: tested with [specific stand-in]
+- **Ports & adapters**: port definition, production adapter, test adapter
+- **Mock**: mock boundary for external services
+
+## Testing Strategy
+
+- **New boundary tests to write**: describe the behaviors to verify at the interface
+- **Old tests to delete**: list the shallow module tests that become redundant
+- **Test environment needs**: any local stand-ins or adapters required
+
+## Implementation Recommendations
+
+Durable architectural guidance that is NOT coupled to current file paths:
+
+- What the module should own (responsibilities)
+- What it should hide (implementation details)
+- What it should expose (the interface contract)
+- How callers should migrate to the new interface
+
+</issue-template>

package/template/skills/core-workflow/audit-architecture/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: audit-architecture
+description: Explore a codebase to find opportunities for architectural improvement, focusing on making the codebase more testable by deepening shallow modules. Use when user wants to improve architecture, find refactoring opportunities, consolidate tightly-coupled modules, or make a codebase more AI-navigable.
+---
+
+# Improve Codebase Architecture
+
+Explore a codebase like an AI would, surface architectural friction, discover opportunities for improving testability, and propose module-deepening refactors as GitHub issue RFCs.
+
+A **deep module** (John Ousterhout, "A Philosophy of Software Design") has a small interface hiding a large implementation. Deep modules are more testable, more AI-navigable, and let you test at the boundary instead of inside.
+
+## Process
+
+### 1. Explore the codebase
+
+Use the Agent tool with subagent_type=Explore to navigate the codebase naturally. Do NOT follow rigid heuristics — explore organically and note where you experience friction:
+
+- Where does understanding one concept require bouncing between many small files?
+- Where are modules so shallow that the interface is nearly as complex as the implementation?
+- Where have pure functions been extracted just for testability, but the real bugs hide in how they're called?
+- Where do tightly-coupled modules create integration risk in the seams between them?
+- Which parts of the codebase are untested, or hard to test?
+
+The friction you encounter IS the signal.
+
+### 2. Present candidates
+
+Present a numbered list of deepening opportunities. For each candidate, show:
+
+- **Cluster**: Which modules/concepts are involved
+- **Why they're coupled**: Shared types, call patterns, co-ownership of a concept
+- **Dependency category**: See [REFERENCE.md](REFERENCE.md) for the four categories
+- **Test impact**: What existing tests would be replaced by boundary tests
+
+Do NOT propose interfaces yet. Ask the user: "Which of these would you like to explore?"
+
+### 3. User picks a candidate
+
+### 4. Frame the problem space
+
+Before spawning sub-agents, write a user-facing explanation of the problem space for the chosen candidate:
+
+- The constraints any new interface would need to satisfy
+- The dependencies it would need to rely on
+- A rough illustrative code sketch to make the constraints concrete — this is not a proposal, just a way to ground the constraints
+
+Show this to the user, then immediately proceed to Step 5. The user reads and thinks about the problem while the sub-agents work in parallel.
+
+### 5. Design multiple interfaces
+
+Spawn 3+ sub-agents in parallel using the Agent tool. Each must produce a **radically different** interface for the deepened module.
+
+Prompt each sub-agent with a separate technical brief (file paths, coupling details, dependency category, what's being hidden). This brief is independent of the user-facing explanation in Step 4. Give each agent a different design constraint:
+
+- Agent 1: "Minimize the interface — aim for 1-3 entry points max"
+- Agent 2: "Maximize flexibility — support many use cases and extension"
+- Agent 3: "Optimize for the most common caller — make the default case trivial"
+- Agent 4 (if applicable): "Design around the ports & adapters pattern for cross-boundary dependencies"
+
+Each sub-agent outputs:
+
+1. Interface signature (types, methods, params)
+2. Usage example showing how callers use it
+3. What complexity it hides internally
+4. Dependency strategy (how deps are handled — see [REFERENCE.md](REFERENCE.md))
+5. Trade-offs
+
+Present designs sequentially, then compare them in prose.
+
+After comparing, give your own recommendation: which design you think is strongest and why. If elements from different designs would combine well, propose a hybrid. Be opinionated — the user wants a strong read, not just a menu.
+
+### 6. User picks an interface (or accepts recommendation)
+
+### 7. Create GitHub issue
+
+Create a refactor RFC as a GitHub issue using `gh issue create`. Use the template in [REFERENCE.md](REFERENCE.md). Do NOT ask the user to review before creating — just create it and share the URL.

package/template/skills/core-workflow/explore-design/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: explore-design
+description: Generate multiple radically different interface designs for a module using parallel sub-agents. Use when user wants to design an API, explore interface options, compare module shapes, or mentions "design it twice".
+---
+
+# Design an Interface
+
+Based on "Design It Twice" from "A Philosophy of Software Design": your first idea is unlikely to be the best. Generate multiple radically different designs, then compare.
+
+## Workflow
+
+### 1. Gather Requirements
+
+Before designing, understand:
+
+- [ ] What problem does this module solve?
+- [ ] Who are the callers? (other modules, external users, tests)
+- [ ] What are the key operations?
+- [ ] Any constraints? (performance, compatibility, existing patterns)
+- [ ] What should be hidden inside vs exposed?
+
+Ask: "What does this module need to do? Who will use it?"
+
+### 2. Generate Designs (Parallel Sub-Agents)
+
+Spawn 3+ sub-agents simultaneously using Task tool. Each must produce a **radically different** approach.
+
+```
+Prompt template for each sub-agent:
+
+Design an interface for: [module description]
+
+Requirements: [gathered requirements]
+
+Constraints for this design: [assign a different constraint to each agent]
+- Agent 1: "Minimize method count - aim for 1-3 methods max"
+- Agent 2: "Maximize flexibility - support many use cases"
+- Agent 3: "Optimize for the most common case"
+- Agent 4: "Take inspiration from [specific paradigm/library]"
+
+Output format:
+1. Interface signature (types/methods)
+2. Usage example (how caller uses it)
+3. What this design hides internally
+4. Trade-offs of this approach
+```
+
+### 3. Present Designs
+
+Show each design with:
+
+1. **Interface signature** - types, methods, params
+2. **Usage examples** - how callers actually use it in practice
+3. **What it hides** - complexity kept internal
+
+Present designs sequentially so user can absorb each approach before comparison.
+
+### 4. Compare Designs
+
+After showing all designs, compare them on:
+
+- **Interface simplicity**: fewer methods, simpler params
+- **General-purpose vs specialized**: flexibility vs focus
+- **Implementation efficiency**: does shape allow efficient internals?
+- **Depth**: small interface hiding significant complexity (good) vs large interface with thin implementation (bad)
+- **Ease of correct use** vs **ease of misuse**
+
+Discuss trade-offs in prose, not tables. Highlight where designs diverge most.
+
+### 5. Synthesize
+
+Often the best design combines insights from multiple options. Ask:
+
+- "Which design best fits your primary use case?"
+- "Any elements from other designs worth incorporating?"
+
+## Evaluation Criteria
+
+From "A Philosophy of Software Design":
+
+**Interface simplicity**: Fewer methods, simpler params = easier to learn and use correctly.
+
+**General-purpose**: Can handle future use cases without changes. But beware over-generalization.
+
+**Implementation efficiency**: Does interface shape allow efficient implementation? Or force awkward internals?
+
+**Depth**: Small interface hiding significant complexity = deep module (good). Large interface with thin implementation = shallow module (avoid).
+
+## Anti-Patterns
+
+- Don't let sub-agents produce similar designs - enforce radical difference
+- Don't skip comparison - the value is in contrast
+- Don't implement - this is purely about interface shape
+- Don't evaluate based on implementation effort