| name | sdlc |
| description | How to do multi-step engineering work in this repo: parent agents plan and stack PRs with official GitHub Stacked PRs (`gh stack` / `gs`); subagents implement layers with incremental check-ins; parent closes every PR bottom-up with rubber-duck adversarial review, comment resolution, CI repair, and squash-merge. Also covers Scalar enlistments, sparse-checkout, worktrees/workspaces for humans and agents, and autotrain iteration delivery (incremental commits always; stacked PR only after positive-result training runs; full bottom-up closeout when training stops). Use for multi-phase tasks, stacked PR workflows, PR closeout, workspace setup, scalar/sparse checkout, autotrain/code-fix delivery during training, or whenever work spans more than one reviewable layer.
|
SDLC — how work ships in this repo
Required for multi-step / multi-phase / multi-task work. Single-file
hotfixes may stay one PR; everything larger uses this skill.
Activation is automatic. Load and follow this skill whenever you are
implementing engineering work that is meant to land in the repo — not only
when the user types sdlc. Creating the skill, fixing delivery process, or
being told to “check in / push / land / ship” still runs the full
lifecycle below.
Canonical laws still win: AGENTS.md,
docs/repository-organization.md,
and the other skills in this directory. This skill is the delivery process
layer on top of those laws.
Load references on demand:
Roles
| Role | Owns | Must not |
|---|
| Parent agent | Plan layers, open/maintain the stack or PR, spawn subagents, integrate mid-stack fixes, bottom-up closeout through squash-merge | Implement every layer itself when a subagent can; stop at push; ask the user whether to open/review/merge |
| Subagent | One stack layer (or one vertical slice), incremental commits, local checks for that layer | Open competing stacks; rewrite lower layers without parent coordination; skip check-ins |
| Human | Intent, merge policy exceptions, billing budget calls | Required as a rubber stamp for every commit, PR open, or CI fix — agents open PRs, fix CI, and closeout themselves |
Non-negotiable process rules
-
Subagents by default. Multi-file, multi-phase, or multi-concern work is
decomposed. Parent plans; subagents execute. Parent integrates.
-
Incremental check-ins. Subagents commit as soon as a coherent unit is
green locally — not one giant end-of-task commit. Prefer small, reviewable
commits on the layer branch.
-
Stacked PRs for multi-layer work. Parent uses official
gh stack (gs alias). One logical concern per
layer. Dependency order: foundations at the bottom, dependents above.
Single-concern work still opens one PR and still runs closeout.
-
Parent owns the full lifecycle: plan → implement/check-in → open or
update PRs (gh stack submit --open or gh pr create) → mid-stack fixes
with rebase/push → closeout through squash-merge.
Push is not done. A branch on the remote without an open PR (or with an
open PR and no closeout) is incomplete work.
-
Never ask permission for required delivery steps. Do not say
“want me to open a PR?”, “shall I create a PR?”, “let me know if you want
me to merge”, or similar. User shorthand maps to the full lifecycle:
| User says (examples) | Agent does |
|---|
| check in / commit / push | commit, push, open/update PR, start closeout |
| land it / ship it / get this in | full lifecycle through squash-merge |
| open a PR | open PR and run closeout (review → CI → merge) |
| draft only / do not merge / PR only no merge | open draft or ready PR; stop before merge; still fix CI |
Only an explicit human stop (“don’t merge”, “draft only”, “wait for
me”) pauses merge. Silence after push is not a stop.
-
Closeout is mandatory and bottom-up. For every PR the parent
opened, before the task is done:
- Review that PR (and its diff vs its base) in rubber-duck + adversarial
mode — see .
Post the duck notes on the PR (comment), not only in chat.
Decision: one PR vs stack
| Shape of work | Delivery |
|---|
| One concern, ≤ ~reviewable size, single owner | One branch + one PR is fine |
| 2+ sequential concerns, phases, or independent review units | Stack — one layer per concern |
| Parallel independent efforts | Separate stacks (or separate PRs), not one tangled stack |
| Experiment / matrix run | Follow running-experiment-matrices / documenting-experiment-results; stack the code changes, not the raw outputs/ |
| Autotrain continuous or multi-run training | During training: incremental commits always; stacked PR only after positive-result runs; get latest / resolve conflicts every cycle. When training stops: full bottom-up closeout of open (positive) layers. See references/autotrain-iteration-delivery.md |
Autotrain (training-active vs training-stopped)
autotrain is not exempt from SDLC. It uses a two-phase delivery rule:
| Phase | When | Delivery |
|---|
| A — training active | Continuous loop or multi-run finite train | Incremental commits while fixing code for an iteration; document every run; open/update a stacked PR layer only when the run is positive (primary-metric win, ship-quality win, or proven executable unblock — see autotrain-iteration-delivery). Non-positive cycles stay local commits + docs only. Always fetch/merge latest before the next run. Do not default to full-stack squash-merge mid-loop. |
| B — training stopped | User stop, hard block, or loop end | Full existing closeout bottom → top (references/closeout-review.md) for open positive layers: rubber-duck + adversarial review, comments, CI, squash-merge, gh stack sync |
Local-only still means: no paid GPU / HF write without authority, and never PR
raw outputs/ blobs. It does not mean "never open stacked PRs after real
wins." Fixture fails and null deltas do not earn a stack layer. Full
procedure:
references/autotrain-iteration-delivery.md.
autotrain must load and follow that reference; this skill owns the process.
Parent agent playbook
1. Clarify goal + acceptance (what "done" means = merged unless human said stop).
2. Plan layers bottom→top (story a reviewer can read in order).
3. Prepare workspace (worktree preferred; Scalar/sparse as needed).
4. gh stack init <bottom-layer> # or one feature branch for single-PR work
5. For each layer:
a. Spawn a subagent with: layer goal, base branch, allowed paths,
check-in cadence, local test commands, "do not touch lower layers".
b. Subagent implements + incremental commits on that branch.
c. Parent spot-checks; if mid-stack fix needed, parent (or a subagent)
commits on the correct lower layer, then gh stack rebase --upstack
and gh stack push.
d. gh stack add <next-layer> when starting the next concern.
6. Immediately open/update reviewable PRs — do not wait for the user:
gh stack submit --open
# single PR: gh pr create (or gh pr edit if already open)
7. Closeout (required, no ask): follow references/closeout-review.md bottom→top
— rubber-duck comment on each PR, fix CI, squash-merge each opened PR.
8. gh stack sync --prune after merges; report final PR URLs + merge SHAs.
After the last intended commit: open/update the PR in the same turn
as the push. After PRs exist: start closeout in the same session —
do not end with “branch pushed; say if you want a PR.”
Planning layers (reviewer story)
Typical order (adapt to the change):
main
└── 01-contract-or-types
└── 02-implementation
└── 03-tests-harness
└── 04-docs-model-card # if checkpoint/docs required
One concern per layer. If a layer grows large, split with gh stack modify
or fold with d/u — do not ship a kitchen-sink PR "because the stack exists."
Spawning subagents
Give each subagent a closed brief:
- Goal for this layer only and out-of-scope list
- Branch name / stack position (bottom = 1)
- Paths they may edit; paths they must not
- Required local checks (
python -m scripts.repo_policy, targeted tests via
.githooks/check-changed patterns, etc.)
- Check-in rule: commit after each coherent green unit; push when asked or
after each check-in if the layer is already submitted
- Skills that apply (e.g.
ponytail, organize-repository,
dashboard-openui-parity, honest-ship-eval)
- Instruction: do not open a second stack; do not rewrite history of
lower layers without parent approval
Parent re-reads subagent output, runs or assigns verification, and only then
advances the stack.
Incremental check-ins (subagent)
- Commit early and often on the layer branch.
- Message: why, not noise (
caveman-commit optional).
- After push to an open PR: paste a short status (what landed, what remains,
risks) so the parent can replan without re-deriving state.
- Never accumulate a day of uncommitted work "for a clean history" — history
is cleaned by layer boundaries and squash-merge, not by silent WIP.
Tooling prerequisites
gh extension install github/gh-stack
gh extension upgrade github/gh-stack
gh stack alias
gh auth status
scalar register /path/to/slm-training
scalar list
Docs: gh-stack ·
CLI reference ·
man scalar / git sparse-checkout.
Prefer gs when the alias is on PATH; otherwise gh stack. Non-interactive
automation: gh stack submit --auto, gh stack merge --yes --squash,
gh stack sync --prune.
Workspace model (summary)
Full detail: references/scalar-sparse-workspaces.md.
| Mechanism | Use for |
|---|
| Scalar register | Background maintenance (commit-graph, multi-pack, prefetch), large-repo Git defaults on the enlistment |
| Scalar clone | New machines: partial clone + sparse by default (or --full-clone when you need everything) |
| Sparse-checkout (cone) | Restrict a worktree to the paths a human/agent needs for one task |
| Git worktrees | Parallel agents/layers without stashing; one worktree per active stack or long-running agent |
| Agent isolation worktrees | Subagent isolation when the harness supports it; still one stack owned by the parent |
Do not enable sparse-checkout on a shared multi-agent worktree without
coordinating — other agents may need paths you cone out. Prefer a dedicated
worktree per task with its own sparse cone.
Closeout gate (parent cannot skip)
Before reporting the task complete:
FOR each PR opened by this parent (bottom → top):
[ ] Rubber-duck walkthrough of the PR diff (explain aloud / in notes)
[ ] Adversarial pass (invariants, leakage, gate weakening, size growth, …)
[ ] All review comments resolved or answered with code/docs
[ ] All relevant status checks green OR documented billing-budget block
[ ] Squash-merged (gh stack merge --yes --squash for a ready prefix,
or per-PR squash when landing partially)
[ ] Higher layers rebased/synced after lower merges (gh stack sync)
If closeout is blocked (human review required by policy, budget, or secrets),
state the block explicitly — open PRs without a closeout plan are incomplete
work, same class of failure as missing experiment docs.
Interaction with other skills
| Concern | Skill |
|---|
| Minimal implementation | ponytail |
| Path placement / moves | organize-repository |
| Experiment / eval / matrix runs | documenting-experiment-results, honest-ship-eval, running-experiment-matrices |
| Continuous / multi-run training delivery | autotrain + this skill's autotrain-iteration-delivery.md |
| Data builds | synthesis-feedback |
| Dashboard page edits | dashboard-openui-parity |
| Verbose shell | rtk |
| Large tool output | headroom |
Red flags
| Smell | Fix |
|---|
| Parent implements a 5-phase epic alone | Decompose; spawn subagents; stack |
| One mega-PR "to save time" | Split with gh stack; reviewer time is the bottleneck |
| Subagent never commits until the end | Enforce incremental check-ins |
| Fix for layer 1 committed on layer 3 | gh stack down, fix on the right layer, rebase --upstack |
| Stack submitted then abandoned | Closeout is part of the task |
| Pushed branch, no PR; agent asks "want a PR?" | Open the PR immediately; start closeout — never ask |
| Agent stops after push/PR open and waits | Continue review → CI → squash-merge unless human said stop |
| Status checks red, merged anyway | Only billing-budget exceed may pause; do not merge red otherwise |
| Merge commits / non-squash land | Use --squash for this repo's agent-landed stacks |
| Sparse-checkout on shared worktree blanks another agent | Separate worktree + cone per task |
| Skills only installed for one harness | Canonical copy under .agents/skills/sdlc + discovery symlinks |
| Autotrain runs for hours with uncommitted harness fixes | Phase A incremental commits every cycle |
| Stacked PR for every fixture-fail / null cycle | Stack only after positive results |
| Training stopped and agent only pastes a resume recipe | Phase B bottom-up closeout of open positive layers is mandatory |
Done means
- Every planned layer has an opened PR that is squash-merged or explicitly
dropped/closed with reason (human “don’t merge” counts as a documented stop)
- Rubber-duck + adversarial review posted and acted on for each PR
- Relevant status checks green (or documented billing-budget block)
- Stack synced/pruned locally
- Required docs / model card / version stamps from other skills are done
- Parent reported merged PR URLs + merge SHAs + residual risks — not just
a branch name or “ready when you are”
