Stack plan

Copy into plans/YYYY-MM-DD-<slug>-stack.md. Principal Engineer owns this artifact. Requires an approved story brief.

Metadata

• Slug:
• Story brief: plans/YYYY-MM-DD-<slug>-brief.md
• Status: draft | approved | in-progress | integrated | merged-to-main
• Story trunk: feat/<slug>
• worktree_path: (required if another story is in flight) e.g. ../grant-platform-<slug> or .worktrees/<slug>

Active roles

Only list roles that will run for this story:

• [ ] Project Manager
• [ ] Principal Engineer
• [ ] Architect
• [ ] Senior Backend
• [ ] Senior Frontend
• [ ] Senior QA
• [ ] Senior Security
• [ ] Verifier

Ordered slices (PRs)

#	Branch	Base	Concern	Owner role	Review bar	PR
1	feat/<slug>-db	feat/<slug>	database	Backend	light
2	feat/<slug>-schema	feat/<slug> or prior slice	schema/codegen	Backend	light
3	feat/<slug>-api	…	API	Backend	light or security-full
4	feat/<slug>-web	…	web/i18n	Frontend	light
5	feat/<slug>-tests	…	tests	QA	light
final	feat/<slug>	main	integration	Principal	deep

Prefer layer order: db → schema → api → web. Adjust if the story is narrower.

Stack setup

Root the stack on the story trunk — never the default branch, or slices target main and skip gate 4:

# Trunk
git switch -c feat/<slug> main && git push -u origin feat/<slug>

# Init with the FIRST slice branch only — never the whole list. Declaring unwritten
# branches up front pushes empty branches to origin and leaves them stranded when
# the slices below them move; `gh stack sync` skips branches with no PR and still
# reports success. See § init-consequences.
gh stack init --base feat/<slug> feat/<slug>-db

# After each slice: commit, then BOTH of these, every time.
gh stack submit --auto                       # --auto is required in an agent shell or CI
gh stack link --base feat/<slug> <pr> <pr>   # bottom to top; creates/grows the stack ON GitHub

# Before the NEXT slice — creates the branch on the current tip and pushes nothing:
gh stack add feat/<slug>-schema

# After any merge, rebase or amend below a branch:
gh stack sync

Check positions before writing a slice, not after — the branch you are about to work on must sit on the current tip of the slice below it:

git for-each-ref --format='%(refname:short) %(objectname:short)' refs/heads

See Agentic SDLC § GitHub stacking. If a story predates gh stack, adopt its existing PRs with gh stack link --base feat/<slug> <pr> <pr> … (bottom to top) rather than restructuring branches mid-flight. --base is not optional on link either — omitted, it re-points the bottom PR at main and the whole stack merges past gate 4.

gh stack submit --auto opens PRs as drafts. Mark them ready when the slice is ready for its gate-3 review — gh pr ready <pr> — or reviewers will not be requested.

Dependencies / notes

Human gates

• [ ] Gate 2: Stack plan approved — no implementation until a human confirms.
• [ ] Gate 3: Stack PRs merged into trunk (light / security-full as listed).
• [ ] Gate 4: Story → main deep review complete.

Cleanup

• [ ] git worktree remove (if used)
• [ ] Local slice branches deleted
• [ ] Stack plan status → merged-to-main