ShipFrame

View saved version →

---
name: a11y-auditor
description: Audit code, components, or screenshots for WCAG 2.2 accessibility barriers across web and mobile projects.
argument-hint: '[--level <A|AA|AAA>]'
allowed-tools: Read Grep Glob Bash
effort: high
---

# a11y-auditor

**Role:** Senior Digital Accessibility Engineer (CPACC certified).  
**Standard:** WCAG 2.2 — Levels A, AA, and AAA.  
**Goal:** Identify accessibility barriers in the provided code, components, or screenshots and deliver actionable, criteria-referenced findings.

## Usage

**Audit at default level (AA):**
```
/a11y-auditor
```

**Audit at a specific conformance level:**
```
/a11y-auditor --level A
/a11y-auditor --level AA
/a11y-auditor --level AAA
```

> If `--level` is not provided, default to **AA** (the standard legal and compliance baseline).

---

## Step 1 — Resolve Conformance Level

Parse `$ARGUMENTS` for `--level`. Accepted values: `A`, `AA`, `AAA`.  
If not provided, use `AA`.  
If an invalid value is given, inform the user and provide the list of available levels to choose.

---

## Step 2 — Environment Detection

Read `AGENTS.md` at the project root to determine the environment. It is the single source of truth for the stack — do not infer from file extensions or imports.

**If `AGENTS.md` exists:**
- Read the `## Stack` section.
- Classify as **Web** if the framework is any of: HTML, React, Next.js, Remix, Astro, Nuxt, Svelte, Angular, or any browser-targeting stack.
- Classify as **Mobile** if the framework is any of: React Native, Expo, Swift, SwiftUI, Kotlin, Jetpack Compose, or Flutter.
- If the stack targets both (e.g., Expo Web), classify as **Web** and note the dual-target nature in the report.

**If `AGENTS.md` does not exist:**
Stop and inform the user:

> `AGENTS.md` was not found. Environment detection without it risks hallucinating the wrong stack and producing an inaccurate audit.
> Run `/init-project` first to scan the project and generate `AGENTS.md`, then re-run `/a11y-auditor`.

Once classified, **execute only the corresponding section below**. Skip the other entirely.

---

## Web Audit

### Perceivable

**1.1 — Text Alternatives (A)**
- Every `<img>` has a meaningful `alt`. Decorative images use `alt=""`.
- Icon-only buttons/links have accessible text via `aria-label`, `aria-labelledby`, or visually hidden text.
- SVGs used as content have `<title>` and `role="img"`.

**1.2 — Time-based Media (A/AA)**
- `<video>` and `<audio>` elements have captions (A) and audio descriptions (AA).
- Pre-recorded media is not the sole means of conveying information.

**1.3 — Adaptable (A)**
- Semantic HTML is used: headings (`h1–h6`), landmarks (`<main>`, `<nav>`, `<header>`, `<footer>`, `<aside>`), lists (`<ul>`, `<ol>`), and form elements (`<label>`, `<fieldset>`, `<legend>`).
- Reading and operation order makes sense when CSS is disabled.
- Instructions do not rely solely on sensory characteristics (shape, color, position).
- No `orientation` lock without programmatic necessity. *(2.2 new — 1.3.4 AA)*
- Input fields have correct `autocomplete` attributes. *(2.1 — 1.3.5 AA)*

**1.4 — Distinguishable (A/AA/AAA)**
- Color is not the only visual means of conveying information. *(A)*
- Normal text contrast ≥ 4.5:1, large text ≥ 3:1. *(AA)*  
  AAA: normal ≥ 7:1, large ≥ 4.5:1.
- Text can be resized to 200% without loss of content or functionality. *(AA)*
- No text in images except logos. *(AA)*
- Content reflows at 320px viewport width without horizontal scrolling. *(2.1 — 1.4.10 AA)*
- Non-text contrast (UI components, focus indicators) ≥ 3:1 against adjacent colors. *(2.1 — 1.4.11 AA)*
- Text spacing can be overridden (line height ≥ 1.5×, letter spacing ≥ 0.12em, word spacing ≥ 0.16em) without content loss. *(2.1 — 1.4.12 AA)*
- Content on hover/focus is dismissible, hoverable, and persistent. *(2.1 — 1.4.13 AA)*

### Operable

**2.1 — Keyboard Accessible (A)**
- All interactive elements are reachable and operable by keyboard alone.
- No keyboard traps.
- Keyboard s

Preview of the first 4,000 characters. Read full instructions →

View saved version →

---
name: backend-release
description: Verify backend/API releases with tests, migrations, queues, integrations, and endpoint smoke checks.
allowed-tools: Read Glob Grep Bash
argument-hint: '[--app <name>] [--environment <name>]'
effort: medium
---

# Backend Release

Use for Laravel, Node, Python, Rails, Go, or other backend/API releases.

## Steps

1. Load `project-profile` for app-specific release rules.
2. Detect framework, package manager, and runtime.
3. Identify migrations, queues, scheduled jobs, webhooks, and external integrations affected by the diff.
4. Run or list exact checks: dependency validation, lint/static analysis, tests, build/compile.
5. Check required env/config changes are documented and not committed as secrets.
6. Smoke health endpoints and affected API routes in the intended environment.
7. Run `deploy-evidence` before declaring completion.

Never mark complete from a green CI job alone; smoke the intended runtime environment.

View saved version →

---
name: bug-diagnosis
description: Diagnose bugs, regressions, failing tests, or slow behavior by building a reproduction loop before code changes.
---

# Bug Diagnosis

A discipline for hard bugs. Skip phases only when explicitly justified.

When exploring the codebase, read `CONTEXT.md` (if it exists) to get a clear mental model of the relevant modules, and check ADRs in the area you're touching.

## Redact

This skill has you show commands, outputs and captured artifacts. **Redact every secret first** — write `<REDACTED>` in its place. Build loops against env vars, so the credential stays in the environment rather than in what you show. Captured artifacts carry auth headers: quote only the lines that carry the signal.

If the redacted output is not enough to diagnose the bug, say so and ask the user.

## Phase 1 — Build a feedback loop

**This is the skill.** Everything else is mechanical. If you have a **tight** pass/fail signal for the bug — one that goes red on _this_ bug — you will find the cause; bisection, hypothesis-testing, and instrumentation all just consume it. If you don't have one, no amount of staring at code will save you.

Spend disproportionate effort here. **Be aggressive. Be creative. Refuse to give up.**

### Ways to construct one — try them in roughly this order

