Introduction

AI drafts the user stories, turns them into issues, and implements each issue as a slice of code. The developer stops writing every line and becomes an orchestrator: they define what gets built, validate what the AI produces at each step, and decide what gets merged. The key is that a story, an issue, a slice, and a PR are the same unit of work, sized just right for an agent to solve it well.

Most projects are organized by technical layers: Controllers/, Services/, Repositories/, DTOs/ (a DTO, Data Transfer Object, is an object that only carries data between parts of the system, with no logic). With that structure, any change forces the agent to read and touch four or five folders full of code unrelated to the task.

VSA organizes code by use case. The agent receives a bounded task, works in a single folder, and delivers a change the orchestrator reviews in minutes.

What VSA is

Slice of cake with four labeled layers: form, endpoint, handler, and table

Hence the name: if the system is a layer cake, a feature is not an entire layer but a vertical slice that carries a bit of each one.

Four technical layers by four features; the "enroll student" slice cuts through all four layers Create student Enroll student List courses Edit course Frontend Backend / API Controller Database form endpoint handler table 1 issue · 1 PR Layer = horizontal cut Slice = vertical cut, screen → database
Each row is a technical layer; each column, a feature. A slice takes a bit of every layer, but only what that feature needs.

A vertical slice is a complete use case with everything it needs: endpoint, validation, business logic, data access, DTOs, and tests. Jimmy Bogard, who popularized the approach, sums it up in one principle: minimize coupling between slices and maximize coupling within each slice (source).

The difference shows in the folder structure:

Layered structure versus sliced structure: the "enroll student" use case spread across four folders or gathered in one By layers 4 folders to read By slices (VSA) 1 folder to read Controllers/ StudentsController EnrollmentsController Services/ StudentService EnrollmentService Repositories/ StudentRepository EnrollmentRepository DTOs/ StudentDto EnrollmentRequest Shared/ domain · authentication · database connection Features/ Students/CreateStudent/ request · handler · test_create_student reference Enrollments/EnrollStudent/ request response handler test_enroll the whole use case in one folder Shared/ domain · authentication · database connection
Everything highlighted is the code for the "enroll student" use case: spread across four folders on the left, in a single one on the right. For an agent, the right side means reading one folder instead of four.

Three rules the agent must follow, and that are worth writing down in the repository:

  1. One slice = one use case. A command (“enroll student”) or a query (“list students”), in the style of CQRS (Command Query Responsibility Segregation: separating the operations that modify data, the commands, from those that only read it, the queries).
  2. Slices do not import each other. What is truly shared (domain entities, authentication, database connection) goes in Shared/.
  3. Duplication is acceptable. Two slices may have similar DTOs. That is preferable to a shared DTO that, when changed for one case, breaks another.

Preparing the repository to work with AI

Before assigning the first issue to an agent, the repository has to spell out the rules the agent cannot guess. With VSA, code is organized by convention alone, so that convention has to be written down and verified automatically.

  • An AGENTS.md file at the root with the slice conventions (or whichever instructions file the agent reads).
  • A complete reference slice for the agent to copy.
  • The issue template in the repo (for example, .github/ISSUE_TEMPLATE/slice.md), for the AI to fill in.
  • Architecture tests, generated by the AI, that fail if one slice imports another.
  • CI that runs the tests and the architecture tests on every PR.
  • AI test review: a second agent checks that the tests cover every criterion in the issue before implementation; the orchestrator resolves only what that agent flags.
  • Periodic review of Shared/: when the AI repeats the same thing across several slices, it gets extracted.

Example AGENTS.md:

# Conventions
- Each use case lives in Features/<Module>/<Verb><Noun>/
- Files in a slice: request, response, handler, and tests, using the
  project's language extension
- Slices do not import each other. Shared code goes in Shared/.
- Reference slice: Features/Students/CreateStudent/
- One PR = one issue = one slice.
- Write the tests before the code, one per acceptance criterion.
- Issue titles are use-case verbs, never layers.

Stories, issues, and slices: the same unit

A good user story is already vertical: it describes an outcome the user gets, not a technical layer. With VSA, that unit passes intact through the whole process, and at each level the AI produces the artifact and the orchestrator validates it.

