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 shortcuts using single characters can be turned off or remapped. *(2.1 — 2.1.4 A)*

**2.2 — Enough Time (A/AA)**
- Moving/auto-updating content can be paused, stopped, or hidden.
- No content flashes more than 3 times per second. *(A)*

**2.4 — Navigable (A/AA/AAA)**
- Skip-to-main-content link is present and functional. *(A)*
- Pages have descriptive `<title>` elements. *(A)*
- Focus order is logical and preserves meaning. *(A)*
- Link purpose is clear from link text alone or context. *(A)*
- Multiple navigation mechanisms exist (nav menu, search, sitemap). *(AA)*
- Headings and labels are descriptive. *(AA)*
- Keyboard focus indicator is visible. *(AA)* *(2.2 enhanced — 2.4.11 AA)*
- Focus indicator has sufficient area and contrast. *(2.2 new — 2.4.11/2.4.12 AA/AAA)*

**2.5 — Input Modalities (A/AA)** *(WCAG 2.1+)*
- Pointer gestures have single-pointer alternatives. *(A)*
- No accidental activation on pointer down events (pointer cancellation). *(A)*
- Labels match accessible names for voice control compatibility. *(A)*
- Motion-based input has a UI alternative and can be disabled. *(A)*
- Target size for interactive elements ≥ 24×24 CSS px. *(2.2 new — 2.5.8 AA)*

### Understandable

**3.1 — Readable (A/AA)**
- `<html lang="...">` is set and correct. *(A)*
- Language changes within a page use `lang` attribute. *(AA)*

**3.2 — Predictable (A/AA)**
- No context changes on focus. *(A)*
- No context changes on input without prior warning. *(A)*
- Consistent navigation order and component labeling across pages. *(AA)*

**3.3 — Input Assistance (A/AA)**
- Errors are identified in text and described to the user. *(A)*
- Labels or instructions are provided for user input. *(A)*
- Error suggestions are offered when known. *(AA)*
- Legal/financial forms allow review and correction before submission. *(AA)*

### Robust

**4.1 — Compatible (A)**
- HTML is valid (no duplicate IDs, no broken nesting that affects AT).
- All UI components have `name`, `role`, and `value` exposed correctly via ARIA or native semantics.
- Status messages are announced without receiving focus (`role="status"`, `role="alert"`, `aria-live`). *(2.1 — 4.1.3 AA)*

---

## Mobile Audit

### React Native / Expo

**Perceivable**
- All `<Image>` components have `accessible={true}` and a meaningful `accessibilityLabel`. Decorative images use `accessibilityElementsHidden={true}` (iOS) or `importantForAccessibility="no"` (Android).
- Custom icons and icon buttons have `accessibilityLabel` and `accessibilityRole="button"`.
- Color is not the only visual means to convey state.
- Text contrast meets ≥ 4.5:1 (normal) and ≥ 3:1 (large) against its background.
- Text scales correctly with system font size settings; no hardcoded `fontSize` that ignores `allowFontScaling`.

**Operable**
- Touchable elements (`TouchableOpacity`, `Pressable`, `TouchableHighlight`) have a minimum touch target of **44×44 pt** (iOS HIG) / **48×48 dp** (Material Design).
- Custom gestures have a single-tap alternative.
- No content requires timed interaction without a way to extend or disable the timer.
- Animations respect the `reduceMotion` accessibility setting:
  ```js
  import { AccessibilityInfo } from 'react-native';
  AccessibilityInfo.isReduceMotionEnabled();
  ```

**Understandable**
- `accessibilityRole` is set correctly on all interactive and semantic elements (`button`, `link`, `header`, `image`, `text`, `checkbox`, `radio`, `tab`, `none`).
- `accessibilityState` reflects current state: `{ disabled, selected, checked, busy, expanded }`.
- `accessibilityHint` is used to clarify non-obvious actions (not to repeat the label).
- Form inputs have associated labels. Use `accessibilityLabelledBy` (RN 0.71+) or combine label + input in an accessible group.
- Error messages are announced via `AccessibilityInfo.announceForAccessibility()`.

**Robust**
- Logical reading order is enforced with `accessibilityViewIsModal` for modals and `importantForAccessibility="yes"` / `accessibilityElementsHidden` to manage focus scope.
- Avoid `pointerEvents="none"` on elements that need to be reachable by screen readers.
- Test with VoiceOver (iOS) and TalkBack (Android) — not just automated tools.

### Swift (iOS Native)

- All `UIView` subclasses that convey information set `isAccessibilityElement = true` and a meaningful `accessibilityLabel`.
- `accessibilityTraits` correctly reflect element type (`.button`, `.header`, `.link`, `.image`, `.selected`, `.notEnabled`).
- `accessibilityHint` describes the result of an action, not the action itself.
- Dynamic Type is supported: use `UIFont.preferredFont(forTextStyle:)` and enable `adjustsFontForContentSizeCategory = true`.
- Minimum touch target: 44×44 pt.
- Reduce Motion is respected: check `UIAccessibility.isReduceMotionEnabled`.
- Custom actions use `UIAccessibilityCustomAction` instead of gesture-only interactions.

### Kotlin / Android Native

- All interactive `View` elements have `contentDescription` set.
- `ViewCompat.setAccessibilityDelegate` is used for custom roles and actions.
- `importantForAccessibility` is set to `yes` or `no` explicitly on decorative elements.
- Minimum touch target: 48×48 dp.
- Reduce Motion: check `Settings.Global.TRANSITION_ANIMATION_SCALE == 0`.
- `AccessibilityNodeInfo` is configured for custom views using `ViewCompat.setAccessibilityDelegate`.

---

## Step 3 — Report Findings

Output findings using this structure:

```
## A11y Audit Report

**Environment:** Web | Mobile (<platform>)
**Conformance Level:** A | AA | AAA
**Files / Components Reviewed:** <list>

---

### ❌ Violations
| WCAG | Level | Issue | Location | Fix |
|------|-------|-------|----------|-----|
| 1.1.1 | A | Missing alt on <img src="hero.png"> | Hero.tsx:14 | Add alt="..." or alt="" if decorative |

### ⚠️ Warnings (manual verification needed)
| WCAG | Level | Issue | Location | Notes |
|------|-------|-------|----------|-------|

### ✅ Passed
- <criterion and what was verified>

---

### Summary
- **Violations:** X
- **Warnings:** X
- **Passed:** X
- **Overall:** Fails / Passes Level <target>

### Recommended Next Steps
1. <highest priority fix>
2. ...
```

**Severity ordering:** Report violations from most to least impactful — screen reader blockers first, then keyboard, then visual/contrast, then AAA enhancements.