1. **Failing test** at whatever seam reaches the bug — unit, integration, e2e.
2. **Curl / HTTP script** against a running dev server.
3. **CLI invocation** with a fixture input, diffing stdout against a known-good snapshot.
4. **Headless browser script** (Playwright / Puppeteer) — drives the UI, asserts on DOM/console/network.
5. **Replay a captured trace.** Save a real network request / payload / event log to disk; replay it through the code path in isolation.
6. **Throwaway harness.** Spin up a minimal subset of the system (one service, mocked deps) that exercises the bug code path with a single function call.
7. **Property / fuzz loop.** If the bug is "sometimes wrong output", run 1000 random inputs and look for the failure mode.
8. **Bisection harness.** If the bug appeared between two known states (commit, dataset, version), automate "boot at state X, check, repeat" so you can `git bisect run` it.
9. **Differential loop.** Run the same input through old-version vs new-version (or two configs) and diff outputs.
10. **HITL bash script.** Last resort. If a human must click, drive _them_ with `scripts/hitl-loop.template.sh` so the loop is still structured. Captured output feeds back to you.

Build the right feedback loop, and the bug is 90% fixed.

### Tighten the loop

Treat the loop as a product. Once you have _a_ loop, **tighten** it:

- Can I make it faster? (Cache setup, skip unrelated init, narrow the test scope.)
- Can I make the signal sharper? (Assert on the specific symptom, not "didn't crash".)
- Can I make it more deterministic? (Pin time, seed RNG, isolate filesystem, freeze network.)

A 30-second flaky loop is barely better than no loop; a 2-second deterministic one is tight — a debugging superpower.

### Non-deterministic bugs

The goal is not a clean repro but a **higher reproduction rate**. Loop the trigger 100×, parallelise, add stress, narrow timing windows, inject sleeps. A 50%-flake bug is debuggable; 1% is not — keep raising the rate until it's debuggable.

### When you genuinely cannot build a loop

Stop and say so explicitly. List what you tried. Ask the user for: (a) access to whatever environment reproduces it, (b) a redacted captured artifact (HAR file, log dump, core dump, screen recording with timestamps), or (c) permission to add temporary production instrumentation. Do **not** proceed to hypothesise without a loop.

### Completion criterion — a tight loop that goes red

Phase 1 is done when the loop is **tight** and **red-capable**: you can name **one command** — a script path, a test invocation, a curl — that you have **already run at least once** (show the invocation and its output, redacted), and that is:

Preview of the first 4,000 characters. Read full instructions →

View saved version →

---
name: client-copy-review
description: Review product copy, i18n, email, and landing text for clarity, approvals, and implementation-safe wording.
allowed-tools: Read Glob Grep Bash
argument-hint: '[--language <en|es|both>]'
effort: medium
---

# Client Copy Review

Use before changing visible product text, emails, landing pages, app UI labels, or client-approved copy.

## Rules

- Preserve explicitly approved copy verbatim unless the user asks to revise it.
- If the project is bilingual or localized, update every required locale together.
- Separate factual claims, marketing claims, and implementation status.
- Do not present planned, demo, experimental, or partially shipped work as released.
- Prefer paste-ready final wording.

## Output

```markdown
## Client Copy Review

**Files/areas checked:** <paths>
**Languages:** <languages>

### Recommended copy
<final wording>

### Consistency checks
- ✅/⚠️ <i18n, tone, legal/safety, approval status>

### Implementation notes
- <where to update>
```

View saved version →

---
name: codebase-design
description: Design or improve module seams, interfaces, testability, and codebase structure without changing product behavior.
---

# Codebase Design

Design **deep modules**: a lot of behaviour behind a small interface, placed at a clean seam, testable through that interface. Use this language and these principles wherever code is being designed or restructured. The aim is leverage for callers, locality for maintainers, and testability for everyone.

## Glossary

Use these terms exactly — don't substitute "component," "service," "API," or "boundary." Consistent language is the whole point.

**Module** — anything with an interface and an implementation. Deliberately scale-agnostic: a function, class, package, or tier-spanning slice. _Avoid_: unit, component, service.

**Interface** — everything a caller must know to use the module correctly: the type signature, but also invariants, ordering constraints, error modes, required configuration, and performance characteristics. _Avoid_: API, signature (too narrow — they refer only to the type-level surface).

**Implementation** — what's inside a module, its body of code. Distinct from **Adapter**: a thing can be a small adapter with a large implementation (a Postgres repo) or a large adapter with a small implementation (an in-memory fake). Reach for "adapter" when the seam is the topic; "implementation" otherwise.

**Depth** — leverage at the interface: the amount of behaviour a caller (or test) can exercise per unit of interface they have to learn. A module is **deep** when a large amount of behaviour sits behind a small interface, **shallow** when the interface is nearly as complex as the implementation.

**Seam** _(Michael Feathers)_ — a place where you can alter behaviour without editing in that place; the *location* at which a module's interface lives. Where to put the seam is its own design decision, distinct from what goes behind it. _Avoid_: boundary (overloaded with DDD's bounded context).

