special-agents 0.1.0

package/content/rules/process/tickets.md

@@ -0,0 +1,17 @@
+---
+name: tickets
+category: process
+description: "Ticket log expectations when no external tracker is configured."
+condition: always
+template: false
+supersededByForeman: true
+---
+## Ticket Tracking
+
+- Maintain `docs/tickets.md` as the source of truth if no external tracker is configured.
+- Break work into epics, stories, and implementation tickets where useful.
+- Every ticket should include: ID, title, status, priority, user/business value, acceptance criteria, implementation notes, test expectations, and links to related docs or code when available.
+- Valid statuses: `Backlog`, `Ready`, `In Progress`, `Blocked`, `In Review`, `Done`, `Won't Do`.
+- Add discovered follow-up work, deferred improvements, risks, and future ideas to the ticket log instead of leaving them only in chat.
+- When completing a ticket, mark it `Done` and summarize what changed.
+

package/content/rules/templated/database.md

@@ -0,0 +1,16 @@
+---
+name: database
+category: templated
+description: "Database defaults, migrations, and boundary validation."
+condition: always
+template: true
+---
+## Data And Database Rules
+
+- Use {{database}} by default.
+- Use migrations for schema changes. Do not rely on manual database edits.
+- Keep migrations reviewable and, where practical, reversible.
+- Update seed data, fixtures, and `.env.example` when schema or setup requirements change.
+- Validate data at system boundaries and before persistence.
+- Document important entities and relationships in `docs/architecture.md`.
+

package/content/rules/templated/infra.md

@@ -0,0 +1,18 @@
+---
+name: infra
+category: templated
+description: "Local/cloud runtime parity and infrastructure-as-code expectations."
+condition: cloud
+template: true
+---
+## Infrastructure And Local/Cloud Runtime
+
+- Unless otherwise noted, build applications to run locally and in the cloud.
+- Keep local and cloud environments as similar as practical while documenting intentional differences.
+- Provide a local runtime path using Docker Compose, local services, scripts, or equivalent tooling when the app has service dependencies.
+- Keep `.env.example`, setup docs, seed data, and local database instructions current.
+- Define cloud infrastructure with Infrastructure as Code such as AWS CDK, Terraform, Pulumi, or CloudFormation unless there is a documented reason not to.
+- Avoid manual cloud console changes for durable infrastructure. If manual changes are unavoidable, document them and add follow-up work to codify them.
+- Document {{cloud}} account/region assumptions, IAM model, networking, secrets, storage, databases, queues, observability, and deployment flow in `docs/local-cloud.md`, `docs/architecture.md`, or `docs/operations.md`.
+- Consult the user when local/cloud runtime expectations, hosting constraints, or infrastructure ownership are unclear.
+

package/content/rules/templated/stack.md

@@ -0,0 +1,19 @@
+---
+name: stack
+category: templated
+description: "Default stack choices (package manager, frontend, backend, database, cloud)."
+condition: always
+template: true
+---
+## Default Stack
+
+- Default package manager: `{{packageManager}}`.
+- Default database: {{database}}.
+- Default frontend: {{frontend}}.
+- Unless the user explicitly says otherwise, plan to build a UI for the app. Do not assume an app is API-only, CLI-only, or backend-only.
+- Default backend: {{backend}}.
+- Default cloud infrastructure: {{cloud}}. Suggest another cloud provider when it is clearly more optimal for cost, product fit, compliance, operations, or team constraints.
+- Unless otherwise noted, build applications so they can run both locally and in the cloud. Consult the user if local/cloud runtime expectations are unclear.
+- If planning selects a different stack, update this rule file and the architecture docs to reflect that choice.
+- Prefer TypeScript for JavaScript projects unless the project explicitly chooses otherwise.
+

package/content/skills/better-sqlite3-rebuild/SKILL.md

@@ -0,0 +1,14 @@
+---
+name: better-sqlite3-rebuild
+description: Use when seeing errors about better-sqlite3 native module, NODE_MODULE_VERSION mismatch, "was compiled against a different Node.js version", or similar native binding errors.
+---
+
+# better-sqlite3 Rebuild
+
+When you encounter errors related to `better-sqlite3` and Node.js version mismatches (e.g. `NODE_MODULE_VERSION` mismatch, "was compiled against a different Node.js version", native module load failures), proactively fix by running:
+
+```sh
+npm rebuild
+```
+
+Do this without asking the user first - just rebuild and retry.

