@kurokeita/add-skill 1.17.1 → 1.18.0

package/dist/skills/gh-fix-ci/SKILL.md

@@ -21,7 +21,11 @@ Prereq: authenticate with the standard GitHub CLI once (for example, run `gh aut
 
 ## Quick start
 
-- `python "<path-to-skill>/scripts/inspect_pr_checks.py" --repo "." --pr "<number-or-url>"`
+- Detect the interpreter first:
+  `PYTHON_BIN=$(command -v python || command -v python3 || true)`
+- If `PYTHON_BIN` is empty, skip the bundled script and use the manual `gh` fallback workflow.
+- Otherwise run:
+  `"$PYTHON_BIN" "<path-to-skill>/scripts/inspect_pr_checks.py" --repo "." --pr "<number-or-url>"`
 - Add `--json` if you want machine-friendly output for summarization.
 
 ## Workflow
@@ -34,7 +38,11 @@ Prereq: authenticate with the standard GitHub CLI once (for example, run `gh aut
    - If the user provides a PR number or URL, use that directly.
 3. Inspect failing checks (GitHub Actions only).
    - Preferred: run the bundled script (handles gh field drift and job-log fallbacks):
-     - `python "<path-to-skill>/scripts/inspect_pr_checks.py" --repo "." --pr "<number-or-url>"`
+     - Resolve the interpreter first:
+       `PYTHON_BIN=$(command -v python || command -v python3 || true)`
+     - If `PYTHON_BIN` is set, run:
+       `"$PYTHON_BIN" "<path-to-skill>/scripts/inspect_pr_checks.py" --repo "." --pr "<number-or-url>"`
+     - If neither `python` nor `python3` is available, skip the bundled script and use the manual fallback below.
      - Add `--json` for machine-friendly output.
    - Manual fallback:
      - `gh pr checks <pr> --json name,state,bucket,link,startedAt,completedAt,workflow`
@@ -65,6 +73,6 @@ Fetch failing PR checks, pull GitHub Actions logs, and extract a failure snippet
 
 Usage examples:
 
-- `python "<path-to-skill>/scripts/inspect_pr_checks.py" --repo "." --pr "123"`
-- `python "<path-to-skill>/scripts/inspect_pr_checks.py" --repo "." --pr "https://github.com/org/repo/pull/123" --json`
-- `python "<path-to-skill>/scripts/inspect_pr_checks.py" --repo "." --max-lines 200 --context 40`
+- `PYTHON_BIN=$(command -v python || command -v python3 || true); test -n "$PYTHON_BIN" && "$PYTHON_BIN" "<path-to-skill>/scripts/inspect_pr_checks.py" --repo "." --pr "123"`
+- `PYTHON_BIN=$(command -v python || command -v python3 || true); test -n "$PYTHON_BIN" && "$PYTHON_BIN" "<path-to-skill>/scripts/inspect_pr_checks.py" --repo "." --pr "https://github.com/org/repo/pull/123" --json`
+- `PYTHON_BIN=$(command -v python || command -v python3 || true); test -n "$PYTHON_BIN" && "$PYTHON_BIN" "<path-to-skill>/scripts/inspect_pr_checks.py" --repo "." --max-lines 200 --context 40`

package/dist/skills/git-branch/SKILL.md

@@ -46,9 +46,9 @@ The branch structure follows a categorized format:
 
 ### Workflow
 
-1. Start from the main integration branch.
-2. Ensure the local branch is up-to-date: `git pull origin main`.
-3. Create the new branch: `git checkout -b <type>/<description>`.
+1. Start from the default branch.
+2. Ensure the local branch is up-to-date: `git pull origin $(git branch --show-current)`.
+3. Create the new branch without tracking: `git checkout --no-track -b <type>/<description>`.
 
 ## Additional Resources
 

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

@@ -0,0 +1,9 @@
+---
+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".
+---
+
+# 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.
+If a question can be answered by exploring the codebase, explore the codebase instead.

package/dist/skills/prd-to-tasks/SKILL.md

@@ -0,0 +1,164 @@
+---
+name: prd-to-tasks
+description: >
+  Break a local PRD into independently grabbable implementation tasks using vertical slices, then save them under
+  .prd/{prd-name}/tasks/ in the current workspace. Use when the user wants to convert a PRD to tasks, break a spec
+  into actionable work, slice a PRD, or create implementation tasks from a local planning document. Do NOT trigger
+  for: writing PRDs, reviewing PRDs without task creation, or remote work item management systems.
+argument-hint: "[prd-name]"
+---
+
+# PRD to Tasks
+
+Break a local PRD into independently grabbable implementation tasks using vertical slices.
+
+Input location:
+
+- PRD directory: `.prd/{prd-name}/`
+- Source PRD: `.prd/{prd-name}/prd.md`
+
+Output location:
+
+- Tasks directory: `.prd/{prd-name}/tasks/`
+- Optional index: `.prd/{prd-name}/tasks/README.md`
+
+`{prd-name}` should be a filesystem-safe kebab-case slug. If the user provides a title instead, normalize it to a slug
+and state the slug you used.
+
+## Step 1: Locate the PRD
+
+If the user provided `$ARGUMENTS`, treat that as the PRD name and normalize it.
+
+If not, ask which PRD directory to use.
+
+Then:
+
+1. Confirm `.prd/{prd-name}/prd.md` exists
+2. Read it fully
+3. Check whether `.prd/{prd-name}/tasks/` already exists
+4. If task files already exist, summarize them and ask whether to overwrite, append, or regenerate selectively
+
+If the PRD does not exist, stop and tell the user exactly which path is missing.
+
+## Step 2: Explore the codebase
+
+If you have not already explored the relevant code in this conversation, do so now:
+
+1. Read top-level architecture guidance if present
+2. Search for code related to the PRD concepts
+3. Read nearby guidance files for affected subsystems
+4. Look for similar features and test patterns
+
+The PRD tells you *what* to build. The codebase tells you enough about *where* and *how* to create useful tasks.
+
+## Step 3: Draft vertical slices
+
+Break the PRD into **tracer bullet** tasks.
+
+### What is a tracer bullet?
+
+A tracer bullet is a thin vertical slice through the whole feature path. It proves that the relevant layers connect
+correctly end to end. It is not a horizontal "build all backend first, then all UI" slice.
+
+Prefer slices that are:
+
+- Independently verifiable
+- Demoable on their own
+- Thin and end to end
+- Ordered by dependency
+
+### HITL vs AFK
+
+Each slice should be marked:
+
+- `HITL`: needs human input, review, testing on real devices, design signoff, or external coordination
+- `AFK`: can be implemented and validated without waiting on a person
+
+### Vertical slice rules
+
+- Each slice should deliver a complete behavior, not one technical layer
+- Prefer many thin slices over a few broad ones
+- Use the PRD's module design to inform slicing, but do not create one task per module
+- Order slices so blockers come first
+
+## Step 4: Quiz the user
+
+Present the proposed slices as a numbered list. For each slice, include:
+
+- Title
+- Type: `HITL` or `AFK`
+- Blocked by
+- User stories covered
+
+Ask the user whether:
+
+- The granularity is right
+- The dependencies are correct
+- Any slices should be merged or split
+- The `HITL` versus `AFK` labels are accurate
+
+Iterate until approved.
+
+## Step 5: Write task files
+
+Only write files after the user approves the breakdown.
+
+Create `.prd/{prd-name}/tasks/` if needed.
+
+Create one Markdown file per task using zero-padded numeric prefixes:
+
+- `.prd/{prd-name}/tasks/01-{task-slug}.md`
+- `.prd/{prd-name}/tasks/02-{task-slug}.md`
+
+`{task-slug}` should be kebab-case and derived from the task title.
+
+Each task file should use this structure:
+
+```md
+# {Task title}
+
+- Type: AFK | HITL
+- Status: Proposed
+- Blocked by: None | 01-other-task
+- Source PRD: ../prd.md
+
+## What to Build
+
+Concise description of the vertical slice. Describe end-to-end behavior, not a layer-by-layer checklist.
+
+## Acceptance Criteria
+
+- [ ] Criterion 1
+- [ ] Criterion 2
+- [ ] Criterion 3
+
+## User Stories Addressed
+
+- User story 3
+- User story 7
+
+## Notes
+
+- Optional implementation hints grounded in the current codebase
+- Reference relevant modules or concepts, but avoid binding the task to fragile file-level details unless necessary
+```
+
+Also create or update `.prd/{prd-name}/tasks/README.md` with:
+
+- The PRD title
+- The approved slice list in dependency order
+- A short summary of each task
+
+## Important constraints
+
+- Do not modify `prd.md` unless the user asks
+- Do not delete existing task files unless the user explicitly approves replacement
+- If existing tasks overlap the proposed slices, call that out before writing duplicates
+
+## After writing
+
+Summarize:
+
+- The PRD slug used
+- The task files created or updated
+- Any existing task files that were preserved

package/dist/skills/test-driven-development/SKILL.md

@@ -1,389 +1,114 @@
 ---
-name: test-driven-development
-description: Use when implementing any feature or bugfix, before writing implementation code
+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 (TDD)
+# Test-Driven Development
 
-## Overview
+## Philosophy
 
-Write the test first. Watch it fail. Write minimal code to pass.
+**Core principle**: Tests should verify behavior through public interfaces, not implementation details. Code can change entirely; tests shouldn't.
 
-**Core principle:** If you didn't watch the test fail, you don't know if it tests the right thing.
+**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.
 
-**Violating the letter of the rules is violating the spirit of the rules.**
+**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.
 
-## When to Use
+See [tests.md](tests.md) for examples and [mocking.md](mocking.md) for mocking guidelines.
 
-**Always:**
+## Anti-Pattern: Horizontal Slices
 
-- New features
-- Bug fixes
-- Refactoring
-- Behavior changes
+**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."
 
-**Exceptions (ask your human partner):**
+This produces **crap tests**:
 
-- Throwaway prototypes
-- Generated code
-- Configuration files
+- 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
 
-Thinking "skip TDD just this once"? Stop. That's rationalization.
+**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.
 
-## The Iron Law
-
-```
-NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST
 ```
-
-Write code before the test? Delete it. Start over.
-
-**No exceptions:**
-
-- Don't keep it as "reference"
-- Don't "adapt" it while writing tests
-- Don't look at it
-- Delete means delete
-
-Implement fresh from tests. Period.
-
-## Red-Green-Refactor
-
-```dot
-digraph tdd_cycle {
-    rankdir=LR;
-    red [label="RED\nWrite failing test", shape=box, style=filled, fillcolor="#ffcccc"];
-    verify_red [label="Verify fails\ncorrectly", shape=diamond];
-    green [label="GREEN\nMinimal code", shape=box, style=filled, fillcolor="#ccffcc"];
-    verify_green [label="Verify passes\nAll green", shape=diamond];
-    refactor [label="REFACTOR\nClean up", shape=box, style=filled, fillcolor="#ccccff"];
-    next [label="Next", shape=ellipse];
-
-    red -> verify_red;
-    verify_red -> green [label="yes"];
-    verify_red -> red [label="wrong\nfailure"];
-    green -> verify_green;
-    verify_green -> refactor [label="yes"];
-    verify_green -> green [label="no"];
-    refactor -> verify_green [label="stay\ngreen"];
-    verify_green -> next;
-    next -> red;
-}
+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
+  ...
 ```
 
-### RED - Write Failing Test
-
-Write one minimal test showing what should happen.
-
-<Good>
-```typescript
-test('retries failed operations 3 times', async () => {
-  let attempts = 0;
-  const operation = () => {
-    attempts++;
-    if (attempts < 3) throw new Error('fail');
-    return 'success';
-  };
+## Workflow
 
-  const result = await retryOperation(operation);
+### 1. Planning
 
-  expect(result).toBe('success');
-  expect(attempts).toBe(3);
-});
+Before writing any code:
 
-```
-Clear name, tests real behavior, one thing
-</Good>
-
-<Bad>
-```typescript
-test('retry works', async () => {
-  const mock = jest.fn()
-    .mockRejectedValueOnce(new Error())
-    .mockRejectedValueOnce(new Error())
-    .mockResolvedValueOnce('success');
-  await retryOperation(mock);
-  expect(mock).toHaveBeenCalledTimes(3);
-});
-```
-
-Vague name, tests mock not code
-</Bad>
+- [ ] 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
 
-**Requirements:**
+Ask: "What should the public interface look like? Which behaviors are most important to test?"
 
-- One behavior
-- Clear name
-- Real code (no mocks unless unavoidable)
+**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.
 
-### Verify RED - Watch It Fail
+### 2. Tracer Bullet
 
-**MANDATORY. Never skip.**
+Write ONE test that confirms ONE thing about the system:
 
-```bash
-npm test path/to/test.test.ts
 ```
-
-Confirm:
-
-- Test fails (not errors)
-- Failure message is expected
-- Fails because feature missing (not typos)
-
-**Test passes?** You're testing existing behavior. Fix test.
-
-**Test errors?** Fix error, re-run until it fails correctly.
-
-### GREEN - Minimal Code
-
-Write simplest code to pass the test.
-
-<Good>
-```typescript
-async function retryOperation<T>(fn: () => Promise<T>): Promise<T> {
-  for (let i = 0; i < 3; i++) {
-    try {
-      return await fn();
-    } catch (e) {
-      if (i === 2) throw e;
-    }
-  }
-  throw new Error('unreachable');
-}
-```
-Just enough to pass
-</Good>
-
-<Bad>
-```typescript
-async function retryOperation<T>(
-  fn: () => Promise<T>,
-  options?: {
-    maxRetries?: number;
-    backoff?: 'linear' | 'exponential';
-    onRetry?: (attempt: number) => void;
-  }
-): Promise<T> {
-  // YAGNI
-}
-```
-Over-engineered
-</Bad>
-
-Don't add features, refactor other code, or "improve" beyond the test.
-
-### Verify GREEN - Watch It Pass
-
-**MANDATORY.**
-
-```bash
-npm test path/to/test.test.ts
+RED:   Write test for first behavior
+       ↓ RUN TESTS — confirm it fails for the right reason
+GREEN: Write minimal code to pass
+       ↓ RUN TESTS — confirm it passes
 ```
 
-Confirm:
-
-- Test passes
-- Other tests still pass
-- Output pristine (no errors, warnings)
-
-**Test fails?** Fix code, not test.
-
-**Other tests fail?** Fix now.
-
-### REFACTOR - Clean Up
-
-After green only:
-
-- Remove duplication
-- Improve names
-- Extract helpers
-
-Keep tests green. Don't add behavior.
-
-### Repeat
-
-Next failing test for next feature.
-
-## Good Tests
-
-| Quality | Good | Bad |
-|---------|------|-----|
-| **Minimal** | One thing. "and" in name? Split it. | `test('validates email and domain and whitespace')` |
-| **Clear** | Name describes behavior | `test('test1')` |
-| **Shows intent** | Demonstrates desired API | Obscures what code should do |
-
-## Why Order Matters
-
-**"I'll write tests after to verify it works"**
-
-Tests written after code pass immediately. Passing immediately proves nothing:
-
-- Might test wrong thing
-- Might test implementation, not behavior
-- Might miss edge cases you forgot
-- You never saw it catch the bug
-
-Test-first forces you to see the test fail, proving it actually tests something.
-
-**"I already manually tested all the edge cases"**
+This is your tracer bullet - proves the path works end-to-end.
 
-Manual testing is ad-hoc. You think you tested everything but:
+**You MUST run the test before writing any implementation.** A test that was never observed to fail might always pass vacuously, be testing the wrong thing, or be broken. The failure message tells you what the test is actually checking.
 
-- No record of what you tested
-- Can't re-run when code changes
-- Easy to forget cases under pressure
-- "It worked when I tried it" ≠ comprehensive
+### 3. Incremental Loop
 
-Automated tests are systematic. They run the same way every time.
+For each remaining behavior:
 
-**"Deleting X hours of work is wasteful"**
-
-Sunk cost fallacy. The time is already gone. Your choice now:
-
-- Delete and rewrite with TDD (X more hours, high confidence)
-- Keep it and add tests after (30 min, low confidence, likely bugs)
-
-The "waste" is keeping code you can't trust. Working code without real tests is technical debt.
-
-**"TDD is dogmatic, being pragmatic means adapting"**
-
-TDD IS pragmatic:
-
-- Finds bugs before commit (faster than debugging after)
-- Prevents regressions (tests catch breaks immediately)
-- Documents behavior (tests show how to use code)
-- Enables refactoring (change freely, tests catch breaks)
-
-"Pragmatic" shortcuts = debugging in production = slower.
-
-**"Tests after achieve the same goals - it's spirit not ritual"**
-
-No. Tests-after answer "What does this do?" Tests-first answer "What should this do?"
-
-Tests-after are biased by your implementation. You test what you built, not what's required. You verify remembered edge cases, not discovered ones.
-
-Tests-first force edge case discovery before implementing. Tests-after verify you remembered everything (you didn't).
-
-30 minutes of tests after ≠ TDD. You get coverage, lose proof tests work.
-
-## Common Rationalizations
-
-| Excuse | Reality |
-|--------|---------|
-| "Too simple to test" | Simple code breaks. Test takes 30 seconds. |
-| "I'll test after" | Tests passing immediately prove nothing. |
-| "Tests after achieve same goals" | Tests-after = "what does this do?" Tests-first = "what should this do?" |
-| "Already manually tested" | Ad-hoc ≠ systematic. No record, can't re-run. |
-| "Deleting X hours is wasteful" | Sunk cost fallacy. Keeping unverified code is technical debt. |
-| "Keep as reference, write tests first" | You'll adapt it. That's testing after. Delete means delete. |
-| "Need to explore first" | Fine. Throw away exploration, start with TDD. |
-| "Test hard = design unclear" | Listen to test. Hard to test = hard to use. |
-| "TDD will slow me down" | TDD faster than debugging. Pragmatic = test-first. |
-| "Manual test faster" | Manual doesn't prove edge cases. You'll re-test every change. |
-| "Existing code has no tests" | You're improving it. Add tests for existing code. |
-
-## Red Flags - STOP and Start Over
-
-- Code before test
-- Test after implementation
-- Test passes immediately
-- Can't explain why test failed
-- Tests added "later"
-- Rationalizing "just this once"
-- "I already manually tested it"
-- "Tests after achieve the same purpose"
-- "It's about spirit not ritual"
-- "Keep as reference" or "adapt existing code"
-- "Already spent X hours, deleting is wasteful"
-- "TDD is dogmatic, I'm being pragmatic"
-- "This is different because..."
-
-**All of these mean: Delete code. Start over with TDD.**
-
-## Example: Bug Fix
-
-**Bug:** Empty email accepted
-
-**RED**
-
-```typescript
-test('rejects empty email', async () => {
-  const result = await submitForm({ email: '' });
-  expect(result.error).toBe('Email required');
-});
-```
-
-**Verify RED**
-
-```bash
-$ npm test
-FAIL: expected 'Email required', got undefined
 ```
-
-**GREEN**
-
-```typescript
-function submitForm(data: FormData) {
-  if (!data.email?.trim()) {
-    return { error: 'Email required' };
-  }
-  // ...
-}
-```
-
-**Verify GREEN**
-
-```bash
-$ npm test
-PASS
+RED:   Write next test
+       ↓ RUN TESTS — confirm new test fails, existing pass
+GREEN: Minimal code to pass
+       ↓ RUN TESTS — confirm all pass
 ```
 
-**REFACTOR**
-Extract validation for multiple fields if needed.
-
-## Verification Checklist
-
-Before marking work complete:
-
-- [ ] Every new function/method has a test
-- [ ] Watched each test fail before implementing
-- [ ] Each test failed for expected reason (feature missing, not typo)
-- [ ] Wrote minimal code to pass each test
-- [ ] All tests pass
-- [ ] Output pristine (no errors, warnings)
-- [ ] Tests use real code (mocks only if unavoidable)
-- [ ] Edge cases and errors covered
-
-Can't check all boxes? You skipped TDD. Start over.
+Rules:
 
-## When Stuck
+- One test at a time
+- Run tests after writing each test (confirm RED) and after each implementation step (confirm GREEN)
+- Only enough code to pass current test
+- Don't anticipate future tests
+- Keep tests focused on observable behavior
 
-| Problem | Solution |
-|---------|----------|
-| Don't know how to test | Write wished-for API. Write assertion first. Ask your human partner. |
-| Test too complicated | Design too complicated. Simplify interface. |
-| Must mock everything | Code too coupled. Use dependency injection. |
-| Test setup huge | Extract helpers. Still complex? Simplify design. |
+### 4. Refactor
 
-## Debugging Integration
+After all tests pass, look for [refactor candidates](refactoring.md):
 
-Bug found? Write failing test reproducing it. Follow TDD cycle. Test proves fix and prevents regression.
+- [ ] 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 fix bugs without a test.
+**Never refactor while RED.** Get to GREEN first.
 
-## Testing Anti-Patterns
-
-When adding mocks or test utilities, read @testing-anti-patterns.md to avoid common pitfalls:
-
-- Testing mock behavior instead of real behavior
-- Adding test-only methods to production classes
-- Mocking without understanding dependencies
-
-## Final Rule
+## Checklist Per Cycle
 
 ```
-Production code → test exists and failed first
-Otherwise → not TDD
+[ ] 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
 ```
-
-No exceptions without your human partner's permission.