LevelExampleWhat the AI doesWhat the orchestrator validates
User storyAs a teacher, I want to enroll a student in a course so they can access the classroom.Drafts it from notes, requests, or the current systemThat it reflects the real need; the priority
Issue#42 Enroll student in courseDerives it from the story, with criteria, folder, and reference sliceThat it is a vertical slice and not a layer
TestsOne test per acceptance criterionWrites them before the code; a second agent checks they cover the criteriaOnly what the reviewing agent flags
SliceFeatures/Enrollments/EnrollStudent/Implements it by copying the reference sliceCI does it with architecture tests
PRfeature/42-enroll-student, a single folderOpens it and fixes it based on commentsThe final review and the merge
The same unit of work passes through story, issue, tests, slice, and PR; at each step the AI produces and the orchestrator validates THE AI PRODUCES drafts it derives it writes them first implements it opens and fixes it Story the user's need Issue #42 Enroll student Tests one per criterion Slice a single folder PR feature/42-… reflects the need and the priority is it a vertical slice? only what the reviewing agent flags CI with architecture tests final review and merge THE ORCHESTRATOR VALIDATES
A single unit of work crosses all five levels. Above, what the AI produces at each one; below, what the orchestrator validates before letting it move to the next.

The most common AI mistake when generating issues is slicing by layer: “create enrollments table”, “create endpoint”, “create screen”. None of them delivers value on its own, and none can be tested end to end. When that happens, reject the split and ask it to redo it by use case: a closed issue has to be a working feature.

Option A: user stories + issues

This fits when there are business users and a product with several features to prioritize. The story lives at a higher level (epic, milestone, or label) and each issue is a slice of that story.

Flow with AI:

  1. The AI drafts the stories from the need, meeting notes, or the description of the current system.

    Prompt: “From these notes, propose user stories for the enrollment module, in the As a / I want / so that format.”

  2. The orchestrator prioritizes and approves the stories.
  3. The AI turns each story into issues, one per slice, filling in the repository template.

    Prompt: “Turn story #12 into issues. Each issue must be a vertical slice, with acceptance criteria, a folder under Features/, and a reference slice. Use the template in AGENTS.md.”

  4. The orchestrator reviews the split (see How to validate the split the AI proposes) and only then assigns the issues to the agent.

Issue template the AI fills in:

## #42 Enroll student in course
Story: #12 Enrollment management
As a teacher, I want to enroll a student in a course so they can access the classroom.

### Acceptance criteria
- [ ] Student already enrolled → 409 error
- [ ] Course has no seats left → 422 error
- [ ] Successful enrollment → 201 and appears in the course roster

### Slice
Features/Enrollments/EnrollStudent/

### Reference
Features/Students/CreateStudent/

### Do not touch
Other slices. Changes to Shared/ must be flagged in the PR.

Option B: issues only

This fits small teams, internal systems, or migrations, where the story format adds ceremony without adding clarity. The AI drafts the issue directly from a short request.

Prompt: “Write an issue for ‘enroll student in course’ using the template in AGENTS.md. The goal is for the student to access the course classroom.”

Expected result:

## Enroll student in course
So that: the student can access the course classroom.

- [ ] Already enrolled → 409
- [ ] No seats left → 422
- [ ] OK → 201

Slice: Features/Enrollments/EnrollStudent/
Reference: Features/Students/CreateStudent/

In both options there is one rule worth including in the prompt: the issue title is a verb that a user or system performs (“Enroll student”, “List active courses”), never a layer (“Create course repository”).

Stories + issuesIssues only
Best forProducts with business users and prioritizationSmall teams, internal systems, migrations
Planning promptsTwo: stories, then issuesOne: the issue directly
Orchestrator validationsStories and the split into issuesOnly the split into issues
Unit the agent receivesOne issue = one sliceOne issue = one slice

How to validate the split the AI proposes

The AI proposes how to split the stories; the orchestrator decides. When a story is large, the right split produces thinner stories that are still vertical. This table helps correct the AI when it splits badly:

Instead of splitting by…Split by…
Layer: table, endpoint, screenRule variant: simple enrollment → with waiting list
Component: backend, frontendHappy path first, error cases later
”All of course CRUD”Each operation: create, edit, deactivate, list
Generic infrastructure up frontOnly the infrastructure the first slice needs

Criteria for accepting an AI-generated issue (INVEST):

  • It can be tested end to end, on its own.
  • It touches a single folder under Features/, plus minor changes in Shared/.
  • The PR can be reviewed in one sitting.
  • It has between two and six acceptance criteria. More than that usually means it is two slices.

One reasonable exception: the project’s technical foundation (authentication, database connection, CI) is built once, horizontally, before the first slice.

The same AI can do a first review of the split before the orchestrator:

Prompt: “Review these issues. Flag any that touches more than one folder under Features/, is named after a layer, or has more than six criteria, and propose how to split it into vertical slices.”

Implementing each issue with an agent