package/content/skills/grill-me/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: grill-me
+description: Interview the user relentlessly about a plan or design until reaching shared understanding, resolving each branch of the decision tree. Use when user wants to stress-test a plan, get grilled on their design, or mentions "grill me".
+---
+
+Interview me relentlessly about every aspect of this plan until we reach a shared understanding. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one. For each question, provide your recommended answer.
+
+Ask the questions one at a time.
+
+If a question can be answered by exploring the codebase, explore the codebase instead.

package/content/skills/improve-codebase-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/content/skills/improve-codebase-architecture/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: improve-codebase-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. Write issue file
+
+Write the refactor RFC as a local markdown file in `issues/` using the template in [REFERENCE.md](REFERENCE.md). Do NOT ask the user to review before writing — just write it and share the path.

package/content/skills/prd-to-issues/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: prd-to-issues
+description: Break a PRD into independently-workable issues and write each as a local markdown file in issues/. Use when the user wants to turn a PRD into a list of concrete tasks.
+---
+
+# PRD to Issues
+
+Break a PRD into independently-grabbable issues using vertical slices (tracer bullets), written as local markdown files.
+
+## Process
+
+### 1. Locate the PRD
+
+Ask the user for the PRD file path (e.g. `issues/prd.md`).
+
+If the PRD is not already in your context window, read it from the file.
+
+### 2. Explore the codebase (optional)
+
+If you have not already explored the codebase, do so to understand the current state of the code.
+
+### 3. Draft vertical slices
+
+Break the PRD into **tracer bullet** issues. Each issue is a thin vertical slice that cuts through ALL integration layers end-to-end, NOT a horizontal slice of one layer.
+
+Slices may be 'HITL' or 'AFK'. HITL slices require human interaction, such as an architectural decision or a design review. AFK slices can be implemented and merged without human interaction. Prefer AFK over HITL where possible.
+
+<vertical-slice-rules>
+- Each slice delivers a narrow but COMPLETE path through every layer (schema, API, UI, tests)
+- A completed slice is demoable or verifiable on its own
+- Prefer many thin slices over few thick ones
+</vertical-slice-rules>
+
+### 4. Quiz the user
+
+Present the proposed breakdown as a numbered list. For each slice, show:
+
+- **Title**: short descriptive name
+- **Type**: HITL / AFK
+- **Blocked by**: which other slices (if any) must complete first
+- **User stories covered**: which user stories from the PRD this addresses
+
+Ask the user:
+
+- Does the granularity feel right? (too coarse / too fine)
+- Are the dependency relationships correct?
+- Should any slices be merged or split further?
+- Are the correct slices marked as HITL and AFK?
+
+Iterate until the user approves the breakdown.
+
+### 5. Create the issue files
+
+For each approved slice, write a markdown file in `issues/` using the naming pattern `issues/NNN-short-title.md` (e.g. `issues/001-add-user-auth.md`).
+
+Number issues starting from the next available number (check what files already exist in `issues/`).
+
+Create files in dependency order (blockers first) so you can reference real filenames in the "Blocked by" field.
+
+Do NOT use `gh issue create` or any GitHub CLI commands. Do NOT reference GitHub issue numbers. Use local filenames for all cross-references.
+
+<issue-template>
+## Parent PRD
+
+`issues/prd.md` (or whichever PRD file was used)
+
+## What to build
+
+A concise description of this vertical slice. Describe the end-to-end behavior, not layer-by-layer implementation. Reference specific sections of the parent PRD rather than duplicating content.
+
+## Acceptance criteria
+
+- [ ] Criterion 1
+- [ ] Criterion 2
+- [ ] Criterion 3
+
+## Blocked by
+
+- Blocked by `issues/NNN-title.md` (if any)
+
+Or "None - can start immediately" if no blockers.
+
+## User stories addressed
+
+Reference by number from the parent PRD:
+
+- User story 3
+- User story 7
+
+</issue-template>
+
+Do NOT close or modify the parent PRD file.

