@kurokeita/add-skill 1.17.2 → 1.19.0

package/dist/skills/write-prd/SKILL.md

@@ -0,0 +1,162 @@
+---
+name: write-prd
+description: >
+  Create a developer-focused PRD through user interview, codebase exploration, and module design, then save it
+  under .prd/{prd-name}/ in the current workspace. Use when the user wants to write a PRD, create a product
+  requirements document, plan a new feature, spec out work, or define requirements for implementation. Also
+  trigger when the user says things like "let's plan this feature", "I need a spec for...", "write requirements
+  for...", or "create a PRD for...". Do NOT trigger for: reviewing existing PRDs, creating child tasks from a PRD,
+  or general project management outside the local PRD directory.
+argument-hint: "[prd-name]"
+---
+
+# Write a PRD
+
+Create a developer-focused Product Requirements Document and save it to the local workspace instead of a remote tracker.
+The PRD captures the *what* and *why* of a feature, not line-level implementation details.
+
+During the interview phase, explicitly use the `grill-me` skill if it is available in the current workspace. Treat
+that skill as the driver for the questioning loop, while this skill remains responsible for codebase exploration,
+module design, PRD drafting, and filesystem output.
+
+Output location:
+
+- Directory: `.prd/{prd-name}/`
+- Primary document: `.prd/{prd-name}/prd.md`
+- Optional notes captured during planning: `.prd/{prd-name}/notes.md`
+
+`{prd-name}` should be a filesystem-safe kebab-case slug. If the user provides a title with spaces or punctuation,
+normalize it to kebab-case and tell the user which slug you used.
+
+You may skip steps if they are clearly unnecessary, but do not rush. The value of this skill is in forcing clarity.
+
+## Step 1: Establish the PRD target
+
+If the user provided `$ARGUMENTS`, treat that as the intended PRD name and normalize it to a slug.
+
+If not, ask for the PRD name before writing files.
+
+Before creating files:
+
+- Check whether `.prd/{prd-name}/` already exists
+- If it exists, read `prd.md` if present and summarize the current state
+- Ask whether the user wants to overwrite the PRD, revise it in place, or create a new slug
+
+## Step 2: Get the problem description
+
+Ask the user for a long, detailed description of the problem they want to solve and any candidate solutions they already
+have in mind.
+
+If an existing `.prd/{prd-name}/prd.md` exists, summarize it first so the user can correct or extend it instead of repeating
+context.
+
+## Step 3: Explore the codebase
+
+Before interviewing, ground yourself in the actual codebase:
+
+1. Read the top-level `README.md`, `AGENTS.md`, or other architectural guidance if present
+2. Search broadly for relevant terms, domain concepts, and adjacent implementations
+3. Read area-specific guidance files when relevant
+4. Look for similar features, patterns, and existing terminology
+
+Do not try to read everything. Use search-driven exploration to understand the current state well enough to ask informed
+questions and write an accurate PRD.
+
+## Step 4: Interview relentlessly
+
+Invoke the `grill-me` skill for this phase if available, then interview the user until you reach shared understanding.
+Walk down each branch of the design tree and resolve dependencies one by one.
+
+Ask one question at a time. Keep going until ambiguity is removed.
+
+Ask about:
+
+- Edge cases and failure scenarios
+- Existing behavior that must be preserved
+- What success looks like from the user's perspective
+- Who the end users are
+- Constraints from architecture, rollout, compatibility, or operations
+
+Continue exploring the codebase while interviewing. If a question can be answered by inspecting code, inspect code instead
+of asking the user.
+
+### Scope check
+
+If it becomes clear the work is too large for one PRD, tell the user and ask whether to narrow the scope or continue with
+a larger document that will later be split into multiple execution tracks.
+
+## Step 5: Sketch module design
+
+Sketch the major conceptual modules to build or modify. Look for opportunities to define **deep modules**:
+
+- Interfaces simpler than the implementation they hide
+- Testable in isolation
+- Internals can change without rippling outward
+
+Check that these modules match the user's expectations and ask which ones need stronger test coverage.
+
+## Step 6: Draft the PRD and get approval
+
+Write the PRD and show it to the user for approval before saving or overwriting `prd.md`.
+
+The PRD should be durable:
+
+- Do describe conceptual modules, responsibilities, interfaces, and data flow
+- Do describe architectural patterns and decisions
+- Do not reference specific file paths, class names, or step-by-step implementation procedures
+- Do not include code snippets unless the user explicitly asks for them
+
+Use this structure:
+
+```md
+# {Human-readable PRD title}
+
+## Problem Statement
+
+## Solution
+
+## User Stories
+1. As a ...
+
+## Module Design
+### {Module name}
+- Responsibility:
+- Interface:
+- Status: new | existing
+- Depth: deep | shallow
+
+## Implementation Decisions
+
+## Testing Decisions
+
+## Out of Scope
+
+## Open Questions
+```
+
+Omit `Open Questions` if none remain.
+
+## Step 7: Save to the filesystem
+
+Only save after the user approves the PRD.
+
+Create `.prd/{prd-name}/` if it does not exist.
+
+Write:
+
+- `.prd/{prd-name}/prd.md`: the approved PRD
+
+Optionally write:
+
+- `.prd/{prd-name}/notes.md`: short working notes, unresolved investigation points, or source references gathered during
+  discovery. Keep this concise and operational, not user-facing.
+
+Do not create extra files unless they add real value.
+
+## After saving
+
+Tell the user:
+
+- The slug used
+- The files created or updated
+- Whether this was a new PRD or a revision of an existing directory

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@kurokeita/add-skill",
-	"version": "1.17.2",
+	"version": "1.19.0",
 	"description": "CLI to install AI agent skills to various platforms",
 	"type": "module",
 	"bin": {

package/dist/skills/test-driven-development/testing-anti-patterns.md

@@ -1,316 +0,0 @@
-# Testing Anti-Patterns
-
-**Load this reference when:** writing or changing tests, adding mocks, or tempted to add test-only methods to production code.
-
-## Overview
-
-Tests must verify real behavior, not mock behavior. Mocks are a means to isolate, not the thing being tested.
-
-**Core principle:** Test what the code does, not what the mocks do.
-
-**Following strict TDD prevents these anti-patterns.**
-
-## The Iron Laws
-
-```
-1. NEVER test mock behavior
-2. NEVER add test-only methods to production classes
-3. NEVER mock without understanding dependencies
-```
-
-## Anti-Pattern 1: Testing Mock Behavior
-
-**The violation:**
-
-```typescript
-// ❌ BAD: Testing that the mock exists
-test('renders sidebar', () => {
-  render(<Page />);
-  expect(screen.getByTestId('sidebar-mock')).toBeInTheDocument();
-});
-```
-
-**Why this is wrong:**
-
-- You're verifying the mock works, not that the component works
-- Test passes when mock is present, fails when it's not
-- Tells you nothing about real behavior
-
-**your human partner's correction:** "Are we testing the behavior of a mock?"
-
-**The fix:**
-
-```typescript
-// ✅ GOOD: Test real component or don't mock it
-test('renders sidebar', () => {
-  render(<Page />);  // Don't mock sidebar
-  expect(screen.getByRole('navigation')).toBeInTheDocument();
-});
-
-// OR if sidebar must be mocked for isolation:
-// Don't assert on the mock - test Page's behavior with sidebar present
-```
-
-### Gate Function
-
-```
-BEFORE asserting on any mock element:
-  Ask: "Am I testing real component behavior or just mock existence?"
-
-  IF testing mock existence:
-    STOP - Delete the assertion or unmock the component
-
-  Test real behavior instead
-```
-
-## Anti-Pattern 2: Test-Only Methods in Production
-
-**The violation:**
-
-```typescript
-// ❌ BAD: destroy() only used in tests
-class Session {
-  async destroy() {  // Looks like production API!
-    await this._workspaceManager?.destroyWorkspace(this.id);
-    // ... cleanup
-  }
-}
-
-// In tests
-afterEach(() => session.destroy());
-```
-
-**Why this is wrong:**
-
-- Production class polluted with test-only code
-- Dangerous if accidentally called in production
-- Violates YAGNI and separation of concerns
-- Confuses object lifecycle with entity lifecycle
-
-**The fix:**
-
-```typescript
-// ✅ GOOD: Test utilities handle test cleanup
-// Session has no destroy() - it's stateless in production
-
-// In test-utils/
-export async function cleanupSession(session: Session) {
-  const workspace = session.getWorkspaceInfo();
-  if (workspace) {
-    await workspaceManager.destroyWorkspace(workspace.id);
-  }
-}
-
-// In tests
-afterEach(() => cleanupSession(session));
-```
-
-### Gate Function
-
-```
-BEFORE adding any method to production class:
-  Ask: "Is this only used by tests?"
-
-  IF yes:
-    STOP - Don't add it
-    Put it in test utilities instead
-
-  Ask: "Does this class own this resource's lifecycle?"
-
-  IF no:
-    STOP - Wrong class for this method
-```
-
-## Anti-Pattern 3: Mocking Without Understanding
-
-**The violation:**
-
-```typescript
-// ❌ BAD: Mock breaks test logic
-test('detects duplicate server', () => {
-  // Mock prevents config write that test depends on!
-  vi.mock('ToolCatalog', () => ({
-    discoverAndCacheTools: vi.fn().mockResolvedValue(undefined)
-  }));
-
-  await addServer(config);
-  await addServer(config);  // Should throw - but won't!
-});
-```
-
-**Why this is wrong:**
-
-- Mocked method had side effect test depended on (writing config)
-- Over-mocking to "be safe" breaks actual behavior
-- Test passes for wrong reason or fails mysteriously
-
-**The fix:**
-
-```typescript
-// ✅ GOOD: Mock at correct level
-test('detects duplicate server', () => {
-  // Mock the slow part, preserve behavior test needs
-  vi.mock('MCPServerManager'); // Just mock slow server startup
-
-  await addServer(config);  // Config written
-  await addServer(config);  // Duplicate detected ✓
-});
-```
-
-### Gate Function
-
-```
-BEFORE mocking any method:
-  STOP - Don't mock yet
-
-  1. Ask: "What side effects does the real method have?"
-  2. Ask: "Does this test depend on any of those side effects?"
-  3. Ask: "Do I fully understand what this test needs?"
-
-  IF depends on side effects:
-    Mock at lower level (the actual slow/external operation)
-    OR use test doubles that preserve necessary behavior
-    NOT the high-level method the test depends on
-
-  IF unsure what test depends on:
-    Run test with real implementation FIRST
-    Observe what actually needs to happen
-    THEN add minimal mocking at the right level
-
-  Red flags:
-    - "I'll mock this to be safe"
-    - "This might be slow, better mock it"
-    - Mocking without understanding the dependency chain
-```
-
-## Anti-Pattern 4: Incomplete Mocks
-
-**The violation:**
-
-```typescript
-// ❌ BAD: Partial mock - only fields you think you need
-const mockResponse = {
-  status: 'success',
-  data: { userId: '123', name: 'Alice' }
-  // Missing: metadata that downstream code uses
-};
-
-// Later: breaks when code accesses response.metadata.requestId
-```
-
-**Why this is wrong:**
-
-- **Partial mocks hide structural assumptions** - You only mocked fields you know about
-- **Downstream code may depend on fields you didn't include** - Silent failures
-- **Tests pass but integration fails** - Mock incomplete, real API complete
-- **False confidence** - Test proves nothing about real behavior
-
-**The Iron Rule:** Mock the COMPLETE data structure as it exists in reality, not just fields your immediate test uses.
-
-**The fix:**
-
-```typescript
-// ✅ GOOD: Mirror real API completeness
-const mockResponse = {
-  status: 'success',
-  data: { userId: '123', name: 'Alice' },
-  metadata: { requestId: 'req-789', timestamp: 1234567890 }
-  // All fields real API returns
-};
-```
-
-### Gate Function
-
-```
-BEFORE creating mock responses:
-  Check: "What fields does the real API response contain?"
-
-  Actions:
-    1. Examine actual API response from docs/examples
-    2. Include ALL fields system might consume downstream
-    3. Verify mock matches real response schema completely
-
-  Critical:
-    If you're creating a mock, you must understand the ENTIRE structure
-    Partial mocks fail silently when code depends on omitted fields
-
-  If uncertain: Include all documented fields
-```
-
-## Anti-Pattern 5: Integration Tests as Afterthought
-
-**The violation:**
-
-```
-✅ Implementation complete
-❌ No tests written
-"Ready for testing"
-```
-
-**Why this is wrong:**
-
-- Testing is part of implementation, not optional follow-up
-- TDD would have caught this
-- Can't claim complete without tests
-
-**The fix:**
-
-```
-TDD cycle:
-1. Write failing test
-2. Implement to pass
-3. Refactor
-4. THEN claim complete
-```
-
-## When Mocks Become Too Complex
-
-**Warning signs:**
-
-- Mock setup longer than test logic
-- Mocking everything to make test pass
-- Mocks missing methods real components have
-- Test breaks when mock changes
-
-**your human partner's question:** "Do we need to be using a mock here?"
-
-**Consider:** Integration tests with real components often simpler than complex mocks
-
-## TDD Prevents These Anti-Patterns
-
-**Why TDD helps:**
-
-1. **Write test first** → Forces you to think about what you're actually testing
-2. **Watch it fail** → Confirms test tests real behavior, not mocks
-3. **Minimal implementation** → No test-only methods creep in
-4. **Real dependencies** → You see what the test actually needs before mocking
-
-**If you're testing mock behavior, you violated TDD** - you added mocks without watching test fail against real code first.
-
-## Quick Reference
-
-| Anti-Pattern | Fix |
-|--------------|-----|
-| Assert on mock elements | Test real component or unmock it |
-| Test-only methods in production | Move to test utilities |
-| Mock without understanding | Understand dependencies first, mock minimally |
-| Incomplete mocks | Mirror real API completely |
-| Tests as afterthought | TDD - tests first |
-| Over-complex mocks | Consider integration tests |
-
-## Red Flags
-
-- Assertion checks for `*-mock` test IDs
-- Methods only called in test files
-- Mock setup is >50% of test
-- Test fails when you remove mock
-- Can't explain why mock is needed
-- Mocking "just to be safe"
-
-## The Bottom Line
-
-**Mocks are tools to isolate, not things to test.**
-
-If TDD reveals you're testing mock behavior, you've gone wrong.
-
-Fix: Test real behavior or question why you're mocking at all.