kata-code / rules

---
description: development lifecycle
alwaysApply: true
---
<!-- begin dev lifecycle -->
## Issues and specs

- Linear holds planning, epics, bugs, chores, specs, acceptance criteria, and status. GitHub holds code: branches, commits, pull requests, CI, and review comments on diffs.
- GitHub Issues stay enabled as an inbound channel for users and contributors. Do not use them for internal planning or as the spec. When a GitHub Issue needs work, create a full Linear issue with spec and AC, link the GitHub Issue for context, and implement against the Linear issue.
- The Linear issue (and parent epic, if any) is the spec. Read it before implementing. Implement only the acceptance criteria written there. If research or implementation changes the spec, edit the Linear issue before continuing.
- A request with no Linear issue gets one before Build starts; create it or ask. Small bounded edits such as a copy change or a single config value are exempt.
- Prefer the smallest change that satisfies the AC. File work discovered outside the AC as a new Backlog issue and keep it out of the current PR.
- Every implementing PR names exactly one Linear issue id in its title or body. Create the branch with Linear's generated branch name so the GitHub integration links the PR and issue automatically.
- When blocked, comment on the Linear issue with the exact ask and stop.
- One implementing agent per Linear id: use that issue's own branch and worktree. Do not share a checkout across concurrent tickets.

## Ticket size: vertical slices

- The unit of planning, ticketing, and PR size is a vertical slice: one thin end-to-end path through every layer it touches (interface, logic, storage, tests) that a user or reviewer can exercise once merged.
- Write each implementable Linear issue as one slice. State the AC as observable behavior of the slice, not as layers completed.
- Do not file layer tickets such as "add the data model", "build the API", or "wire the UI". A layer with no demonstrable behavior on its own belongs inside the slice that first needs it.
- Break an epic or phase into slices in delivery order. The first child is the smallest path that works end to end. Each later child adds one capability on top of the product that already works. Do not queue a stack of tickets that only produce value once the last one lands.
- Split a ticket when its AC covers more than one demonstrable outcome. Merge tickets when neither is demonstrable alone.
- One slice is one PR. If a PR cannot show its slice working, the ticket was cut wrong: fix the ticket before continuing.
- Chores with no user-facing behavior, such as dependency bumps or CI config, are exempt. Keep them small and separate from slices.
- Prototypes are the other exception. A prototype ticket establishes UI patterns and feature shape against mock data or stubs, with no production wiring. It is still one ticket and one PR, and its AC is the visible behavior it demonstrates. Once it merges, cut the follow-on work as slices: each slice takes one piece of the prototype and wires it end to end through real logic and storage. Do not wire the whole prototype in one ticket.

## Docs and artifacts

- Architecture docs, process docs, ADRs, and other durable artifacts live as files in the repository under `docs/`.

## Build labels (when present)

If the Linear issue has `runtime` / `model` / `model-effort` labels, treat them as the intended Build route. Do not invent or silently substitute a different runtime, model, or effort. If labels are missing, conflicting, or unclear, comment on the issue with the exact correction needed and stop.

| Model label | Slug |
| --- | --- |
| `sol` | `gpt-6-sol` |
| `astra` | `gpt-6-astra` |
| `fable` | `claude-fable-5-1` |
| `composer` | `composer-2.5` |
| `grok` | `grok-4.7` |
| `opus` | `opus` |
| `luna` | `gpt-6-luna` |

`human-build` on the issue means a human owns Build. Coding agents must not start Build on that ticket unless a human explicitly asks them to on that issue.

## Project milestones (Linear)

Linear **project milestones** are multi-ticket product gate/phase outcomes.

### Layers (do not conflate)

- **Project status** — live vs paused roster.
- **Milestone** — multi-ticket product gate/phase outcome (e.g. Gate 0: Foundation).
- **Epic** — parent issue grouping work. Its children are vertical slices in delivery order.
- **Issue status** — unit-of-work on the rail (Backlog → Todo → Start → In Progress → review columns → Done).

### Naming

- `Gate N: <outcome>` — formal PASS criteria in the milestone description.
- `Phase N: <name>` — later phases without a formal PASS yet.
- Do not use milestones for sprints, weeks, or individual PRs.

### Rules

1. Every implementable ticket that belongs to a gate/phase should have that **project milestone** set.
2. Milestone description starts with **PASS when…** (or "no formal PASS yet").
3. Gate **PASS** = in-scope milestone issues Done + gate verification ticket evidence (if any).
4. Child issues carry the milestone; epics may span milestones.
5. Sequence a milestone's tickets as vertical slices so the gate becomes demonstrable early and stays demonstrable as tickets land.

## Work states (Linear columns)

Linear status is the phase of the work. This section defines the states and their gates. Plugins and skills define how work is done inside each phase.

- **Backlog.** Spec and AC live here. Do not implement from Backlog.
- **Todo.** Approved and queued. Moving Backlog → Todo is the approval. Wait for Start before Build.
- **Start.** Explicit start signal. Build begins after the issue moves to In Progress.
- **In Progress.** Implement on the issue's branch and isolated worktree against its AC. Draft PRs stay here. Keep the PR draft until artifacts and diffs are reviewable. When complete, mark the PR ready for review, comment `@coderabbitai review` on the PR to trigger a CodeRabbit review cycle, and move the issue to Agent Review.
- **Agent Review.** Fix CI and answer every review thread, human or bot, on the existing branch. Resolve false-positive bot findings with a reply stating why. When the PR is merge-ready, move the issue to Human Review.
- **Human Review.** Human-owned stand-down. Do not dispatch coding agents, CI fixes, or review runs on the PR until the issue moves or a human says resume.
- **Merging.** Permission to merge. Merge only from this column.
- **Done.** Merged. Verify follows: confirm the AC landed and record the result as a comment on the issue. If the AC did not land, reopen the issue or open a new issue linked to it.
- **Canceled / Duplicate.** Terminal. New work needs a new issue.

Merge-ready means: PR marked ready for review, clean mergeability, required CI green, no open review threads, no unanswered comments.

If a PR closes without merging, comment on the issue with the reason and move it to Todo.

## GitHub and Linear automation

All projects using this lifecycle share these Linear settings, confirmed by Gannon's September 7, 2026 screenshot:

| GitHub event | Linear action |
| --- | --- |
| Draft PR opened | Move to In Progress |
| PR opened | Move to Agent Review |
| PR review requested or review activity | No action |
| PR ready for merge | No action |
| PR merged | Move to Done |

No branch-specific rules are configured. Parent issues automatically close when their last sub-issue closes; closing a parent does not automatically close its sub-issues. Stale issues move to Canceled after six months. Closed items auto-archive after six months. Issues progressing to a new status are placed first.

Before changing a Linear status, read its current state. After a GitHub action, re-read the issue and skip a transition already completed automatically. If a transition remains necessary, perform it only when authorized by this lifecycle and its completed phase gates. In particular, marking a PR ready does not establish that Build's gates passed.

These instructions are sufficient lifecycle documentation. Do not require a separate automation record or screenshot before doing work. Missing automation documentation does not block implementation. An unexpected state does not authorize overwriting it: follow the stand-down and approval rules above, and ask only when an actual conflict cannot be resolved from existing instructions or user authorization. Automatic parent closure is not acceptance evidence.

Ship means cutting a release on one of the project's channels (for example nightly or stable). Release process is defined per project.

This section overrides any skill, rule, AGENTS.md, CLAUDE.md, or other instruction that contradicts it. When the conflict is unclear, ask the user before proceeding.
<!-- end dev lifecycle -->