package/content/skills/tdd/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: tdd
+description: Test-driven development with red-green-refactor loop. Use when user wants to build features or fix bugs using TDD, mentions "red-green-refactor", wants integration tests, or asks for test-first development.
+---
+
+# Test-Driven Development
+
+## Philosophy
+
+**Core principle**: Tests should verify behavior through public interfaces, not implementation details. Code can change entirely; tests shouldn't.
+
+**Good tests** are integration-style: they exercise real code paths through public APIs. They describe _what_ the system does, not _how_ it does it. A good test reads like a specification - "user can checkout with valid cart" tells you exactly what capability exists. These tests survive refactors because they don't care about internal structure.
+
+**Bad tests** are coupled to implementation. They mock internal collaborators, test private methods, or verify through external means (like querying a database directly instead of using the interface). The warning sign: your test breaks when you refactor, but behavior hasn't changed. If you rename an internal function and tests fail, those tests were testing implementation, not behavior.
+
+See [tests.md](tests.md) for examples and [mocking.md](mocking.md) for mocking guidelines.
+
+## Anti-Pattern: Horizontal Slices
+
+**DO NOT write all tests first, then all implementation.** This is "horizontal slicing" - treating RED as "write all tests" and GREEN as "write all code."
+
+This produces **crap tests**:
+
+- Tests written in bulk test _imagined_ behavior, not _actual_ behavior
+- You end up testing the _shape_ of things (data structures, function signatures) rather than user-facing behavior
+- Tests become insensitive to real changes - they pass when behavior breaks, fail when behavior is fine
+- You outrun your headlights, committing to test structure before understanding the implementation
+
+**Correct approach**: Vertical slices via tracer bullets. One test → one implementation → repeat. Each test responds to what you learned from the previous cycle. Because you just wrote the code, you know exactly what behavior matters and how to verify it.
+
+```
+WRONG (horizontal):
+  RED:   test1, test2, test3, test4, test5
+  GREEN: impl1, impl2, impl3, impl4, impl5
+
+RIGHT (vertical):
+  RED→GREEN: test1→impl1
+  RED→GREEN: test2→impl2
+  RED→GREEN: test3→impl3
+  ...
+```
+
+## Workflow
+
+### 1. Planning
+
+Before writing any code:
+
+- [ ] Confirm with user what interface changes are needed
+- [ ] Confirm with user which behaviors to test (prioritize)
+- [ ] Identify opportunities for [deep modules](deep-modules.md) (small interface, deep implementation)
+- [ ] Design interfaces for [testability](interface-design.md)
+- [ ] List the behaviors to test (not implementation steps)
+- [ ] Get user approval on the plan
+
+Ask: "What should the public interface look like? Which behaviors are most important to test?"
+
+**You can't test everything.** Confirm with the user exactly which behaviors matter most. Focus testing effort on critical paths and complex logic, not every possible edge case.
+
+### 2. Tracer Bullet
+
+Write ONE test that confirms ONE thing about the system:
+
+```
+RED:   Write test for first behavior → test fails
+GREEN: Write minimal code to pass → test passes
+```
+
+This is your tracer bullet - proves the path works end-to-end.
+
+### 3. Incremental Loop
+
+For each remaining behavior:
+
+```
+RED:   Write next test → fails
+GREEN: Minimal code to pass → passes
+```
+
+Rules:
+
+- One test at a time
+- Only enough code to pass current test
+- Don't anticipate future tests
+- Keep tests focused on observable behavior
+
+### 4. Refactor
+
+After all tests pass, look for [refactor candidates](refactoring.md):
+
+- [ ] Extract duplication
+- [ ] Deepen modules (move complexity behind simple interfaces)
+- [ ] Apply SOLID principles where natural
+- [ ] Consider what new code reveals about existing code
+- [ ] Run tests after each refactor step
+
+**Never refactor while RED.** Get to GREEN first.
+
+## Checklist Per Cycle
+
+```
+[ ] Test describes behavior, not implementation
+[ ] Test uses public interface only
+[ ] Test would survive internal refactor
+[ ] Code is minimal for this test
+[ ] No speculative features added
+```

package/content/skills/tdd/deep-modules.md

@@ -0,0 +1,33 @@
+# Deep Modules
+
+From "A Philosophy of Software Design":
+
+**Deep module** = small interface + lots of implementation
+
+```
+┌─────────────────────┐
+│   Small Interface   │  ← Few methods, simple params
+├─────────────────────┤
+│                     │
+│                     │
+│  Deep Implementation│  ← Complex logic hidden
+│                     │
+│                     │
+└─────────────────────┘
+```
+
+**Shallow module** = large interface + little implementation (avoid)
+
+```
+┌─────────────────────────────────┐
+│       Large Interface           │  ← Many methods, complex params
+├─────────────────────────────────┤
+│  Thin Implementation            │  ← Just passes through
+└─────────────────────────────────┘
+```
+
+When designing interfaces, ask:
+
+- Can I reduce the number of methods?
+- Can I simplify the parameters?
+- Can I hide more complexity inside?

package/content/skills/tdd/interface-design.md

