pi-dev 0.1.1

package/skills/taste/SKILL.md

@@ -0,0 +1,148 @@
+---
+name: taste
+description: View, update, or onboard engineering taste (lifecycle, philosophy, testing, architecture, automation, communication) across global → project → package layers. Use when the user says "내 취향 좀 보자", "취향 업데이트", "preferences 보여줘", "taste 갱신", or when /do reports preferences are missing.
+---
+
+# /taste — Project Preferences
+
+Three-layer preferences:
+
+1. **Global** — `~/.pi/agent/preferences.md` (user-level defaults across all projects).
+2. **Project** — `docs/agents/preferences.md` at the repo root (overrides global).
+3. **Package** — `packages/<pkg>/preferences.md` (overrides project for that package only).
+
+Skills merge **global → project → package**, last write wins per key. Other skills must call this merge at the start of every run.
+
+## Modes
+
+- **onboarding** — first time in a project. Project file does not exist. Run a short interview (only project-specific questions; do NOT re-ask global defaults).
+- **init** — same as onboarding but explicitly invoked, even if file exists, with user permission to overwrite.
+- **update** — file exists; user wants to change specific section(s).
+- **review** — print the merged result + per-layer breakdown; stop.
+
+Pick mode based on (a) file existence, (b) user phrasing.
+
+## Onboarding mode (most important)
+
+Triggered by `/do` on first session in a project (no `docs/agents/preferences.md`). Goal: minimal friction, only ask what global cannot answer.
+
+### Onboarding flow
+
+1. **Read global** at `~/.pi/agent/preferences.md`. If missing, fall back to built-in defaults (see below) and warn once.
+2. **Auto-detect project signals** — quick scan to pre-fill answers:
+   - `package.json` workspaces / `pnpm-workspace.yaml` / `turbo.json` → monorepo?
+   - test config (`vitest.config*`, `jest.config*`, `playwright.config*`) → testing stack
+   - scripts named `*live-test*`, `*smoke*`, `e2e*`, `prod:*` → live-test infra strength
+   - `AGENTS.md` / `CLAUDE.md` → existing rules to honour
+   - presence of `docs/agents/{issue-tracker,triage-labels,domain}.md` → already setup-matt-pocock'd
+   - git remote → fork? primary repo?
+   - `CHANGELOG.md` / version → maturity proxy
+   - presence of `.github/workflows/*` → CI strength
+3. **Compute project profile** from signals:
+   - `stage` proxy: changelog age + version + commit cadence
+   - `live-test-infra`: `strong` | `medium` | `weak` based on script/config presence
+   - `mocking-default`: detect mock-heavy patterns vs faux/real-deps
+   - `module-shape`: monorepo vs single-package
+4. **Present a 1-screen summary** of detected signals + the 4–6 questions where project context likely diverges from global. Do not ask anything global already answers consistently.
+
+### The minimal onboarding questions (max 6)
+
+Only ask questions where (a) the project signal contradicts global, OR (b) the question is inherently project-specific:
+
+1. **Project name + 1-line purpose** (always ask — used in free notes)
+2. **Lifecycle stage override?** (only if signals suggest different from global; offer detected default)
+3. **Mocking stance override?** (only if mock-heavy patterns detected and global says `fakes`)
+4. **Local-live entrypoint?** — how does the agent boot the app/subsystem locally? Pick one or describe: `pnpm dev:prod` / `npm run dev` / custom script / "we don't have one yet — agent will build a harness". This drives `local-live-policy=mandatory`.
+5. **Ops-live policy override?** (only if `ops-live-infra=weak` or `=strong` strongly contradicts global)
+6. **Auto-commit/auto-pr override?** (only if repo has fork structure, strong CI, or production-critical paths)
+7. **Regression test locations** — single path, or per-package map. Defaults to `<package>/test/regressions/<slug>.test.ts`.
+8. **Project taboos / blocking rules** (free text — extract from `AGENTS.md` BLOCKING/CRITICAL/NEVER sections, ask user to confirm/append)
+
+Each question:
+
+- One sentence explainer
+- Detected default + global default
+- Choices
+- "skip" or "global default" as bulk-accept
+
+After answers, show the resulting `docs/agents/preferences.md` file (only the keys that **differ from global**) and ask for final OK before writing.
+
+### Built-in fallback defaults (when global missing)
+
+```
+stage=growth, change-budget=module
+simplicity-bias=simple-first, completeness-bias=feature-complete, over-engineering-tolerance=0, durability-target=long-lived
+test-priority-order=local-live>integration>unit, wait-budget-seconds=30, wait-budget-exceeded-action=redesign-test
+test-design-bar=design-first, coverage-scope=critical-paths, mocking-stance=fakes
+local-live-policy=mandatory, ops-live-policy=risk-gated
+module-depth-preference=deep, dedup-trigger=never-preemptive, adr-threshold=hard-to-reverse-only
+auto-create-issues=preview-then-yes, auto-apply-labels=yes, auto-commit-per-slice=staged-only, auto-pr=branch-push-only, interrupt-on-ambiguity=confidence<0.5
+verbosity=minimal, explanation-style=decisions-only, language=ko
+```
+
+## Init / Update / Review modes
+
+- **init**: same as onboarding but assume file may exist; confirm overwrite.
+- **update**: read existing project file. Ask which section(s). Walk only those. Show diff. Write.
+- **review**: print merged result + per-layer breakdown table. Do not modify.
+
+## Output template
+
+Project file format — **only include keys that differ from global**. This keeps files small and the override intent obvious.
+
+```markdown
+# <Project> Engineering Preferences
+
+> Project-level overrides on `~/.pi/agent/preferences.md`. Keys not listed here inherit from global. Edit this file directly to update.
+
+last-updated: YYYY-MM-DD
+project: <name>
+purpose: <one-liner>
+
+## Overrides
+
+- <section>.<key>: <value>   # <one-line rationale>
+
+## Project taboos
+
+- <BLOCKING/NEVER rules from AGENTS.md, confirmed with user>
+
+## Free notes
+
+<free-form>
+```
+
+If there are no overrides (global fits perfectly), still write the file with `purpose`, `taboos`, and free notes — its existence signals "onboarding ran".
+
+**Migration marker**: every project file MUST end with the line
+
+```
+<!-- migrated: <ISO-date> by `/migrate` -->
+```
+
+`/do` checks this marker as the strict gate. If absent, it refuses to start and invokes `/migrate` first. Onboarding without prior migration is not allowed.
+
+## AGENTS.md hookup
+
+After writing the project file, ensure `AGENTS.md` (or `CLAUDE.md`) has:
+
+```markdown
+### Preferences
+
+Per-project engineering preferences in `docs/agents/preferences.md` (overrides on `~/.pi/agent/preferences.md`). The `/do` meta skill reads merged preferences before every run.
+```
+
+If the section already exists, leave it alone.
+
+## Merge function (canonical, for other skills)
+
+```
+merged = global
+for each (key, value) in project:
+    merged[key] = value
+for each (key, value) in package (if applicable):
+    merged[key] = value
+return merged
+```
+
+Other skills should call this merge at run start, never cache across runs.