**Adapter** — a concrete thing that satisfies an interface at a seam. Describes *role* (what slot it fills), not substance (what's inside).

**Leverage** — what callers get from depth: more capability per unit of interface they learn. One implementation pays back across N call sites and M tests.

**Locality** — what maintainers get from depth: change, bugs, knowledge, and verification concentrate in one place rather than spreading across callers. Fix once, fixed everywhere.

## Deep vs shallow

**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 an interface, ask:

- Can I reduce the number of methods?
- Can I simplify the parameters?
- Can I hide more complexity inside?

## Principles

- **Depth is a property of the interface, not the implementation.** A deep module can be internally composed of small, mockable, swappable parts — they just aren't part of the interface. A module can have **internal seams** (private to its implementation, used by its own tests) as well as the **external seam** at its interface.
- **The deletion test.** Imagine deleting the module. If complexity vanishes, it was a pass-through. If complexity reappears across N callers, it was earning its keep.
- **The interface is the test surface.** Callers and tests cross the same seam. If you want to test *past* the interface, the module is probably the wrong shape.
- **One adapter means a hypothetical seam. Two adapters means a real 

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 2 — file references are metadata, not package contents.

View saved version →

---
name: code-review
description: Review changed code before commit or PR with fast checks plus SOLID, security, performance, and test coverage audit.
argument-hint: '[--base-branch <branch>]'
allowed-tools: Read Grep Glob Bash
effort: high
---

# code-review

Two-phase code review skill. Phase 1 catches surface-level issues fast. Phase 2 audits structural correctness using SOLID as the primary framework and KISS/DRY/YAGNI for implementation quality.

## Usage

**With a base branch** — reviews only the files changed between your current branch and the specified base:
```
/code-review --base-branch main
/code-review --base-branch develop
/code-review --base-branch origin/main
```

**Without arguments** — Claude will detect your local branches and ask you to pick the base interactively:
```
/code-review
```
You'll be prompted with a question like:
> "Which branch should be used as the base for this review?"
> Options: `main`, `master`, `develop`, or any other local branch detected. Select one or type a custom name.

> **Tip:** Run `/init-project` first if the project has no `AGENTS.md`. The review uses it for stack-aware checks in Phase 1.

---

> **Mindset**: There is no reward for speed. The reward comes from persistence on resolving issues to a high standard. Consistent iteration produces better outcomes than fast completion.

---

## Setup — Resolve Base Branch

Current branch: `!git branch --show-current`

Available local branches:
```
!git branch
```

**Step 1 — Parse the argument.**
Check if `$ARGUMENTS` contains `--base-branch`. If it does, extract the value that follows it and use that as `BASE_BRANCH`. Skip to Step 3.

**Step 2 — Ask the user (only if `--base-branch` was not provided).**
Use `AskUserQuestion` with the following question:

- Question: "Which branch should be used as the base for this review?"
- Header: "Base branch"
- Build the options from the branch list above. Always include the most common default (`main`) plus any branches found locally. Cap at 4 options; if there are more, include the 3 most relevant and leave "Other" for free input. If there is no more options but default, just use the default.

**Step 3 — Scope the review to changed files.**
Run:
```
git diff <BASE_BRANCH>...HEAD --name-only
```
Read only the files returned by that command. Do not review files that were not changed relative to `BASE_BRANCH`.

If the diff is empty, inform the user: "No changes detected between the current branch and `<BASE_BRANCH>`." and stop.

---

## Phase 1 — Fast Pre-Commit Check

Catch the 80% of issues before going deeper. Run this first.

### 1.1 Spec & Logic

- [ ] Code exactly matches the stated requirements — no more, no less
- [ ] Edge cases are handled: empty states, null/undefined, error boundaries
- [ ] No leftover debug artifacts: `console.log`, commented-out code, TODO-without-ticket

### 1.2 Type Safety & Validation

- [ ] No unconstrained `any` / `unknown` casts without justification
- [ ] External input (API responses, form data, env vars) is validated at the boundary
- [ ] Types are derived from a single source of truth — not duplicated across files

### 1.3 Stack Alignment

Check the detected stack (see `AGENTS.md` if available) and verify conventions are followed:
- Framework-specific patterns are used correctly (e.g., server vs. client components, lifecycle hooks, routing conventions)
- Styling follows the project's chosen approach consistently
- ORM/database queries follow the project's data-access layer patterns

### 1.4 Verification

- [ ] Existing tests pass
- [ ] New behavior has test coverage (unit or integration)
- [ ] There is observable evidence the change works (test output, screenshot, logs)


### 1.5 Security Checks

- [ ] No hardcoded secrets or credentials
- [ ] No sensitive data in logs or error messages
- [ ] Input validation prevents injection attacks
- [ ] Dependencies are up to date

### 1.6 Performance Checks

- [ ] No N+1 queries
- [ ] No unnecessary database queries
-

Preview of the first 4,000 characters. Read full instructions →

View saved version →

---
name: create-pr
description: Create a Draft GitHub PR or GitLab MR from git diff, commits, CODEOWNERS, and the ShipFrame PR template.
argument-hint: '[--base <branch>] [--ticket-id <id>] [--provider <auto|github|gitlab>] [--auto]'
allowed-tools: Bash AskUserQuestion mcp__github__create_pull_request mcp__github__list_branches
effort: low
---

# create-pr

**Role:** Senior engineer opening a pull request or merge request.
**Goal:** Auto-generate a complete, reviewer-ready PR/MR from git context alone. Every section is derived from the diff, commits, branch name, and project files — no manual writing required. When `--auto` is passed (or when called by another skill/agent), skip all confirmation steps and create the PR/MR immediately.

---

## Step 1 — Parse arguments

Parse `$ARGUMENTS` for:
- `--base <branch>` — target branch for the PR/MR (skip inference if provided)
- `--ticket-id <id>` — ClickUp or issue ID to reference (optional)
- `--provider <auto|github|gitlab>` — host provider to use; default is `auto`
- `--auto` — skip all confirmation steps and create the PR/MR without asking

Capture any provided values. Set `AUTO_MODE = true` if `--auto` is present. Set `PROVIDER_INPUT = auto` when `--provider` is omitted. Reject any provider value outside `auto`, `github`, or `gitlab` with a clear error before doing network operations.

---

## Step 2 — Gather git context

Run all commands via Bash. Capture every output — it feeds every section of the template.

```bash
# Current branch
git branch --show-current

# Remote URL (to detect provider and extract host/owner/repo)
git remote get-url origin

# Current git user email (to exclude from FYI tagging)
git config user.email

# All remote branches (for base branch inference)
git branch -r --format='%(refname:short)' | sed 's/origin\///'

# Last 20 commits on this branch (used for description and module inference)
git log HEAD --oneline -20

# All changed files vs each candidate base branch (resolved once base is confirmed)
# Run after base is resolved:
git diff <BASE_BRANCH>...HEAD --name-only
git diff <BASE_BRANCH>...HEAD --stat
git diff <BASE_BRANCH>...HEAD
```

Extract `HOST`, `OWNER`, and `REPO` from the remote URL:
- GitHub SSH: `git@github.com:owner/repo.git`
- GitHub HTTPS: `https://github.com/owner/repo.git`
- GitLab SSH: `git@gitlab.com:owner/repo.git` or `git@gitlab.example.com:group/subgroup/repo.git`
- GitLab HTTPS: `https://gitlab.com/owner/repo.git` or `https://gitlab.example.com/group/subgroup/repo.git`

Determine `PROVIDER`:
- If `--provider github` was passed, use `github`.
- If `--provider gitlab` was passed, use `gitlab`.
- If `--provider auto` is active and `origin` contains `github.com`, use `github`.
- If `--provider auto` is active and `origin` contains `gitlab.com`, use `gitlab`.
- If `--provider auto` is active and the host is not GitHub, treat remotes whose host or path contains `gitlab` as self-hosted GitLab and use `gitlab`.
- If auto-detection cannot identify the provider, stop and ask the caller to rerun with `--provider github` or `--provider gitlab`.

For GitLab repositories with nested groups, keep the full namespace as `OWNER` (for example, `group/subgroup`) and the final path segment as `REPO`.

If the working tree has uncommitted changes, warn:
> "Uncommitted changes detected. These will not be included in the PR/MR. Commit them first or proceed anyway."
In `AUTO_MODE`, proceed without asking.

---

## Step 3 — Infer the base branch

If `--base` was provided, use it as `BASE_BRANCH` without any confirmation or inference and skip to Step 4. This is always correct when called by `implement-task` — do not second-guess it.

Otherwise, infer from the remote branches list using this priority order:

1. `main`
2. `master`
3. `develop`
4. `staging`
5. First `release/*` branch found
6. If none of the above exist, use the most recently committed remote branch

If `AUTO_MODE` is false and the inferred branch is not `main` or `master`, confirm with the 

Preview of the first 4,000 characters. Read full instructions →

View saved version →

---
name: deploy-evidence
description: Collect concrete deploy or release proof before saying a publish, release, or deployment is complete.
allowed-tools: Read Glob Grep Bash
argument-hint: '[--environment <name>] [--url <url>]'
effort: medium
---

# Deploy Evidence

Verify that a release reached the intended environment with concrete evidence.

## Evidence hierarchy

Prefer direct proof over inferred proof:

1. Production/staging URL smoke result with timestamp.
2. Version endpoint, visible version, release tag, or commit SHA in deployed artifact.
3. CI/deployment job result for the exact commit.
4. Application-specific smoke checks: key routes, API endpoints, queues, webhooks, auth flows.
5. Logs only as supporting evidence, not sole proof.

## Output

```markdown
## Deploy Evidence

**Environment:** <environment>
**Commit/tag/version checked:** <value>
**Timestamp:** <local time>

### Evidence collected
- ✅ <proof>

### Smoke checks
- ✅/⚠️/❌ <check>

### Gaps
- <missing proof or "None">

### Verdict
<Complete only if exact-environment evidence exists; otherwise Not complete>
```

View saved version →

---
name: feature-discovery
description: Gather requirements for a new feature through structured questions and produce a ticket-ready specification.
argument-hint: '[--description "<initial feature idea>"]'
allowed-tools: AskUserQuestion mcp__clickup__clickup_get_workspace_hierarchy mcp__clickup__clickup_create_task TaskCreate Skill
effort: medium
---

# feature-discovery

**Role:** Senior Functional Analyst.  
**Goal:** Elicit, clarify, and structure all requirements for a feature through disciplined questioning. Deliver a complete, unambiguous feature specification that any engineer, designer, or PM can act on immediately.

---

## Mindset

You are not a yes-machine. Your job is to surface assumptions, expose gaps, and challenge vague statements — politely but precisely. A requirement that cannot be tested is not a requirement. Push until every "it should work well" becomes "it must respond in under 200ms for 95% of requests."

Do not dump all questions at once. Questions are grouped into phases. Ask one phase at a time, process the answers, and adapt follow-up questions based on what you learn. The goal is a conversation, not a form.

---

## Step 1 — Get the Initial Description

Parse `$ARGUMENTS` for `--description "<text>"`.

**If `--description` is provided:** use that text as the seed description. Acknowledge it briefly and proceed to Step 2.

**If no `--description` is provided:** use `AskUserQuestion` with:
- Header: "Feature Discovery"
- Question: "What feature do you want to build? Give me as much or as little as you have — a sentence, a paragraph, or a rough idea is all we need to start."

Use the answer as the seed description and proceed to Step 2.

---

## Step 2 — Rapid Clarification (Phase 1)

Before going deep, resolve the most critical ambiguities. Analyze the seed description and identify the top 3–5 questions that would most change the scope or approach. Ask them all in a single `AskUserQuestion` call (multi-question format).

Focus on:
- **Problem vs. solution** — Is the description a problem to solve or a solution already decided? If solution-first, ask what problem it solves.
- **Scope boundaries** — What is explicitly OUT of scope for this feature?
- **Target users** — Who uses this? (role, persona, technical level, volume)
- **Context** — Does this extend an existing feature or is it net new? If existing, what does it touch?
- **Priority driver** — Why now? What business or user pain drives this?

Ask only what is genuinely unclear from the seed. Do not ask for information already stated.

---

## Step 3 — Functional Deep Dive (Phase 2)

Based on the answers from Phase 1, ask a focused set of questions about the functional behavior. Aim for 4–7 questions. Group them logically in a single `AskUserQuestion`.

Cover the relevant subset of:

**User Interactions**
- What actions can the user take? (create, read, update, delete, trigger, configure…)
- Are there multiple entry points or surfaces where this feature is accessible?
- What does the user see/experience when the feature is not available, loading, or errored?

**Data & State**
- What data does this feature create, read, or modify?
- What is the source of truth? Where does data come from and where does it go?
- Are there states the feature can be in? (draft, active, archived, pending…)

**Business Rules & Logic**
- What validations must be enforced?
- Are there conditions under which the feature is locked, hidden, or disabled?
- Are there thresholds, limits, or quotas? (e.g., max 10 items, once per day, only for admin)

**Permissions & Roles**
- Who can access this feature? Who cannot?
- Are there actions restricted to specific roles?

**Integrations**
- Does this feature depend on or trigger anything external? (API, email, webhook, third-party service)
- Does it need to sync with other parts of the product?

Skip any category that is clearly irrelevant to the feature.

---

## Step 4 — Edge Cases & Constraints (Phase 3)

Ask a final, tighter set 

Preview of the first 4,000 characters. Read full instructions →

View saved version →

---
name: frontend-release
description: Verify frontend releases with project-aware build, route smoke checks, assets, i18n, and version validation.
allowed-tools: Read Glob Grep Bash
argument-hint: '[--app <name>] [--environment <name>]'
effort: medium
---

# Frontend Release

Use for Angular, React, Vue, Svelte, static, or SPA frontend releases.

## Steps

1. Load `project-profile` for app-specific release rules.
2. Detect framework and package manager from repo files.
3. Identify build output policy: committed artifact, CI artifact, or platform build.
4. Run or list exact checks: install status, lint, typecheck, tests, build.
5. Inspect generated entrypoints and lazy chunks where relevant.
6. Smoke public routes and app routes required by the profile.
7. Run `deploy-evidence` before declaring completion.

## Required checks to consider

- Version or build identifier where the project has one.
- i18n files when visible text changes.
- Critical routes and auth redirects.
- Console/network errors for browser apps when browser tooling is available.
- Static asset paths and cache-sensitive files.

Never mark complete without exact environment smoke evidence.

View saved version →

---
name: generate-readme
description: Generate or refresh a team-ready README by scanning stack, purpose, commands, and project conventions.
allowed-tools: AskUserQuestion Glob Read Grep Write
effort: medium
---

# generate-readme

Generate a `README.md` file following the ShipFrame team-ready standard. Scan the project to auto-detect as much as possible, then ask only what cannot be inferred.

---

## Step 1 — Gather project context

Scan the project root to detect the tech stack and structure. Use Glob and Read tools — do not guess.

**Detect:**

- **Language & runtime:** `package.json`, `composer.json`, `requirements.txt`, `go.mod`, `Cargo.toml`, `pubspec.yaml`
- **Framework:** check dependencies in `package.json` for `next`, `react`, `vue`, `nuxt`, `express`, `fastify`, `laravel` (via `composer.json`), etc.
- **Database:** look for `prisma`, `drizzle-orm`, `typeorm`, `mongoose`, `pg`, `mysql2`, `sqlite3`, `@supabase`, `pgsql` in dependency files or config files
- **Package manager:** `pnpm-lock.yaml` → pnpm, `yarn.lock` → Yarn, `bun.lockb` → Bun, `package-lock.json` → npm
- **Build tools:** `vite.config.*`, `webpack.config.*`, `turbo.json`
- **Container/infra:** `Dockerfile`, `docker-compose.*`
- **CI/CD:** `.github/workflows/`
- **Dev commands:** read `package.json` scripts section, `Makefile`, or `composer.json` scripts

Read these files if they exist:
- `package.json`
- `composer.json`
- `README.md` (first 50 lines — to avoid overwriting intentional content)
- `.env.example` (keys only, never values)

---

## Step 2 — Ask the user for missing information

After scanning, ask only for information that could not be inferred from the codebase. Use `AskUserQuestion` with a single call covering all needed fields at once (1–4 questions max).

Always ask:
1. **Project name + repository clone URL** — if not clear from `package.json`, `composer.json`, or folder name
2. **Short project description** — one sentence explaining what the project does
3. **Credentials/config location** — where developers get environment variable values (e.g. Passbolt, 1Password, a shared drive link — never hardcode actual values)
4. **Contact info** — Project Manager name + email, Tech Lead name + email

Only ask for stack details if they genuinely could not be detected.

---

## Step 3 — Generate README.md

If `README.md` already exists and contains non-placeholder content, ask for confirmation before overwriting and preserve any clearly intentional hand-written sections.

Write `README.md` at the project root using the template below. Fill every section with real detected values. Use placeholder text only where data is unavailable and mark it with `<!-- TODO: fill in -->`.
Rules:
- Use the project's actual logo if `public/` or `assets/` contains an `.svg` or image with "logo" in the name; otherwise omit the `<img>` tag.
- List only the stack components actually detected — do not invent extras.
- Commands table: list only commands that exist in `package.json` scripts, `Makefile`, or `composer.json` scripts. Do not fabricate commands.
- Keep the tone professional but friendly, matching the example format.
- Never include sensitive values (passwords, API keys, tokens).

---

### README.md template

````markdown
<div align="center">
<img src="./public/<logo-file>" alt="icon">
<h3>
 <project-name> 🚀 ShipFrame
</h3>


   <a href="#-stack">
        Stack
    </a>
    <span>&nbsp;✦&nbsp;</span>
    <a href="#-getting-started">
        Getting Started
    </a>
    <span>&nbsp;✦&nbsp;</span>
   <a href="#-useful-commands">
        Commands
    </a>
    <span>&nbsp;✦&nbsp;</span>
    <a href="#-contribution">
        How to contribute
    </a>
    <span>&nbsp;✦&nbsp;</span>
    <a href="#-deployment">
        How to do a deployment
    </a>
    <span>&nbsp;✦&nbsp;</span>
    <a href="#-contact">
        Contact
    </a>
</div>


## 🛠️ Stack

To start working with <project-name> you will need to have some tools previously installed.

#### Prerequisites

-   SO

Preview of the first 4,000 characters. Read full instructions →

View saved version →

---
name: handoff
description: Compact the current conversation into a handoff document for another agent or future session.
argument-hint: "What will the next session be used for?"
disable-model-invocation: false
---

Write a handoff document summarising the current conversation so a fresh agent can continue the work. Save to the temporary directory of the user's OS - not the current workspace.

Include a "suggested skills" section in the document, which suggests skills that the agent should invoke.

Do not duplicate content already captured in other artifacts (specs, plans, ADRs, issues, commits, diffs). Reference them by path or URL instead.

Redact any sensitive information, such as API keys, passwords, or personally identifiable information.

If the user passed arguments, treat them as a description of what the next session will focus on and tailor the doc accordingly.

View saved version →

---
name: implement-task
description: Implement a scoped task end-to-end by reading context, planning files, changing code, verifying, committing, and preparing PR/MR.
argument-hint: '[--ticket-id <id>] [--description "<text>"]'
allowed-tools: Glob Read Grep Write Edit Bash AskUserQuestion mcp__clickup__clickup_get_task mcp__github__create_pull_request TaskCreate TaskUpdate
effort: high
---

# implement-task

**Role:** Senior software engineer assigned to a task.  
**Goal:** Understand a task fully, plan the implementation at the file level, write production-quality code that follows the project's existing conventions, verify it, commit it, and open a PR/MR — all without inventing requirements or deviating from the project's patterns.

---

## Mindset

Read before you write. Every file you touch must be understood before it is modified. Never guess at conventions — find them in the codebase. If the task is ambiguous after reading all available context, surface the ambiguity and ask rather than assume.

---

## Step 1 — Resolve the task input

Parse `$ARGUMENTS` for `--ticket-id` and `--description`.

**Case A — `--ticket-id` provided:**

Fetch the task from ClickUp:
```
mcp__clickup__clickup_get_task { task_id: "<ticket-id>" }
```
Extract: `name`, `description`, `status`, `assignees`, and `subtasks` (the list of child task objects, if any).

If the ticket cannot be fetched, stop:
> "Could not fetch ticket `<id>`. Check the ID or ClickUp MCP access."

**If the ticket has subtasks (the `subtasks` list is non-empty):**

This is a parent task. Switch to the multi-subtask flow in Step 1b. Do not treat the parent ticket itself as work to implement — it is only the container.

Fetch each subtask in full:
```
mcp__clickup__clickup_get_task { task_id: "<subtask-id>" }
```
Build an ordered list `SUBTASK_LIST` preserving the ClickUp order. For each subtask, parse its description using the 8-section plan-expert template if present (Context, What to implement, Where, Acceptance criteria, Out of scope, Technical notes, Depends on, Definition of done).

Store `PARENT_TICKET_ID`, `PARENT_TICKET_NAME`, and `SUBTASK_LIST`. Set `MULTI_SUBTASK_MODE = true`. Proceed to Step 1b.

**If the ticket has no subtasks:**

This is a leaf task. Parse the description using the 8-section plan-expert template if present. Set `MULTI_SUBTASK_MODE = false` and `CURRENT_TASK = this ticket`. Proceed directly to Step 2.

---

**Case B — `--description` provided (no ticket):**

Run the full `plan-expert` skill as defined in its SKILL.md, passing:
- `--description "<description>"` — the full description text

`plan-expert` will decompose the work into structured subtasks using its 8-section template and present them for confirmation. Once the user confirms, the resulting subtask plan is stored as `TASK_PLAN` and used as the implementation input for all subsequent steps.

Do not proceed to Step 2 until `plan-expert` has completed and the plan is confirmed.

---

**Case C — Neither provided:**

Use `AskUserQuestion`:
- Header: "Implement task"
- Question: "What do you want to implement? Paste a ClickUp ticket ID or describe the task."
- Options: `I have a ClickUp ticket ID`, `I'll describe the task`

If the user provides a ticket ID, treat as Case A.  
If the user provides a description, treat as Case B.

---

## Step 1b — Multi-subtask orchestration

> **Only enter this step when `MULTI_SUBTASK_MODE = true`.** Skip entirely for single tasks.

### Branch structure

Before implementing anything, infer the base branch (same logic as `create-pr` Step 3: check remote branches for `main` → `master` → `develop` → `staging`). Store as `BASE_BRANCH`.

Create a parent feature branch from `BASE_BRANCH`:

```bash
git checkout <BASE_BRANCH>
git checkout -b feat/CU-<PARENT_TICKET_ID>-<slug-of-parent-name>
```

Store this as `PREVIOUS_BRANCH`. This is the branch that subtask 1 will branch from.

### Execution loop

Present the full subtask list to the user before starting:

```
## Mu

Preview of the first 4,000 characters. Read full instructions →

View saved version →

---
name: init-project
description: Scan a new or unfamiliar repo and generate AGENTS.md with stack, commands, structure, and agent context.
allowed-tools: Glob Read Grep Write
effort: medium
---

# init-project

Scan the current project and detect its full tech stack, then generate an `AGENTS.md` file with structured context so future Claude agents have everything they need to work effectively in this codebase.

## Steps

### 1. Scan for stack indicators

Search the project root and subdirectories for the following files and patterns. Use Glob and Read tools — do not guess.

**Languages & runtimes**
- `package.json` → Node.js / JavaScript / TypeScript
- `tsconfig.json` → TypeScript
- `requirements.txt`, `pyproject.toml`, `setup.py`, `Pipfile` → Python
- `Cargo.toml` → Rust
- `go.mod` → Go
- `pom.xml`, `build.gradle`, `build.gradle.kts` → Java / Kotlin
- `*.csproj`, `*.sln` → C# / .NET
- `Gemfile` → Ruby
- `composer.json` → PHP
- `pubspec.yaml` → Dart / Flutter

**Frameworks**
- In `package.json` dependencies/devDependencies: look for `next`, `react`, `vue`, `svelte`, `angular`, `express`, `fastify`, `hono`, `remix`, `astro`, `nuxt`, `gatsby`
- In Python files: look for `django`, `flask`, `fastapi`, `sqlalchemy`
- In `Cargo.toml`: look for `axum`, `actix-web`, `rocket`
- In `go.mod`: look for `gin`, `echo`, `fiber`

**Databases & ORMs**
- In dependency files: look for `prisma`, `drizzle-orm`, `typeorm`, `sequelize`, `mongoose`, `pg`, `mysql2`, `sqlite3`, `redis`, `supabase`, `@planetscale`, `@neon`
- Config files: `prisma/schema.prisma`, `drizzle.config.*`

**Styling**
- `tailwind.config.*` → Tailwind CSS
- In `package.json`: `styled-components`, `@emotion`, `sass`, `less`, `@mui`, `@chakra-ui`, `@radix-ui`, `shadcn`

**Build tools & bundlers**
- `vite.config.*` → Vite
- `webpack.config.*` → Webpack
- `turbo.json` → Turborepo
- `nx.json` → Nx
- `rollup.config.*` → Rollup
- `.swcrc` → SWC

**Testing**
- In `package.json`: `jest`, `vitest`, `@testing-library`, `playwright`, `cypress`, `mocha`
- `pytest.ini`, `conftest.py` → pytest
- `jest.config.*`, `vitest.config.*`

**Infrastructure & deployment**
- `Dockerfile`, `docker-compose.*` → Docker
- `.github/workflows/` → GitHub Actions
- `vercel.json`, `.vercel/` → Vercel
- `netlify.toml` → Netlify
- `fly.toml` → Fly.io
- `terraform/`, `*.tf` → Terraform
- `kubernetes/`, `k8s/`, `*.yaml` with `kind: Deployment` → Kubernetes

**Monorepo**
- `pnpm-workspace.yaml` → pnpm workspaces
- `turbo.json` → Turborepo
- `nx.json` → Nx
- `lerna.json` → Lerna
- `packages/`, `apps/` directories → likely monorepo

**Package manager**
- `pnpm-lock.yaml` → pnpm
- `yarn.lock` → Yarn
- `bun.lockb` → Bun
- `package-lock.json` → npm

**Environment & config**
- `.env`, `.env.example`, `.env.local` → environment variables (list keys only, never values)
- `*.config.ts`, `*.config.js` at root

### 2. Read key files in full

After identifying which files exist, read:
- `package.json` (full)
- `tsconfig.json` (full)
- `prisma/schema.prisma` or `drizzle.config.*` if present
- `README.md` if present (first 80 lines)
- `.env.example` if present (keys only)

### 3. Infer project type

Based on findings, classify the project as one or more of:
- `web-app` (frontend UI)
- `api` (backend/REST/GraphQL)
- `fullstack` (frontend + backend in same repo)
- `cli` (command-line tool)
- `library` (npm/pip/cargo package)
- `mobile` (React Native, Flutter, Expo)
- `monorepo` (multiple apps/packages)
- `infrastructure` (IaC, DevOps-only)

### 4. Generate AGENTS.md

Write `AGENTS.md` at the project root with the following structure. Be specific — list actual package versions from dependency files, not guesses. If something is uncertain, omit it rather than guess.

```markdown
# Project Context

## Project Type
<!-- e.g., fullstack web-app, monorepo -->

## Stack

### Language & Runtime
<!-- e.g., TypeScript 5.4, Node.js 20 -->

### Framework
<!-- e.g., Next.js 14 (App Router) -->

### Styling
<!-- e.g., Tailwind CSS 3.4, shadcn/ui

Preview of the first 4,000 characters. Read full instructions →

View saved version →

---
name: mcp-debugging
description: Diagnose MCP connector failures by separating stored connection state from live upstream tool evidence.
allowed-tools: Read Glob Grep Bash
argument-hint: '[--connector <name>]'
effort: medium
---

# MCP Debugging

Use when an MCP connector, tool, token, or upstream integration appears connected but behavior fails.

## Principles

- Stored connection state is not proof that the upstream service accepts the token/session.
- Prefer a live tool call or minimal endpoint check that exercises the failing capability.
- Capture exact error codes, tool names, timestamps, and sanitized payloads.
- Never expose secrets, tokens, cookies, or auth headers.

## Output

```markdown
## MCP Debug Report

**Connector:** <name>
**Claimed state:** <configured/active/unknown>
**Live check:** <command/tool and result>
**Root cause:** <best-supported cause or unknown>
**User action needed:** <reconnect, grant permission, rotate token, none>
**Evidence:** <sanitized snippets>
```

View saved version →

---
name: plan-expert
description: Plan a ticket or task into ordered subtasks with context, acceptance criteria, out-of-scope, and done definition.
argument-hint: '[--ticket-id <id>] [--description "<text>"]'
allowed-tools: Read Grep Glob Bash AskUserQuestion mcp__clickup__clickup_get_task mcp__clickup__clickup_create_task mcp__clickup__clickup_get_workspace_hierarchy TaskCreate TaskUpdate Skill
effort: medium
---

# plan-expert

**Role:** Senior Technical Project Planner.  
**Goal:** Decompose a task, ticket, or description into a precise, ordered, actionable execution plan with enough detail that any engineer on the team can pick up and implement each step independently.

---

## Usage

**Plan from a ClickUp ticket:**
```
/plan-expert --ticket-id abc123xyz
```

**Plan from a description:**
```
/plan-expert --description "Build a user authentication flow with email and OAuth"
```

**Plan from both (description overrides/extends the ticket):**
```
/plan-expert --ticket-id abc123xyz --description "Focus only on the backend part"
```

**Without arguments** — Claude will ask the user what to plan:
```
/plan-expert
```

---

## Step 1 — Resolve Input

Parse `$ARGUMENTS` to extract `--ticket-id` and `--description`.

**Case A — Neither argument provided:**  
Use `AskUserQuestion` with:
- Question: "What do you want to plan?"
- Header: "Plan Expert"
- Accept free-form text. Treat the answer as the `--description` input and continue to Step 2B.

**Case B — `--ticket-id` provided:**  
Fetch the ticket using the ClickUp MCP:
```
mcp__clickup__clickup_get_task { task_id: "<ticket-id>" }
```
Extract from the response:
- `name` → task title
- `description` → full task description (may be markdown or plain text)
- `status` → current status
- `assignees` → assigned team members
- `subtasks` (if any already exist — note them to avoid duplication)

If the ticket cannot be fetched, inform the user: "Could not fetch ticket `<id>`. Please check the ID or verify ClickUp MCP access." and stop.

**Case C — `--description` provided (no ticket):**  
Use the description text directly as the planning input. Skip to Step 2.

**Case D — Both provided:**  
Fetch the ticket as in Case B. Treat the `--description` as a scope modifier or focus area that overrides or narrows the ticket content for planning purposes. Note both sources when generating the plan.

---

## Step 2 — Analyze & Decompose

Read the resolved input (ticket content and/or description) carefully. Think as a senior engineer scoping a sprint ticket.

### 2.0 Establish codebase scope (REQUIRED — do this before anything else)

Explore the repository to determine what layers and technologies are actually present. Use `Glob`, `Grep`, and `Read` to inspect the project structure. Identify:

- **Project type** — Is this a frontend-only app, a backend API, a full-stack monorepo, a mobile app, a CLI tool, etc.?
- **Tech stack** — Languages, frameworks, and runtimes in use (e.g., React, Next.js, Node/Express, Django, Rails, etc.)
- **Layers present** — Which of the following actually exist in this repo: UI/components, API routes, database models, auth logic, infrastructure config, etc.

**Hard rule: you may only plan work that lives inside the codebase you are operating on.** If the task description implies work in a layer that does not exist in this repo (e.g., backend endpoints in a frontend-only project, database migrations in a UI library, mobile screens in a web app), do NOT plan those subtasks. Instead, flag them explicitly:

> ⚠️ Out of codebase scope: `<description of the work>` requires a `<layer>` that does not exist in this repository. This must be planned and executed in a separate project.

Do not assume a layer exists just because the task description mentions it. Verify in the actual code first.

### 2.1 Identify the goal

Summarize the objective in one sentence: what needs to be true when this is done?

### 2.2 Identify concerns

For each of the following areas, decide if it is relev

Preview of the first 4,000 characters. Read full instructions →

View saved version →

---
name: project-memory-refresh
description: Refresh project context from memory, WIKI/AGENTS files, git state, and repo conventions before work.
allowed-tools: Read Glob Grep Bash
effort: low
---

# Project Memory Refresh

Before changing a project, recover the relevant working context.

## Steps

1. Read `WIKI.md`, `wiki/index.md`, and `AGENTS.md` if present.
2. Inspect git status, current branch, remotes, and recent commits.
3. Search local documentation for the task keywords.
4. Summarize prior decisions, conventions, and likely drift-prone facts.
5. Flag what still needs live verification.

## Output

```markdown
## Project Context Refreshed

**Repo state:** <branch/status/remotes>
**Docs read:** <paths>
**Relevant conventions:** <bullets>
**Needs verification:** <bullets or "None">
```

View saved version →

---
name: project-profile
description: Read project-specific workflow rules before releases, deploys, onboarding, or custom repository conventions.
allowed-tools: Read Glob Grep Bash
effort: low
---

# Project Profile

Load project-specific rules that customize the generic ShipFrame workflow.

## Lookup order

1. `shipframe.profile.md`
2. `.shipframe/profile.md`
3. `.shipframe/project-profile.md`
4. `AGENTS.md` sections mentioning ShipFrame, release, deploy, PR, tickets, or project rules
5. `WIKI.md` and `wiki/sync-config.md` for documented repo boundaries

## What to extract

- Repo topology: root app, nested apps, multi-repo dependencies, generated artifacts.
- Branching and release rules: base branch, protected branches, tags, release notes.
- Verification rules: build, lint, tests, smoke URLs, screenshots, API checks.
- Product rules: i18n, approved copy, client constraints, analytics, access control.
- Deployment evidence: what must be shown before saying work is done.

## Output

Return a concise profile summary:

```markdown
## Project Profile Loaded

**Source files:** <paths read>
**Repo topology:** <summary>
**Release rules:** <summary>
**Verification rules:** <summary>
**Project-specific constraints:** <summary>
**Missing/unclear:** <items or "None">
```

If no profile exists, state that ShipFrame will use the generic workflow and recommend creating `.shipframe/profile.md` for repeatable project rules.

View saved version →

---
name: project-release
description: Orchestrate a generic release by loading project profile rules, running checks, and collecting deploy evidence.
allowed-tools: Read Glob Grep Bash Skill
argument-hint: '[--target <frontend|backend|full-stack|library|docs>] [--environment <name>]'
effort: high
---

# Project Release

Project Release is the generic ShipFrame release entrypoint. It must work across projects without hardcoding a specific client or product.

## Flow

1. Run `project-profile` to load repo-specific rules.
2. Run `release-checklist` to define release gates.
3. Dispatch by target:
   - frontend/static/UI changes → `frontend-release`
   - backend/API/jobs/integrations → `backend-release`
   - both → run both in dependency order from the project profile
   - docs/library-only → run the relevant checklist and evidence steps
4. Run `deploy-evidence` after deploy/publication.
5. Report final status with completed checks, evidence, gaps, and rollback notes.

## Completion rule

Do not say "done", "deployed", or "released" unless the final report includes concrete evidence for the intended environment.

## Final report

```markdown
## Project Release Report

**Target:** <target>
**Environment:** <environment>
**Version/tag/commit:** <value>

### Completed
- ✅ <item>

### Evidence
- ✅ <item>

### Gaps / follow-up
- <item or "None">

### Verdict
<Released | Not released | Partially verified>
```

View saved version →

---
name: release-checklist
description: Build a project-aware release checklist before merge, deploy, publication, or versioned release.
allowed-tools: Read Glob Grep Bash
argument-hint: '[--target <frontend|backend|full-stack|library|docs>]'
effort: medium
---

# Release Checklist

Create a concrete release checklist from the current repo and project profile.

## Steps

1. Load `project-profile` if profile files exist.
2. Detect release target from arguments or changed files.
3. Identify the base branch, release branch, CI requirements, version/tag policy, and deploy mechanism.
4. List exact verification commands and smoke checks.
5. List rollback expectations and post-release evidence.

## Required output

```markdown
## Release Checklist

**Target:** <target>
**Base branch:** <branch>
**Version/tag policy:** <policy or n/a>
**Deploy mechanism:** <command, CI, provider, or unknown>

### Before merge
- [ ] <checks>

### Before deploy
- [ ] <checks>

### After deploy
- [ ] <smoke/evidence>

### Rollback notes
- <rollback path or "Define before deploy">

### Missing decisions
- <items or "None">
```

Do not declare a release complete from successful commands alone; require observable deploy evidence.

View saved version →

---
name: research
description: Research a docs/API/version question against primary sources and capture findings as a Markdown file in the repo.
---

Spin up a **background agent** to do the research, so you keep working while it reads.

Its job:

1. Investigate the question against **primary sources** — official docs, source code, specs, first-party APIs — not a secondary write-up of them. Follow every claim back to the source that owns it.
2. Write the findings to a single Markdown file, citing each claim's source.
3. Save it where the repo already keeps such notes; match the existing convention, and if there is none, put it somewhere sensible and say where.

View saved version →

---
name: tdd
description: Use red-green-refactor test-driven development for features, bug fixes, or integration-test-first work.
---

# Test-Driven Development

TDD is the red → green loop. This skill is the reference that makes that loop produce tests worth keeping: what a good test is, where tests go, the anti-patterns, and the rules of the loop. Every section applies on every cycle — consult them before and during the loop, not after.

When exploring the codebase, read `CONTEXT.md` (if it exists) so test names and interface vocabulary match the project's domain language, and respect ADRs in the area you're touching.

## What a good test is

Tests verify behavior through public interfaces, not implementation details. Code can change entirely; tests shouldn't. A good test reads like a specification — "user can checkout with valid cart" tells you exactly what capability exists — and survives refactors because it doesn't care about internal structure.

See [tests.md](tests.md) for examples and [mocking.md](mocking.md) for mocking guidelines.

## Seams — where tests go

A **seam** is the public boundary you test at: the interface where you observe behavior without reaching inside. Tests live at seams, never against internals.

**Test only at pre-agreed seams.** Before writing any test, write down the seams under test and confirm them with the user. No test is written at an unconfirmed seam. You can't test everything — agreeing the seams up front is how testing effort lands on the critical paths and complex logic instead of every edge case.

Ask: "What's the public interface, and which seams should we test?"

When the shape of that interface is itself in question — how deep the module is, where the seam belongs, what the interface should expose — use the `/codebase-design` skill for the vocabulary. It is the shared source of the module, interface, depth, seam, adapter, leverage and locality terms, and it is a reference to consult, not a session to run.

## Anti-patterns

- **Implementation-coupled** — mocks internal collaborators, tests private methods, or verifies through a side channel (querying the database instead of using the interface). The tell: the test breaks when you refactor but behavior hasn't changed.
- **Tautological** — the assertion recomputes the expected value the way the code does (`expect(add(a, b)).toBe(a + b)`, a snapshot derived by hand the same way, a constant asserted equal to itself), so it passes by construction and can never disagree with the code. Expected values must come from an independent source of truth — a known-good literal, a worked example, the spec.
- **Horizontal slicing** — writing all tests first, then all implementation. Bulk tests verify _imagined_ behavior: you test the _shape_ of things rather than user-facing behavior, the tests go insensitive to real changes, and you commit to test structure before understanding the implementation. Work in **vertical slices** instead — one test → one implementation → repeat, each test a **tracer bullet** that responds to what the last cycle taught you.

## Rules of the loop

- **Red before green.** Write the failing test first, then only enough code to pass it. Don't anticipate future tests or add speculative features.
- **One slice at a time.** One seam, one test, one minimal implementation per cycle.
- **Refactoring is not part of the loop.** It belongs to the review stage (see the `code-review` skill), not the red → green implementation cycle.

Referenced files: 2 — file references are metadata, not package contents.