Once the issue is approved, the agent implements it. The issue is the prompt: it says what to do, where to do it, what not to touch, and when it is done.

  1. Assign the issue. The prompt is short because the issue already has everything: “Implement issue #42 following AGENTS.md.”
  2. Tests first. The agent turns each acceptance criterion into a test inside the slice folder. A second agent checks that the tests cover what the issue asks for before moving on; the orchestrator resolves whatever that agent flags.
  3. Implementation. The agent copies the structure of the reference slice and writes code until the tests pass.
  4. CI. The tests and the architecture tests run. If they fail, the agent fixes and tries again.
  5. Orchestrator review. The PR touches a single folder and is reviewed quickly. Changes are requested with a PR comment and the agent applies them.
  6. Merge and close. The PR closes the issue (Closes #42).

Because slices are independent, several issues can be assigned to several agents in parallel without merge conflicts.

Flow of one issue: criteria become tests, the agent implements, CI and the orchestrator's review send the work back to the agent until the merge is approved Approved issue Criteria → tests Agent implements CI passes? fails: back to the agent passes Orchestrator reviews requests changes approves Merge, closes #42 correction loops: the work goes back to the agent
Two loops back to the agent: CI when the tests fail, and the orchestrator when it requests changes. The agent does not decide when it is done.

The two loops back to the agent (CI and review) are what keep quality up: the agent does not decide when it is done.

How to implement it: mattpocock/skills

To avoid building everything from scratch, the process can be set up on top of mattpocock/skills, an open collection (MIT license) that works with Claude Code, Codex, Copilot, Gemini CLI, Cursor, and other agents.

1. Install

One method per agent: installing both the plugin and the files duplicates the skills.

AgentCommand
Claude Codeclaude plugin install mattpocock-skills@claude-plugins-official
Codexcodex plugin marketplace add mattpocock/skills, then codex plugin add mattpocock-skills@mattpocock
GitHub Copilot (CLI and VS Code)copilot plugin marketplace add mattpocock/skills, then copilot plugin install mattpocock-skills@mattpocock
Gemini CLIgemini skills install https://github.com/mattpocock/skills.git --path skills/engineering
Others (Cursor, OpenCode, Windsurf…)npx skills@latest add mattpocock/skills -a <agent>, including setup-matt-pocock-skills when it asks which skills to install

2. Configure the repository (once)

Run /setup-matt-pocock-skills. It asks which issue tracker to use (GitHub, GitLab, local files, or other), which labels are used to classify issues, and where to store documentation. Then add the AGENTS.md with the slice conventions from the Preparing the repository section.

3. Align with the AI: /grill-with-docs

The AI interviews the orchestrator, one question at a time, until every decision is explicit. Along the way it maintains a domain glossary (GLOSSARY.md) and records architecture decisions (ADRs). This is the stage where the user stories are born.

4. Write the specification: /to-spec

Turns the conversation into a specification and publishes it to the issue tracker. It plays the role of the user story or the epic.

5. Split into vertical issues: /to-tickets

This is the central step. It runs on the specification, for example /to-tickets #12, and:

  1. Reads the specification and explores the code; if it helps, it proposes a preparatory refactor to make the work easier.
  2. Splits the work into tracer bullet tickets: each one cuts through every layer, can be verified on its own, and fits in a fresh context window.
  3. Marks the dependencies: which ticket blocks which.
  4. Shows the list to the orchestrator and asks whether the granularity is right, whether the dependencies are real, and whether tickets should be merged or split. It iterates until the orchestrator approves.
  5. Publishes one issue per ticket, with acceptance criteria and the ready-for-agent label (or one file per ticket under .scratch/<feature>/issues/ if local files were chosen).

Step 4 is the validation of the split. To reinforce it, before approving you can run the control prompt from How to validate the split over the list. One detail: /to-tickets avoids putting file paths in issues because they go stale, so the folder for each slice is defined by the AGENTS.md convention, not by the issue.

6. Implement: /implement or /implement-spec

  • /implement takes the tickets, works with /tdd (first a failing test, then the code that makes it pass), runs the tests, and closes with /code-review. That review uses parallel subagents that check two things separately: whether the code follows the repo’s standards and whether it faithfully implements the issue. It is the reviewing agent this article describes.
  • /implement-spec works through a complete specification: it launches several subagents in parallel on the tickets that have no blockers.

Every few days it is worth running /improve-codebase-architecture, which looks for where the structure is degrading and proposes improvements.

Mapping to the process

Stage in this articleSkill
Prepare the repository/setup-matt-pocock-skills + your own AGENTS.md
Draft stories/grill-with-docs + /to-spec
Turn stories into vertical issues/to-tickets
Validate the split/to-tickets questions + control prompt
Tests first/tdd
Implement the slice/implement
Reviewing agent/code-review
Several slices in parallel/implement-spec