package/skills/tdd/SKILL.md

@@ -0,0 +1,109 @@
+---
+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
+
+When exploring the codebase, read `docs/agents/domain.md` first if it exists, use the project's domain glossary so that test names and interface vocabulary match the project's language, and respect ADRs in the area you're touching.
+
+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/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/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/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/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/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");
+});
+```

package/skills/to-issues/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: to-issues
+description: Break a plan, spec, or PRD into independently-grabbable issues on the project issue tracker using tracer-bullet vertical slices. Use when user wants to convert a plan into issues, create implementation tickets, or break down work into issues.
+---
+
+# To Issues
+
+Break a plan into independently-grabbable issues using vertical slices (tracer bullets).
+
+The issue tracker and triage label vocabulary should have been provided to you — run `/`/setup`` if not. Before fetching or publishing, read `docs/agents/issue-tracker.md`, `docs/agents/triage-labels.md`, and `docs/agents/domain.md` if they exist.
+
+## Process
+
+### 1. Gather context
+
+Work from whatever is already in the conversation context. If the user passes an issue reference (issue number, URL, or path) as an argument, fetch it from the issue tracker and read its full body and comments.
+
+### 2. Explore the codebase (optional)
+
+If you have not already explored the codebase, do so to understand the current state of the code. Issue titles and descriptions should use the project's domain glossary vocabulary, and respect ADRs in the area you're touching.
+
+### 3. Draft vertical slices
+
+Break the plan 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 this addresses (if the source material has them)
+
+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. Publish the issues to the issue tracker
+
+For each approved slice, publish a new issue to the issue tracker. Use the issue body template below. Apply the `needs-triage` triage label so each issue enters the normal triage flow.
+
+Publish issues in dependency order (blockers first) so you can reference real issue identifiers in the "Blocked by" field.
+
+<issue-template>
+## Parent
+
+A reference to the parent issue on the issue tracker (if the source was an existing issue, otherwise omit this section).
+
+## What to build
+
+A concise description of this vertical slice. Describe the end-to-end behavior, not layer-by-layer implementation.
+
+## Acceptance criteria
+
+- [ ] Criterion 1
+- [ ] Criterion 2
+- [ ] Criterion 3
+
+## Blocked by
+
+- A reference to the blocking ticket (if any)
+
+Or "None - can start immediately" if no blockers.
+
+</issue-template>
+
+Do NOT close or modify any parent issue.

package/skills/to-prd/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: to-prd
+description: Turn the current conversation context into a PRD and publish it to the project issue tracker. Use when user wants to create a PRD from the current context.
+---
+
+This skill takes the current conversation context and codebase understanding and produces a PRD. Do NOT interview the user — just synthesize what you already know.
+
+The issue tracker and triage label vocabulary should have been provided to you — run `/`/setup`` if not. Before publishing, read `docs/agents/issue-tracker.md`, `docs/agents/triage-labels.md`, and `docs/agents/domain.md` if they exist.
+
+## Process
+
+1. Explore the repo to understand the current state of the codebase, if you haven't already. Use the project's domain glossary vocabulary throughout the PRD, and respect any ADRs in the area you're touching.
+
+2. 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.
+
+3. Write the PRD using the template below, then publish it to the project issue tracker. Apply the `needs-triage` triage label so it enters the normal triage flow.
+
+<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>