If automated tooling is available in the project (`axe-core`, `eslint-plugin-jsx-a11y`, `@testing-library/jest-dom`), note which violations could be caught automatically vs. those requiring manual testing.

---

## Step 4 — Export

After displaying the report, use `AskUserQuestion` to ask:

**Question 1 — Export to file?**
- Question: "Would you like to export this audit report as a Markdown file?"
- Header: "Export report"
- Options:
  - `Yes` — export the report to a `.md` file
  - `No` — finish here, no file written

If the user selects **No**, stop here.

**Question 2 — Export location?** *(only if Yes was selected)*
- Question: "Where should the report be saved?"
- Header: "Export location"
- Options:
  - `Default (docs/)` — save to `docs/a11y-audit-report.md` at the project root
  - `Custom path` — let me type the path

If the user selects **Custom path**, ask them to provide it as free text via the "Other" input.

Once the path is confirmed:
- Resolve it relative to the project root.
- If the target directory does not exist, create it before writing.
- Write the full report content (exactly as displayed in Step 3) to the file.
- Confirm to the user: `Report saved to <resolved-path>`.

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:

- [ ] **Red-capable** — it drives the actual bug code path and asserts the **user's exact symptom**, so it can go red on this bug and green once fixed. Not "runs without erroring" — it must be able to _catch this specific bug_.
- [ ] **Deterministic** — same verdict every run (flaky bugs: a pinned, high reproduction rate, per above).
- [ ] **Fast** — seconds, not minutes.
- [ ] **Agent-runnable** — you can run it unattended; a human in the loop only via `scripts/hitl-loop.template.sh`.

If you catch yourself reading code to build a theory before this command exists, **stop — jumping straight to a hypothesis is the exact failure this skill prevents.** No red-capable command, no Phase 2.

## Phase 2 — Reproduce + minimise

Run the loop. Watch it go red — the bug appears.

Confirm:

- [ ] The loop produces the failure mode the **user** described — not a different failure that happens to be nearby. Wrong bug = wrong fix.
- [ ] The failure is reproducible across multiple runs (or, for non-deterministic bugs, reproducible at a high enough rate to debug against).
- [ ] You have captured the exact symptom (error message, wrong output, slow timing) so later phases can verify the fix actually addresses it.

### Minimise

Once it's red, shrink the repro to the **smallest scenario that still goes red**. Cut inputs, callers, config, data, and steps **one at a time**, re-running the loop after each cut — keep only what's load-bearing for the failure.

Why bother: a minimal repro shrinks the hypothesis space in Phase 3 (fewer moving parts left to suspect) and becomes the clean regression test in Phase 5.

Done when **every remaining element is load-bearing** — removing any one of them makes the loop go green.

Do not proceed until you have reproduced **and** minimised.

## Phase 3 — Hypothesise

Generate **3–5 ranked hypotheses** before testing any of them. Single-hypothesis generation anchors on the first plausible idea.

Each hypothesis must be **falsifiable**: state the prediction it makes.

> Format: "If <X> is the cause, then <changing Y> will make the bug disappear / <changing Z> will make it worse."

If you cannot state the prediction, the hypothesis is a vibe — discard or sharpen it.

**Show the ranked list to the user before testing.** They often have domain knowledge that re-ranks instantly ("we just deployed a change to #3"), or know hypotheses they've already ruled out. Cheap checkpoint, big time saver. Don't block on it — proceed with your ranking if the user is AFK.

## Phase 4 — Instrument

Each probe must map to a specific prediction from Phase 3. **Change one variable at a time.**

Tool preference:

1. **Debugger / REPL inspection** if the env supports it. One breakpoint beats ten logs.
2. **Targeted logs** at the boundaries that distinguish hypotheses.
3. Never "log everything and grep".

**Tag every debug log** with a unique prefix, e.g. `[DEBUG-a4f2]`. Cleanup at the end becomes a single grep. Untagged logs survive; tagged logs die.

**Perf branch.** For performance regressions, logs are usually wrong. Instead: establish a baseline measurement (timing harness, `performance.now()`, profiler, query plan), then bisect. Measure first, fix second.

## Phase 5 — Fix + regression test

Write the regression test **before the fix** — but only if there is a **correct seam** for it.