@@ -0,0 +1,31 @@
+# Interface Design for Testability
+
+Good interfaces make testing natural:
+
+1. **Accept dependencies, don't create them**
+
+   ```typescript
+   // Testable
+   function processOrder(order, paymentGateway) {}
+
+   // Hard to test
+   function processOrder(order) {
+     const gateway = new StripeGateway();
+   }
+   ```
+
+2. **Return results, don't produce side effects**
+
+   ```typescript
+   // Testable
+   function calculateDiscount(cart): Discount {}
+
+   // Hard to test
+   function applyDiscount(cart): void {
+     cart.total -= discount;
+   }
+   ```
+
+3. **Small surface area**
+   - Fewer methods = fewer tests needed
+   - Fewer params = simpler test setup

package/content/skills/tdd/mocking.md

@@ -0,0 +1,59 @@
+# When to Mock
+
+Mock at **system boundaries** only:
+
+- External APIs (payment, email, etc.)
+- Databases (sometimes - prefer test DB)
+- Time/randomness
+- File system (sometimes)
+
+Don't mock:
+
+- Your own classes/modules
+- Internal collaborators
+- Anything you control
+
+## Designing for Mockability
+
+At system boundaries, design interfaces that are easy to mock:
+
+**1. Use dependency injection**
+
+Pass external dependencies in rather than creating them internally:
+
+```typescript
+// Easy to mock
+function processPayment(order, paymentClient) {
+  return paymentClient.charge(order.total);
+}
+
+// Hard to mock
+function processPayment(order) {
+  const client = new StripeClient(process.env.STRIPE_KEY);
+  return client.charge(order.total);
+}
+```
+
+**2. Prefer SDK-style interfaces over generic fetchers**
+
+Create specific functions for each external operation instead of one generic function with conditional logic:
+
+```typescript
+// GOOD: Each function is independently mockable
+const api = {
+  getUser: (id) => fetch(`/users/${id}`),
+  getOrders: (userId) => fetch(`/users/${userId}/orders`),
+  createOrder: (data) => fetch('/orders', { method: 'POST', body: data }),
+};
+
+// BAD: Mocking requires conditional logic inside the mock
+const api = {
+  fetch: (endpoint, options) => fetch(endpoint, options),
+};
+```
+
+The SDK approach means:
+- Each mock returns one specific shape
+- No conditional logic in test setup
+- Easier to see which endpoints a test exercises
+- Type safety per endpoint

package/content/skills/tdd/refactoring.md

@@ -0,0 +1,10 @@
+# Refactor Candidates
+
+After TDD cycle, look for:
+
+- **Duplication** → Extract function/class
+- **Long methods** → Break into private helpers (keep tests on public interface)
+- **Shallow modules** → Combine or deepen
+- **Feature envy** → Move logic to where data lives
+- **Primitive obsession** → Introduce value objects
+- **Existing code** the new code reveals as problematic

package/content/skills/tdd/tests.md

@@ -0,0 +1,61 @@
+# Good and Bad Tests
+
+## Good Tests
+
+**Integration-style**: Test through real interfaces, not mocks of internal parts.
+
+```typescript
+// GOOD: Tests observable behavior
+test("user can checkout with valid cart", async () => {
+  const cart = createCart();
+  cart.add(product);
+  const result = await checkout(cart, paymentMethod);
+  expect(result.status).toBe("confirmed");
+});
+```
+
+Characteristics:
+
+- Tests behavior users/callers care about
+- Uses public API only
+- Survives internal refactors
+- Describes WHAT, not HOW
+- One logical assertion per test
+
+## Bad Tests
+
+**Implementation-detail tests**: Coupled to internal structure.
+
+```typescript
+// BAD: Tests implementation details
+test("checkout calls paymentService.process", async () => {
+  const mockPayment = jest.mock(paymentService);
+  await checkout(cart, payment);
+  expect(mockPayment.process).toHaveBeenCalledWith(cart.total);
+});
+```
+
+Red flags:
+
+- Mocking internal collaborators
+- Testing private methods
+- Asserting on call counts/order
+- Test breaks when refactoring without behavior change
+- Test name describes HOW not WHAT
+- Verifying through external means instead of interface
+
+```typescript
+// BAD: Bypasses interface to verify
+test("createUser saves to database", async () => {
+  await createUser({ name: "Alice" });
+  const row = await db.query("SELECT * FROM users WHERE name = ?", ["Alice"]);
+  expect(row).toBeDefined();
+});
+
+// GOOD: Verifies through interface
+test("createUser makes user retrievable", async () => {
+  const user = await createUser({ name: "Alice" });
+  const retrieved = await getUser(user.id);
+  expect(retrieved.name).toBe("Alice");
+});
+```