Feature Lifecycle

Feature lifecycle

The mechanics for running a Tier 1 or Tier 2 feature, once the tier is picked per AGENTS.md's Workflow section. See story-lifecycle for what a single story does inside its own worktree; this skill covers the layer above it — feature level, parallelism across stories, integration, and the retrospective.

Feature level — main session, main checkout

1. analyst → analysis, task list, dependency graph. If its report starts with NEEDS-INPUT, put its questions to the user with AskUserQuestion: state the problem, the options with their consequences, and the recommendation. Send the answers back to the same agent and let it finish.
2. story-writer → one story file per story. No file, function or endpoint names in a story.
3. project-manager → one blueprint per story, with every contact point frozen and the exact start command the validator will run. At most six engineer tasks per story. Every task is a fresh agent that reads the repository, the blueprint and the conventions from nothing, so a seventh task costs more in re-read context than the split saves in focus. Measured: one story split into twelve tasks spent 57M input tokens on its engineers alone, 15% of an eighteen-story feature. If a story genuinely needs more than six, it is more than one story and belongs back with the story-writer.
4. Show and launch in the same response. Story list plus dependency graph, then start. No "shall I proceed".

Story level — one teammate per story, one worktree per story

Each story runs the story-lifecycle skill in its own worktree, branch story/<feature>/<story-id>, its own ports, its own ROUTERLY_HOME:

node .Codex/scripts/story.mjs claim <story-id> --feature <feature> --base 0.4.0

5. orchestrator freezes the interface, then dispatches backend-engineer and frontend-engineer in parallel where the blueprint says they are independent.
6. validator starts the app on the story's ports and verifies every criterion for real, browser included. It can run anything and change nothing but its own report.
7. BLOCKED → remediation-loop, three iterations maximum, then escalate to the user with what survived and why.
8. A story that passes validation with zero blocking findings merges into its base branch right away: story.mjs state <id> done and story.mjs release <id>. qa-engineer and docs-writer do not run per story — every story merges as fast as validation clears it, and formalization happens once, at the feature-level user-check gate below, after every story is in.

An agent returns a summary and a path, never the report itself. Its deliverable is already on disk by rule; returning the full text a second time puts it into the main session's context, where it is then re-read on every later turn. The main session is 27% of this feature's input tokens, more than any agent role except the engineers, and that is what most of it is. Ten lines and the path to the file is the whole contract: verdict, blocking count, and where to read the rest.

This is a hard cap, not a target: no pasted file contents, no blueprint excerpts, no diffs, no findings lists in the return message, whatever the reason feels compelling in the moment. If the summary would need more than ten lines to be useful, the extra belongs in the file, not the message: the main session reads the file when it needs the detail, once, not on every later turn by way of the conversation. A follow-up feature measured this rule "in force" and still watched the main session's share grow 27% → 32%; a rule that erodes under its own weight needs a harder edge, not a reminder.

An agent's report is not evidence. When an agent returns, the main session checks the worktree before believing it: git status --short plus the files the blueprint said would exist. Agents have returned confident summaries for files they never wrote, and have returned nothing at all after ninety minutes of work. Both are caught by looking, and only by looking. An agent that returns without a result is resumed with an order to write the deliverable to disk before composing any prose.

Parallelism

Stories are the unit, not features. Independent stories run at once; the dependency graph decides what is allowed to run in parallel, and the machine decides how many of those actually do.

Concurrency is measured, not chosen. Between one and six, never a fixed number. Before every dispatch:

sh .Codex/scripts/capacity.sh

It samples for five seconds and prints the slot count, the reason it is that number, how many stories are already in flight, and how many more to dispatch. The exit code is the slot count, so it can gate a loop. Dispatch what it says and not one more. If it says zero more, the answer is to let the running stories finish, never to push the seventh and hope.

The signals it reads, and why each is there:

• Kernel memory pressure (kern.memorystatus_vm_pressure_level) is the one to trust over the others, because it is what the OS itself acts on. WARN caps at three, CRITICAL at one.
• Swap growth, not swap used. Used never falls on macOS: pages stay in swap until something touches them, so a machine that recovered an hour ago still reads eleven gigabytes used and means nothing by it. Growth is the part that means something.
• Free memory percentage. Below twenty per cent this laptop starts paging out things the user is actively using, which is the state where it stops being usable for anything else.
• Load per core, not raw load. Eight cores make a load of eight ordinary and a load of twenty-four a wall.

Two things the script cannot see, so they are yours to apply on top of it:

• A container build under QEMU emulation counts for more than one slot. A docker buildx --platform linux/amd64,linux/arm64 on this machine froze it hard: buildkit OOM-killed in an eight-gigabyte VM, load average fifty-nine, swap at thirteen gigabytes of fourteen. If a story needs one, it runs alone or it moves to CI.
• The measurement is a snapshot. Re-run it between dispatches, not once at the start of a wave.

A slot is held by a story's implementation, not by its paperwork. Once a story passes validation it merges and its slot frees immediately — nothing holds a slot open waiting on a human or on tests and documentation, because neither runs per story any more. Stories touching the same file or the same contract run sequentially, in graph order. The registry (.Codex/registry.json, main checkout, lock-protected) is what stops two sessions taking the same story or the same ports.