A correct seam is one where the test exercises the **real bug pattern** as it occurs at the call site. If the only available seam is too shallow (single-caller test when the bug needs multiple callers, unit test that can't replicate the chain that triggered the bug), a regression test there gives false confidence.

**If no correct seam exists, that itself is the finding.** Note it. The codebase architecture is preventing the bug from being locked down. Flag this for the next phase.

If a correct seam exists:

1. Turn the minimised repro into a failing test at that seam.
2. Watch it fail.
3. Apply the fix.
4. Watch it pass.
5. Re-run the Phase 1 feedback loop against the original (un-minimised) scenario.

## Phase 6 — Cleanup + post-mortem

Required before declaring done:

- [ ] Original repro no longer reproduces (re-run the Phase 1 loop)
- [ ] Regression test passes (or absence of seam is documented)
- [ ] All `[DEBUG-...]` instrumentation removed (`grep` the prefix)
- [ ] Throwaway prototypes deleted (or moved to a clearly-marked debug location)
- [ ] The hypothesis that turned out correct is stated in the commit / PR message — so the next debugger learns

**Then ask: what would have prevented this bug?** If the answer involves architectural change (no good test seam, tangled callers, hidden coupling) hand off to the `/improve-codebase-architecture` skill with the specifics. Make the recommendation **after** the fix is in, not before — you have more information now than when you started.

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 one.** Don't introduce a seam unless something actually varies across it.

## Designing for testability

Good interfaces make testing natural:

1. **Accept dependencies, don't create them.**

   ```typescript
   // Testable
   function processOrder(order, paymentGateway) {}

   // Hard to test
   function processOrder(order) {
     const gateway = new StripeGateway();
   }
   ```

2. **Return results, don't produce side effects.**

   ```typescript
   // Testable
   function calculateDiscount(cart): Discount {}

   // Hard to test
   function applyDiscount(cart): void {
     cart.total -= discount;
   }
   ```

3. **Small surface area.** Fewer methods = fewer tests needed. Fewer params = simpler test setup.

## Relationships

- A **Module** has exactly one **Interface** (the surface it presents to callers and tests).
- **Depth** is a property of a **Module**, measured against its **Interface**.
- A **Seam** is where a **Module**'s **Interface** lives.
- An **Adapter** sits at a **Seam** and satisfies the **Interface**.
- **Depth** produces **Leverage** for callers and **Locality** for maintainers.

## Rejected framings

- **Depth as ratio of implementation-lines to interface-lines** (Ousterhout): rewards padding the implementation. We use depth-as-leverage instead.
- **"Interface" as the TypeScript `interface` keyword or a class's public methods**: too narrow — interface here includes every fact a caller must know.
- **"Boundary"**: overloaded with DDD's bounded context. Say **seam** or **interface**.

## Going deeper

- **Deepening a cluster given its dependencies** — see [DEEPENING.md](DEEPENING.md): dependency categories, seam discipline, and replace-don't-layer testing.
- **Exploring alternative interfaces** — see [DESIGN-IT-TWICE.md](DESIGN-IT-TWICE.md): spin up parallel sub-agents to design the interface several radically different ways, then compare on depth, locality, and seam placement.

Referenced files: 2

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
- [ ] No unnecessary API calls
- [ ] No unnecessary computations

**Phase 1 outcome:**
- All items pass → proceed to Phase 2
- Any item fails → fix and re-run Phase 1 before continuing

---

## Phase 2 — Deep SOLID & Structural Audit

### Gate 1: Single Responsibility (SRP)

- **Pass:** Each function/class has one reason to change. Logic is encapsulated by domain. Functions are under ~20 lines.
- **Fail:** "God objects" that mix UI, state, and I/O logic. Deep nesting (>2 levels). Side effects inside functions advertised as pure.
- **Action on Fail:** Trigger decomposition — split logic into atomic, single-purpose units. Each extracted piece should be testable in isolation.

### Gate 2: Open/Closed + Liskov Substitution (OCP/LSP)

- **Pass:** New behavior is added by extending, not by modifying existing code. Subtypes are drop-in replacements for their parents without breaking contracts.
- **Fail:** Large `if/else` or `switch` chains that must grow for each new type. Subclass methods throwing "Not Implemented".
- **Action on Fail:** Refactor using the Strategy pattern or polymorphism. Close the current abstraction and extend via composition.

### Gate 3: Interface Segregation + Dependency Inversion (ISP/DIP)

- **Pass:** Interfaces are narrow — clients only depend on what they use. High-level modules depend on abstractions, not concrete implementations.
- **Fail:** "Fat" interfaces where implementors are forced to stub unused methods. Hardcoded `new SpecificClass()` inside constructors. Tight coupling to third-party SDKs in business logic.
- **Action on Fail:** Introduce dependency injection. Split fat interfaces into focused contracts. Wrap third-party dependencies behind an abstraction layer owned by your code.

### Gate 4: Pragmatic Quality (KISS / DRY / YAGNI)

- **Pass:** Zero duplicated logic. Simplest solution that satisfies the requirement. Intent-revealing names (`isExpired` vs `flag`). Related code is colocated.
- **Fail:** Over-engineering for hypothetical future requirements. Magic numbers. Single-use abstractions with more complexity than the code they replaced. Abbreviated names (`ptr`, `tmp`, `idx`).
- **Action on Fail:** Inline over-engineered abstractions. Replace magic numbers with named constants. Choose duplication over a premature abstraction when the abstraction adds net complexity.

---

## Phase 2 — Critical Patterns

### Dependency Impact Scan

Before any signature change, identify every file that imports the target.  
If a signature changes, all dependent files **must** be updated in the same change. Never leave broken imports or type errors downstream.

### Structural Integrity

- Check for unreachable code and dead exports
- Check for circular dependencies
- Verify files are in the correct location per the project's structure (reference `AGENTS.md`)
- Run the project's lint and type-check commands. Block completion if they fail.

---

## Reporting

After completing both phases, report findings in this format:

```
## Code Review Results

### ❌ Errors (must fix)
- <specific issue, file:line, remediation>

### ⚠️ Warnings (should fix)
- <specific issue, file:line, remediation>

### ✅ Passed
- <what was verified>

### Recommendation
Approve / Request Changes — <one-line rationale>
```

- If errors exist: report them and ask "Should I apply the fixes?"
- After applying fixes: re-run the relevant phase to verify resolution
- If the codebase has no `AGENTS.md`, suggest running `/init-project` first for better stack-aware review

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 user:
> "Inferred base branch: `<branch>`. Is this correct?"
In `AUTO_MODE`, proceed with the inferred branch silently.

If the current branch equals `BASE_BRANCH`, stop:
> "The current branch is the same as the base branch. Switch to a feature branch first."

---

## Step 4 — Infer PR/MR title

Derive the PR/MR title from the branch name:
1. Strip the type prefix: `feat/`, `fix/`, `chore/`, `refactor/`, `docs/`, `hotfix/`
2. Strip any ticket/sprint/module prefix (e.g. `CU-abc123-`, `M3-S12-`)
3. Replace hyphens and underscores with spaces
4. Title-case the result
5. Prepend the type label in brackets: `[Feature]`, `[Fix]`, `[Refactor]`, `[Docs]`, `[Chore]`, `[Hotfix]`
6. If a ticket ID is available (from `--ticket-id` or extracted from the branch name), append it: `(CU-abc123)`

Example: `feat/CU-abc123-user-auth-flow` → `[Feature] User auth flow (CU-abc123)`

---

## Step 5 — Populate the PR/MR template

The canonical PR/MR body structure is defined in `templates/pull_request_template.md` at the project root of the **ShipFrame** repo (the repo where this skill lives). Read that file and use it as the exact skeleton — do not invent or remove sections. Populate every placeholder by analyzing the git context from Step 2. Instructions inside each section below describe how to derive the content — follow them precisely. The rendered output must not contain the instruction text or placeholder markers.

---

### Section: Description

Using the commit messages and `git diff` output:

- Write 2–4 bullet points summarising the "Why" (motivation / problem solved) and "What" (what was changed at a high level)
- Every bullet must start with exactly one of these semantic keywords: `add`, `update`, `fix`, `refactor`, `delete`
- Do not paste raw commit messages — rewrite them as coherent intent statements
- Be specific: reference function names, component names, or API routes where relevant

---

### Section: Type of Change

From the PR/MR title type label (inferred in Step 4) or the branch prefix, tick exactly one checkbox:

| Branch prefix / label | Checkbox to tick |
|---|---|
| `feat/` / `[Feature]` | `- [x] Feature` |
| `fix/` / `[Fix]` | `- [x] Bug Fix` |
| `refactor/` / `[Refactor]` | `- [x] Refactor` |
| `docs/` / `[Docs]` | `- [x] Docs` |
| `chore/` / `[Chore]` | `- [x] Chore` |
| `hotfix/` / `[Hotfix]` | `- [x] Hotfix` |

Leave all others unchecked.

---

### Section: Related Ticket

- If `--ticket-id` was provided, format it as a ClickUp URL: `https://app.clickup.com/t/<id>`
- If a ticket ID was extracted from the branch name (e.g. `CU-abc123`), use the same format
- If no ticket is available, write: `N/A`

---

### Section: Module

Parse the branch name and the last 20 commit messages for:

- **Migration Number / Section Name** — look for patterns like `M1`, `M2`, `M3`, `migration-1`, `section-2` in the branch name or commits. Extract as `M{N}`. If not found, write `<!-- TBD -->`.
- **Sprint** — look for patterns like `S12`, `sprint-12`, `sprint/12` in the branch name or commits. Extract as `S{N}`. If not found, write `<!-- TBD -->`.

Never invent values. Placeholders are correct when data is absent.

---

### Section: Shared Code Impact

Inspect the list of changed files (`git diff --name-only`) for any files inside directories that suggest shared or cross-cutting code:

- Common directory names: `shared/`, `core/`, `common/`, `lib/`, `utils/`, `helpers/`, `hooks/`, `composables/`, `services/`, `types/`, `constants/`

If any matches are found:
- Answer: **Yes**
- List each affected file path
- Add: `Team notified: No` (the author must verify before merge)

If no matches: Do not include the `### Shared Code Impact` section in the rendered PR body.

---

### Section: Breaking Changes

Analyze the git diff and commit messages for indications of breaking changes, such as:
- Modified or removed API route parameters/responses
- Changes to shared library function signatures/interfaces
- Database schema changes that remove or alter columns
- Commit messages containing `BREAKING CHANGE:` or `!` in the type prefix (e.g. `feat!:`)

If breaking changes are detected:
- Answer: **Yes**
- Describe what breaks and the required migration path for other developers

If no breaking changes: Do not include the `### Breaking Changes` section in the rendered PR body.

---

### Section: FYI

1. Check if a `CODEOWNERS` file exists at the project root or `.github/CODEOWNERS`.  
   If it exists, read it and extract GitHub handles (`@username`) mapped to the changed files.

2. Also run:
   ```bash
   git log <BASE_BRANCH>...HEAD --invert-grep -E --format="%ae" -- <changed files> | sort | uniq
   ```
   Map contributor emails to GitHub handles where possible (use the handle from CODEOWNERS if the same person appears there).

3. Combine both sources into a de-duplicated list of `@handles`.

4. **Mandatory:** remove the current PR author's handle from the list (identified by `git config user.email` from Step 2).

5. If the list is empty after deduplication, write: `No additional stakeholders identified.`

---

### Section: Screenshots

Inspect the changed file paths for UI indicators:
- Directories: `pages/`, `views/`, `routes/`, `screens/`, `app/`, `src/app/`
- File extensions or names containing: `.vue`, `.svelte`, `Page.`, `View.`, `Screen.`, `Layout.`
- Any component file touched inside a route-level directory

**If UI changes are detected:**
- List each modified route or page
- For each, provide a provider-specific raw/blob URL format for evidence screenshots:
  ```
  # GitHub
  https://github.com/<OWNER>/<REPO>/blob/<CURRENT_BRANCH>/.github/evidence/<filename>.png?raw=true

  # GitLab
  https://<HOST>/<OWNER>/<REPO>/-/blob/<CURRENT_BRANCH>/.github/evidence/<filename>.png
  ```
- Note: "Add screenshots at the paths above before requesting review."

**If no UI changes:** write: `No UI changes in this PR.`

---

### Section: Test Plan

Derive a concrete, ordered checkbox list a reviewer can follow to verify the changes end-to-end.

Rules:
- Every step must come from the actual diff — no generic steps like "verify the app works"
- Start from the entry point a real user or caller would use (navigate to a route, call an endpoint, trigger an action)
- Cover the happy path first, then at least one edge or error case if changes touch validation, error handling, or conditional logic
- Include any required setup (env vars, feature flags, seed data, running migrations)
- One action per checkbox — short and imperative
- If the change is backend-only: describe the API call (method, endpoint, payload, expected response)
- If the change is UI-only: describe the user interaction and the expected visual or functional outcome
- If new tests were added: include a step to run them with the specific command (e.g. `npm test -- --testPathPattern=<file>`)

Format:
```
- [ ] <imperative step>
- [ ] <imperative step>
```

---

### Section: Release Readiness

- `Ready for release:` Yes — if all test plan steps are expected to pass based on the implementation
- `Needs additional work:` No — unless there are known gaps, open questions, or incomplete items identified during implementation

---

## Step 6 — Render and confirm

Assemble the full PR body using this exact structure:

```markdown
## Description 📝
<populated description bullets>

### Type of Change
<checkbox list with exactly one item checked based on branch type>

### Related Ticket
<ticket URL or "N/A">

### Module
- Migration: <M{N} or TBD>
- Sprint: <S{N} or TBD>

### Shared Code Impact
<Include only if Yes: file list and Team notified>

### Breaking Changes
<Include only if Yes: describe what breaks and the migration path>

### FYI 🙋
<@handles or "No additional stakeholders identified.">

### Screenshots 📸
<screenshot entries or "No UI changes in this PR.">

### Test Plan 🧪
<checkbox list>

### Release Readiness
- Ready for release: <Yes/No>
- Needs additional work: <Yes/No>
```

If `AUTO_MODE` is **false**, present the rendered body and the inferred title to the user and ask:
> "Does this PR/MR look correct? Reply Yes to create it, or paste corrections."
Apply any corrections before proceeding.

If `AUTO_MODE` is **true**, skip confirmation and proceed immediately.

---

## Step 7 — Create the PR/MR

**All PRs and MRs must be created as Draft. This is non-negotiable — never omit `--draft`.**

Before invoking provider CLIs, write the rendered body to a temporary file and keep its path in `BODY_FILE` so the user can reuse it if creation fails:

```bash
BODY_FILE="$(mktemp -t shipframe-pr-mr-body.XXXXXX.md)"
printf '%s\n' "<rendered PR/MR body>" > "$BODY_FILE"
```

### GitHub provider: gh CLI

Use this path when `PROVIDER=github`.

First verify the local CLI and authentication:

```bash
command -v gh
gh auth status
```

If `gh` is missing or unauthenticated, stop and report:

```text
GitHub PR not created. ShipFrame generated the body at <BODY_FILE>.
Install/authenticate GitHub CLI, then rerun:
  brew install gh
  gh auth login
  gh auth status
```

Create the Draft PR:

```bash
gh pr create \
  --title "<PR/MR title>" \
  --body-file "$BODY_FILE" \
  --base "<BASE_BRANCH>" \
  --head "<current branch>" \
  --draft
```

If the command exits with a non-zero status, capture the error and proceed to the GitHub MCP fallback below.

### GitHub fallback: GitHub MCP (only if gh CLI fails)

If `gh pr create` failed, create the PR using the MCP tool:

```
mcp__github__create_pull_request {
  owner: "<OWNER>",
  repo: "<REPO>",
  title: "<PR/MR title>",
  body: "<rendered PR/MR body>",
  head: "<current branch>",
  base: "<BASE_BRANCH>",
  draft: true
}
```

If both GitHub methods fail, report the errors from both attempts, include `BODY_FILE`, and stop.

### GitLab provider: glab CLI

Use this path when `PROVIDER=gitlab`. There is no GitLab MCP fallback in ShipFrame v1.

First verify the local CLI and authentication:

```bash
command -v glab
glab auth status
```

If `glab` is missing or unauthenticated, stop and report:

```text
GitLab MR not created. ShipFrame generated the body at <BODY_FILE>.
Install/authenticate GitLab CLI, then rerun:
  brew install glab
  glab auth login
  glab auth status
```

Create the Draft MR:

```bash
glab mr create \
  --title "<PR/MR title>" \
  --description "$(cat "$BODY_FILE")" \
  --target-branch "<BASE_BRANCH>" \
  --source-branch "<current branch>" \
  --draft \
  --yes
```

If `glab mr create` fails, report the captured error, include `BODY_FILE`, and stop. Do not fall back to GitHub MCP for GitLab remotes.

---

## Step 8 — Report

```
## Pull Request / Merge Request Created (Draft)

Title:    <title>
URL:      <pr_or_mr_url>
Provider: <github|gitlab>
Base:     <BASE_BRANCH> <- <current branch>
Files:    <count> changed
Method:   <gh CLI | GitHub MCP (fallback) | glab CLI>
Body:     <BODY_FILE>
```

Store `PR_URL` or `MR_URL` and the request number/IID in context — downstream skills or agents may need them.

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 of questions (3–5) targeting the scenarios most likely to be forgotten until late in development.

Cover the relevant subset of:

**Edge Cases**
- What happens with empty states? (no data, first-time user, zero results)
- What happens at limits? (maximum load, concurrent users, bulk operations)
- What happens when dependencies fail? (third-party API down, network error, timeout)
- Can this feature conflict with another existing feature? If so, how is it resolved?

**Non-Functional Requirements**
- Are there performance expectations? (response time, throughput, availability SLA)
- Are there security or compliance requirements? (auth, encryption, data residency, GDPR)
- Does this need to work offline or in degraded network conditions?
- Are there accessibility requirements? (screen reader, keyboard navigation, WCAG level)

**Delivery & Rollout**
- Should this be feature-flagged or rolled out gradually?
- Are there dependencies on other teams, migrations, or releases that affect timing?
- Is there a definition of "done" beyond just "it works"? (e.g., monitored, documented, analytics instrumented)

---

## Step 5 — Synthesize & Confirm

After all phases, synthesize everything into a structured feature spec (see format below). Present it to the user and ask:

> "Does this capture everything correctly? Any corrections, additions, or things to remove before I finalize it?"

Incorporate any feedback, then produce the final version.

---

## Feature Spec Format

```
# Feature: <name>

## Summary
<2–3 sentence description of what this feature does and why it exists>

## Problem Statement
<The user/business pain this solves. What happens today without this feature?>

## Target Users
<Who uses this, their role, context, and volume>

## Goals
- <Measurable outcome 1>
- <Measurable outcome 2>

## Out of Scope
- <Explicitly excluded item>
- <Explicitly excluded item>

## Functional Requirements

### <Functional Area 1>
- FR-01: <Specific, testable requirement>
- FR-02: <Specific, testable requirement>

### <Functional Area 2>
- FR-03: ...

## Business Rules
- BR-01: <Rule with condition and outcome>
- BR-02: ...

## Permissions & Roles
| Role | Can do | Cannot do |
|------|--------|-----------|
| <role> | <actions> | <restrictions> |

## Data Model Notes
<Key entities, fields, or state transitions relevant to this feature>

## Integrations & Dependencies
- <System/service and how it's used>

## Non-Functional Requirements
- **Performance:** <e.g., API response < 300ms p95>
- **Security:** <e.g., requires authenticated session, no PII in logs>
- **Accessibility:** <e.g., WCAG 2.2 AA>
- **Availability:** <e.g., must work offline with stale cache>

## Edge Cases & Error Handling
- <Scenario>: <Expected behavior>
- <Scenario>: <Expected behavior>

## Acceptance Criteria
- [ ] <Verifiable criterion>
- [ ] <Verifiable criterion>
- [ ] <Verifiable criterion>

## Open Questions
- <Unresolved item that needs a decision before implementation>

## Notes
<Any additional context, references, or design decisions captured during discovery>
```

Omit sections that are genuinely not applicable. Never leave a section empty — either fill it or remove it.

---

## Step 6 — Create in ClickUp (Optional)

After the spec is confirmed, ask:

> "Would you like me to create this in ClickUp?"

**If the user says yes:**

Hand off to the `create-task` skill to handle classification, template selection, and task creation. Pass the full confirmed feature spec as the input:

```
/create-task --input "<full feature spec markdown>" --type US
```

The `create-task` skill will:
1. Read the `templates/clickup/us_task_template.md` template
2. Fill it out using the feature spec
3. Ask the user to confirm before creating
4. Select the target ClickUp list
5. Create the task and return the URL

After `create-task` completes, capture `TICKET_ID` and `TICKET_URL` from its output and format them as follows so downstream agents can pick them up:

```
✅ ClickUp ticket created

**Name:** <task name>
**ID:** <task id>
**URL:** <task url>

> To generate an execution plan for this ticket, run:
> `/plan-expert --ticket-id <task id>`
```

**If the user says no:** present the final spec as a clean markdown block they can copy, and suggest:
> "You can run `/plan-expert --description \"<feature name>\"` to break this into an execution plan without a ClickUp ticket."

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: OSX, Linux, Windows with WSL2
<!-- List only prerequisites that are genuinely required based on detected stack -->
-   [**<Runtime & version>**](<official-url>)
-   [**<Package manager>**](<official-url>)
-   [**<Database>**](<official-url>)

#### Technical Information

<!-- List only what was detected -->
-   [**<Framework & version>**](<official-url>)
-   [**<Key library>**](<official-url>)
-   [**<Container/infra tool>**](<official-url>)

## 🧑‍💻 Getting Started

1. **Clone** this repository.

```bash
git clone git@github.com:<org>/<repo>.git
```

2. Copy the `.env.example` file to `.env` and set all the necessary environment values.

```bash
cp .env.example .env
```

You can find the credentials in [<credentials-location>](<credentials-url-if-provided>). If you don't have access, please [contact](#-contact) your Project Manager or Tech Lead.

3. Install the dependencies.

<!-- Adapt to the detected package manager and language -->
```bash
<install command>
```

4. <!-- Add any additional required setup steps detected from README or scripts, e.g. key generation, migrations, seed -->

5. Run the development server.

```bash
<dev command>
```

## 🖥️ Useful Commands

| | Command | Action |
| :-- | :----------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
<!-- List only commands that exist in scripts -->
| ⚙️ | `<command>` | <what it does> |

> Commands used in this project are from <tooling>. <!-- Add a relevant cheatsheet link if applicable -->

## 🧠 Contribution

There are some "rules" to follow if you want to contribute to this project.

#### Branch Naming

To start contributing you will need to create a branch from your development branch following these steps:

1. Identify the ticket of your task in [ClickUp](https://app.clickup.com/31625254/home).

2. Once you identify the ticket, note its ID (found in the URL or in the left corner of the modal).

3. Our branch naming convention is based on [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/#summary) followed by the ClickUp task ID:

-   **fix**: patches a bug (correlates with PATCH in Semantic Versioning).
-   **feat**: introduces a new feature (correlates with MINOR in Semantic Versioning).
-   **hotfix**: patches a bug live in PRODUCTION (promote to production ASAP).

Branch name format: `feat/CU-[ClickUp task ID]-[optional-detail]`
Examples: `feat/CU-86aydqtf5-Login` or `feat/CU-86aydqtf6`

#### Descriptive Commits

Make commits referencing the ClickUp ID: `feat/CU-[ID] Task title`

#### Create a PR

Include the following in your Pull Request description:

-   **Explanation of Unrelated Changes:** If there are changes unrelated to the ticket, explain why they were included.
-   **Screenshots:** Attach screenshots of screens that changed to facilitate visual review.
-   **Other tickets affected:** If the changes affect other tickets, list them and leave a comment on those tickets with the PR URL.

> **IMPORTANT:** Never add sensitive information to the repository (passwords, API keys, etc.)

> **REMEMBER:** Keep PRs as small and focused as possible.

## 🚀 Deployment

<!-- Describe the CI/CD pipeline detected or ask the user to fill this in -->
We use CI/CD for deployments. To deploy, merge an approved PR to the correct branch:

-   **`<environment>`** environment → merge PR to `<branch>` branch.

## 📞 Contact

For support or questions, please contact:

Project Manager: <a href="mailto:<pm-email>"><pm-name></a>

Tech Lead: <a href="mailto:<tl-email>"><tl-name></a>
````

---

## Step 4 — Write the file and confirm

Write the completed `README.md` to the project root.

Then report:
- What was auto-detected vs. what the user provided
- Any sections left with `<!-- TODO: fill in -->` placeholders and why
- Reminder not to commit sensitive values

Do not continue or suggest further steps after reporting.

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:

```
## Multi-subtask implementation plan

Parent: <PARENT_TICKET_NAME> (CU-<PARENT_TICKET_ID>)
Base branch: <BASE_BRANCH>
Parent branch: feat/CU-<PARENT_TICKET_ID>-<slug>

Subtasks to implement in order:
1. <subtask 1 name> (CU-<id>)  →  branch from: <PARENT_BRANCH>
2. <subtask 2 name> (CU-<id>)  →  branch from: subtask 1 branch
3. <subtask 3 name> (CU-<id>)  →  branch from: subtask 2 branch
...

Each subtask gets its own branch and PR/MR targeting the previous branch.
```

Ask:
> "Does this order look correct? Confirm to start implementing, or describe what to change."

Wait for confirmation. Once confirmed, iterate through `SUBTASK_LIST` in order. For each subtask:

1. Set `CURRENT_TASK = this subtask`
2. Set `CURRENT_BASE = PREVIOUS_BRANCH` (the branch this subtask will branch from)
3. Execute Steps 2 through 9 for `CURRENT_TASK`, using `CURRENT_BASE` wherever "base branch" is referenced in those steps (branch creation in Step 5 and PR target in Step 9)
4. After the PR is created, update `PREVIOUS_BRANCH = the branch just created for this subtask`
5. Move to the next subtask

Do not start subtask N+1 until subtask N has a committed branch and an open PR/MR.

### Multi-subtask report (replaces Step 10)

After all subtasks are complete, output this summary instead of the single-task report:

```
## Parent Task Implementation Complete

**Parent:** <PARENT_TICKET_NAME> (CU-<PARENT_TICKET_ID>)
**Base branch:** <BASE_BRANCH>
**Parent branch:** feat/CU-<PARENT_TICKET_ID>-<slug>

### Subtasks

| # | Subtask | Branch | PR/MR |
|---|---------|--------|----|
| 1 | <name> | <branch> | <PR/MR URL> |
| 2 | <name> | <branch> | <PR/MR URL> |
| … | … | … | … |

### Merge order
Merge PRs/MRs in the order listed above. Each PR/MR targets the previous branch —
merging out of order will produce incorrect diffs.

### Known gaps or follow-up
<any subtask whose Definition of done could not be fully completed, or "None">
```

Stop after outputting this report. Do not proceed to Step 10.

---

## Step 2 — Load project context

Read the following files if they exist at the project root:

- `AGENTS.md` — stack, framework, conventions, dev commands
- `DESIGN.md` — design tokens, component patterns, variant system

These files are the authority on how to write code for this project. If they do not exist, infer conventions from the codebase in Step 3.

---

## Step 3 — Understand the affected area

Before writing a single line of code, read the existing code in the area the task touches.

Use the **Where** section from the ticket or plan to locate the relevant files. Then:

1. **Glob** for files matching the area (e.g. all files in the target directory or matching the feature name)
2. **Read** each relevant file in full — components, services, routes, tests, types
3. **Grep** for patterns, function names, or imports referenced in the task to trace dependencies
4. Identify:
   - Naming conventions (file names, function names, variable names)
   - How similar features are structured in the existing codebase
   - Shared utilities, hooks, or services that should be reused
   - Test patterns (where tests live, what testing library is used, how test files are named)

Do not skip this step. Implementing without reading leads to convention violations that fail code review.

---

## Step 4 — Build the implementation plan

Produce a file-level plan before writing any code. The plan must list every concrete action needed:

```
## Implementation Plan: <task name>

### New files to create
- `<path/to/file>` — <one-line purpose>

### Files to modify
- `<path/to/file>` — <what changes and why>

### Files to delete
- `<path/to/file>` — <why it is being removed>

### Commands to run
- <e.g. run a migration, generate a type, update a lock file>

### Verification steps
- <lint command from AGENTS.md>
- <type check command>
- <test command targeting affected files>

### Out of scope (will not touch)
- <files or areas explicitly excluded — from the ticket's Out of scope section or plan-expert output>
```

Cross-reference the **Out of scope** section from the ticket or plan — do not implement anything listed there.

Present the plan to the user and ask:
> "Does this implementation plan look correct? Confirm to start, or describe what to change."

Wait for confirmation before proceeding. Do not start writing code until the plan is approved.

---

## Step 5 — Create a feature branch

Derive the branch name from `CURRENT_TASK`:

- Type prefix from the task nature: `feat/`, `fix/`, `refactor/`, `docs/`, `chore/`
- Ticket ID if available: `CU-<id>-`
- Slug from the task name: lowercase, hyphens, max 40 characters

Determine the source branch:
- **Single task** (`MULTI_SUBTASK_MODE = false`): branch from the inferred base branch (`main` / `master` / `develop`)
- **Multi-subtask** (`MULTI_SUBTASK_MODE = true`): branch from `CURRENT_BASE` (set by Step 1b for this iteration)

```bash
git checkout <source branch>
git checkout -b <type>/CU-<id>-<slug>
```

Example (single task): `feat/CU-abc123-add-user-auth-flow` branched from `main`  
Example (subtask 2): `feat/CU-sub2-add-token-service` branched from `feat/CU-sub1-add-auth-endpoint`

If the branch already exists locally, switch to it:
```bash
git checkout <branch>
```

---

## Step 6 — Implement

Execute the plan from Step 4 in order. For each action:

**Creating a file:**
- Follow the naming and structure conventions identified in Step 3
- Reuse existing utilities, components, and patterns — do not reinvent what already exists
- Match the code style of adjacent files exactly (indentation, import order, export style)

**Modifying a file:**
- Read the file again immediately before editing
- Make the minimum change required — do not refactor unrelated code
- Do not alter formatting of untouched lines

**Running commands:**
- Use the commands from `AGENTS.md` (dev commands section) as the authority
- If a command fails, diagnose and fix the root cause before continuing — do not skip

After all files are written, do a final pass:
- Re-read every file you created or modified
- Verify naming conventions, import patterns, and structure match the project
- Confirm the **Acceptance criteria** from the ticket or plan are addressed by the code

---

## Step 7 — Verify

### 7a — Automated checks

Run all applicable verification commands from `AGENTS.md`. At minimum:

```bash
# Lint
<lint command>

# Type check (if typed language)
<type check command>

# Tests targeting affected files
<test command> <affected file pattern>
```

If any command fails:
- Read the error output
- Fix the root cause in the affected file
- Re-run the failing command
- Do not mark 7a complete until all commands pass

### 7b — Code review

Run the full `code-review` skill as defined in its SKILL.md, scoping the review to the current feature branch:

- Pass the feature branch base as the `--base-branch` argument so the review covers only the files changed in this task
- `code-review` will run its Phase 1 (fast checks) and Phase 2 (SOLID / structural audit) on those files

**If `code-review` reports errors or warnings:**
- Apply every fix marked as ❌ Error — these are blocking
- Apply fixes marked as ⚠️ Warning unless they conflict with the task's explicit Out of scope section
- After applying all fixes, re-run the automated checks from 7a to confirm nothing broke
- Do not proceed until `code-review` produces no blocking errors

**If `code-review` reports no issues or only passing items:**
- Proceed to Step 8 immediately

Do not proceed to Step 8 with unresolved code-review errors.

---

## Step 8 — Commit

Stage only the files that are part of this task:

```bash
git add <file1> <file2> ...
```

Do not use `git add .` — it risks including unrelated changes or generated files.

Write the commit message following Conventional Commits:

```
<type>(<scope>): <short imperative description>

<body — bullet points of what was done, one per meaningful change>

Refs: <ticket ID or "n/a">
```

```bash
git commit -m "<message>"
```

If the commit is rejected by a pre-commit hook, fix the issue the hook reports and recommit. Do not use `--no-verify`.

---

## Step 9 — Open the PR/MR

Run the `create-pr` skill as defined in its SKILL.md, passing:
- `--auto` — skip confirmation steps inside `create-pr`
- `--ticket-id <id>` — the current subtask or single task ID
- `--base <branch>` — set explicitly:
  - **Single task**: the inferred base branch (`main` / `master` / `develop`)
  - **Multi-subtask**: `CURRENT_BASE` for this iteration (the previous subtask's branch, or the parent feature branch for subtask 1)

Passing `--base` explicitly prevents `create-pr` from re-inferring the target and ensures each subtask PR/MR targets its correct predecessor branch.

`create-pr` will populate the full PR/MR template from the diff against `--base`, auto-detect GitHub/GitLab from `origin` unless `--provider` is passed, and open the Draft PR/MR automatically. Capture the returned `PR_URL` or `MR_URL`.

---

## Step 10 — Report

```
## Task Implementation Complete

**Task:** <task name>
**Branch:** <branch name>
**PR/MR:** <PR_URL or MR_URL>

### What was implemented
<bullet list — semantics: add | update | fix | refactor | delete>

### Acceptance criteria
<for each criterion: ✅ Met | ⚠️ Partial — <note> | ❌ Not met — <reason>>

### Known gaps or follow-up
<items from Definition of done not yet completed, or "None">
```

---

## Constraints

- Never modify files outside the approved implementation plan without re-confirming with the user.
- Never disable linting, type checking, or test commands to force verification to pass.
- Never commit secrets, credentials, `.env` files, or generated build artifacts.
- Never use `git add .` or `git commit --no-verify`.
- If the task turns out to be significantly larger than estimated after reading the codebase, stop and surface it:
  > "After reading the codebase, this task is larger than the ticket suggests. Here is what I found: <summary>. Should I proceed, split the work, or adjust the scope?"

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 -->

### Database & ORM
<!-- e.g., PostgreSQL via Prisma 5.x -->

### Testing
<!-- e.g., Vitest, Playwright for E2E -->

### Build & Tooling
<!-- e.g., Vite, Turborepo, pnpm workspaces -->

### Deployment
<!-- e.g., Vercel (frontend), Docker (API) -->

## Project Structure
<!-- Brief description of top-level directories and their purpose -->

## Environment Variables
<!-- List .env keys (no values) and what they're for if inferable -->

## Development Commands
<!-- Extract from package.json scripts or README -->
```

### 5. Confirm to the user

After writing `AGENTS.md`, report:
- What stack was detected
- Where the file was written
- Any ambiguities or gaps that could not be determined automatically

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 relevant to this task. Only include areas that actually apply:

- **Backend / API** — endpoints, business logic, data models, migrations
- **Frontend / UI** — components, pages, routing, state management
- **Database** — schema changes, queries, indexes, seeds
- **Authentication / Authorization** — access control, roles, sessions
- **Integrations** — third-party APIs, webhooks, SDKs
- **Testing** — unit, integration, E2E
- **Infrastructure / DevOps** — deployment, env vars, CI/CD
- **Documentation** — README, inline docs, API docs
- **Security** — input validation, secrets, permissions
- **Performance** — caching, pagination, query optimization

### 2.3 Decompose into subtasks

Break the work into sequential subtasks. Each subtask must:
- Have a clear, imperative title starting with a verb (e.g., "Add `POST /auth/login` endpoint", "Write unit tests for TokenService")
- Be independently completable by one engineer
- Be scoped to a single concern — avoid "and" in the title
- Be populated using the **Subtask Template** defined in Step 3

Order subtasks from foundational to dependent (data layer → logic → API → UI → tests → docs).

Aim for 4–10 subtasks for most tasks. If the task is very large, note that it should be split into separate tickets after planning.

Every field in the template is required. If a field genuinely does not apply (e.g., "Out of scope" has nothing notable), write "N/A" — never omit the field.

---

## Step 3 — Output the Plan

> **MANDATORY TEMPLATE RULE**
> Every subtask — without exception — must be written using the template below.
> All 8 sections are required in every subtask, both in this preview and in what gets written to ClickUp or local files.
> If a section has nothing to say, write `N/A`. Never skip, collapse, or summarize a section.

Present the full plan before taking any write actions:

```
## Plan: <task title or goal>

**Goal:** <one-sentence objective — what must be true when this is done>
**Scope:** <comma-separated concern areas from 2.2>
**Subtasks:** <count>

---

### Subtask 1 — <imperative title starting with a verb>

#### Context
<Why this subtask exists and how it fits the overall goal. One or two sentences.>

#### What to implement
<Detailed description of the work — no ambiguity. Use bullet points for multi-part work.>

#### Where
<Specific file paths, modules, or layers involved. If not inferable, write the closest known location.>

#### Acceptance criteria
- [ ] <Specific, testable criterion — written so a reviewer can verify it without asking questions>
- [ ] <Add as many criteria as needed>

#### Out of scope
<Explicitly list what this subtask must NOT do. If nothing notable, write "N/A".>

#### Depends on
<"Subtask N — <title>" for each blocker. If none, write "None".>

#### Technical notes
<Implementation hints, known edge cases, gotchas, or relevant prior art in the codebase. If nothing notable, write "N/A".>

#### Definition of done
- [ ] Implementation satisfies all acceptance criteria above
- [ ] Relevant unit or integration tests written and passing
- [ ] No new lint, type, or build errors introduced
- [ ] Code reviewed and approved by at least one teammate
- [ ] Any new public API or behavior is documented (inline or in relevant docs)

---

### Subtask 2 — <imperative title starting with a verb>

#### Context
<...>

#### What to implement
<...>

#### Where
<...>

#### Acceptance criteria
- [ ] <...>

#### Out of scope
<...>

#### Depends on
<...>

#### Technical notes
<...>

#### Definition of done
- [ ] Implementation satisfies all acceptance criteria above
- [ ] Relevant unit or integration tests written and passing
- [ ] No new lint, type, or build errors introduced
- [ ] Code reviewed and approved by at least one teammate
- [ ] Any new public API or behavior is documented (inline or in relevant docs)

---

(repeat the full template for every subsequent subtask)
```

After presenting the plan, ask:

> "Does this plan look correct? Should I proceed to create the subtasks?"

Wait for user confirmation before proceeding to Step 4.

---

## Step 4 — Write Subtasks

### If `--ticket-id` was provided (Case B or D):

Fetch the parent task's `list` field to get the correct `list_id`. Create each subtask in order (1 → N) using:

```
mcp__clickup__clickup_create_task {
  list_id: "<same list as parent task>",
  name: "<subtask title>",
  description: "<full subtask body using the template from Step 3 — all sections included>",
  parent: "<ticket-id>"
}
```

The `description` field must be the complete rendered template for that subtask exactly as presented in Step 3 — all 8 sections in order: Context, What to implement, Where, Acceptance criteria, Out of scope, Depends on, Technical notes, Definition of done. Do not abbreviate, merge, or omit any section. A task created without all 8 sections is invalid.

After all subtasks are created, report:

```
## Subtasks Created

✅ Subtask 1 — <title> (id: ...)
✅ Subtask 2 — <title> (id: ...)
...

All subtasks have been added to ticket <ticket-id>.
```

### If only `--description` was provided (Case C):

First, create a parent ClickUp task for this work by delegating to the `create-task` skill. Pass the description and let `create-task` classify it and apply the correct template:

```
/create-task --input "<planning description>"
```

`create-task` will:
1. Classify the input into the appropriate task type ([US], [TASK], [IMP], etc.)
2. Fill out the standardized template
3. Ask the user to confirm the ticket
4. Ask which ClickUp list to use
5. Create the parent task and return the task ID and URL

After `create-task` completes, capture `PARENT_TICKET_ID` and `PARENT_TICKET_URL` from its output.

Then create each subtask as a child of the parent task using:

```
mcp__clickup__clickup_create_task {
  list_id: "<same list as parent task>",
  name: "<subtask title>",
  description: "<full subtask body using the template from Step 3 — all sections included>",
  parent: "<PARENT_TICKET_ID>"
}
```

The `description` field must be the complete rendered template for that subtask — all 8 sections in order. Do not abbreviate, merge, or omit any section.

After all subtasks are created, report:

```
## Subtasks Created

✅ Subtask 1 — <title> (id: ...)
✅ Subtask 2 — <title> (id: ...)
...

Parent ticket: <PARENT_TICKET_URL>
All subtasks have been added to the parent ticket.
```

**Fallback (if user declines ClickUp creation in `create-task`):** create local tasks using `TaskCreate` for each subtask and report:

```
## Task List Created (local)

✅ Task 1 — <title>
✅ Task 2 — <title>
...

These tasks are local to this session. To persist them in ClickUp, run `/create-task` to create a ticket, then re-run `/plan-expert --ticket-id <id>`.
```

---

## Constraints

- **Every task written — to ClickUp or locally — must use the mandatory 8-section template defined in Step 3. No exceptions. A task missing any section is incomplete and must not be created.**
- **Never plan work outside the codebase scope established in Step 2.0.** If a task implies work in a layer not present in this repository, flag it with `⚠️ Out of codebase scope:` and exclude it from the generated subtasks. Do not assume any layer exists without verifying it in the actual code.
- Do not invent technical details that cannot be inferred from the input. If a detail is ambiguous, note it explicitly in the subtask description as: `⚠️ Clarify: <question>`.
- Do not create subtasks for work that is already marked as done in the existing ticket subtasks.
- Do not skip the user confirmation step between Step 3 and Step 4.
- If the ticket is in a "done" or "closed" status, warn the user before proceeding: "This ticket appears to be already closed. Do you still want to create subtasks on it?"

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