vertical-slices

---
name: vertical-slices
description: Design, implement, and review software using vertical slices (feature-first architecture) instead of horizontal layers. Use when creating a new feature, refactoring layered code (controllers/services/repositories), defining clear API-domain-data boundaries, improving slice-level testability, or reducing cross-module coupling in backend or fullstack TypeScript projects.
---

# Vertical Slices

Build features as independent slices that own contract, business rules, persistence logic, and tests.

Prefer feature-first folders and thin entrypoints. Keep business behavior inside the slice, not in transport or framework code.

Always follow stricter repository rules when present (for example `AGENTS.md`).

## Outcomes

A slice is complete only when all are true:

- One clear capability is owned by one slice.
- Behavior is implemented in the slice, not in handlers/controllers/routes.
- Persistence logic is co-located and transaction-safe.
- Tests cover behavior, boundaries, and failure paths with regression depth.
- Cross-slice coupling is explicit, minimal, and one-way.

If these are not met, do not call the slice done.

## Execution Workflow (Required)

### 1) Define the slice boundary before coding

- Name exactly one capability in business language.
- Define one owner module (for example `billing`, `session`, `question`).
- State what is intentionally out of scope for this slice.
- Limit dependencies to shared infrastructure and explicit contracts.

### 2) Write a compact Slice Design Spec before implementation

Create a short design note in your working context with:

- Capability statement: one sentence with actor + action + outcome.
- Invariants: 3-7 rules that must remain true.
- Boundary contracts: input, output, error model, idempotency behavior.
- Data ownership: tables/entities read and written by the slice.
- Dependency map: entrypoint -> slice -> infrastructure only.
- Cross-slice touchpoints: event names or explicit interfaces only.
- Failure model: validation, conflict, upstream, and persistence failures.

If this spec is missing, pause and define it first.

### 3) Define contracts before behavior

- Create input/output schemas at the boundary (HTTP, queue, CLI, RPC).
- Use the same contract definitions in adapters and tests.
- Keep contract definitions in the slice area, not spread across global folders.
- Map internal errors to boundary errors in one place.

### 4) Implement business behavior in the slice

- Keep handlers/routes thin: validate -> invoke slice -> map result/error.
- Keep orchestration and rules in slice functions.
- Avoid leaking framework request/response objects into business logic.
- Prefer explicit return types at public slice boundaries.

### 5) Co-locate persistence and side effects

- Keep slice-specific reads/writes near slice behavior.
- Use explicit transaction boundaries for multi-write flows.
- Emit side effects only after successful commit.
- Make idempotency explicit when retries can happen.

### 6) Enforce low coupling

- Use event publication for asynchronous cross-slice reactions.
- Use explicit interfaces only when immediate response is required.
- Do not deep-import another slice internals.
- Keep dependency direction one-way: entrypoint -> slice -> infrastructure.

### 7) Apply test maturity gates (required)

Do not stop at export/smoke tests. Build behavior-focused suites:

- Unit-level slice tests:
  - happy path with realistic data
  - validation failures
  - domain invariant failures
  - edge cases for optional/empty/limit inputs
- Boundary integration tests when behavior crosses boundaries:
  - transport + contract validation + error mapping
  - persistence side effects and rollback behavior
  - idempotency and duplicate request handling when relevant
- Regression tests:
  - every bug fix must add at least one failing-then-passing test
  - test must assert behavior outcome, not implementation details

### 8) Run final quality gate before completion

- Execute `references/checklist.md` fully.
- Discover verification commands from the host repository before running tests:
  - inspect package/workspace scripts for unit/integration/e2e commands
  - inspect CI workflows to identify required checks for affected paths
  - do not assume script names; infer by behavior
- Run concrete verification commands for the touched slice paths:
  - smallest relevant unit command(s)
  - integration command(s) when boundaries/persistence changed
  - e2e command(s) when user-visible workflows changed
- Prefer package/service-local commands first. Do not use repository root tests when the repo uses a root test guard.
- Keep verification aligned with required CI checks for the affected area.
- Record exact commands executed, pass/fail outcome, and intentional skips with residual risk.
- Record residual risks and follow-ups.
- Call out compatibility or migration impact.

## Choose a Blueprint

Read `references/blueprints.md` to pick folder templates for backend-only and fullstack repositories.

## Apply Naming Conventions

Read `references/naming.md` and pick canonical package and slice names before creating folders and contracts.

## Validate Slice Quality

Read `references/checklist.md` and execute the checks before finalizing changes. Do not mark complete if any required check fails.

## Build Mature Test Suites

Read `references/testing-maturity.md` when designing tests. Use it to choose test depth, avoid shallow suites, and ensure regressions are captured.

## Refactor Toward Slices

If starting from layered architecture, read `references/adoption-playbook.md` and migrate one feature at a time.