Feature Cycle

The loop for building a feature and never letting it go invisible. Each pass ends by surfacing what the next one starts from.

This skill exists because the expensive failures on real projects are not scoping failures. Work gets built and then disappears, finished but uncommitted, merged but never announced, broken in a branch nobody ran. Step 0 and step 3 are the ones that fix that. Everything else is chaining tools that already exist.

The skill carries the loop and the discipline; every project-specific fact lives in a per-project profile (see step 0a). Fill the profile in once for your project and the same loop runs correctly there.

0a. Load the project profile: do this before anything else

Every concrete fact this skill needs (who the stakeholder is, the repos, the base branch, the seed accounts, the DB clone command, the dev ports, the verification stack) lives in a profile, not here. That is what makes this reusable instead of wrong on every project but one.

Find it, in this order:

1. .claude/feature-cycle-profile.md in the repo you are working in (preferred: it travels with the project).
2. A profile the user names or pastes.
3. None yet? Copy profile-template.md (next to this SKILL.md), fill it in with the user, and write it to .claude/feature-cycle-profile.md. Do not guess the values, a wrong seed account or base branch is worse than asking.

Everywhere below that says [profile: X], read X from the loaded profile. If the profile is silent on something, ask; do not fall back to a default carried over from another project.

The fast path

No time? Do these four and stop:

1. Close out what is loose: commit anything finished, land anything ready
2. Audit: check it does not already exist
3. Build it
4. Say what shipped: to the stakeholder [profile: stakeholder], in their language

Everything below is the full version. It is worth running when there is room, but a process that only works with an hour to spare is one you abandon on the day it would have helped most. Four steps in thirty minutes beats eleven steps skipped.

Talk while you work

This is a loop you run WITH someone, not a batch you hand back finished.

The failure is specific: the audit lands, approval is given, and then an hour passes with no word while branches, commits and PRs accumulate. Your partner cannot redirect what they cannot see, and by the time they ask "what's happening?" the expensive decisions are already made.

Three places to stop and say something, every time:

1. After the audit (step 3). Report the verdicts and wait. This is where a "big build" most often turns out to be a two-line link between existing things.
2. After each landable unit (step 6). One PR, one migration, one slice: say what landed and what it cost before starting the next. Not a progress bar; a checkpoint where the plan can still change cheaply.
3. Whenever a decision has more than one defensible answer. Ask. A question costs one message; a wrong assumption costs a rebuild. If proceeding under an assumption is genuinely safe, state the assumption out loud and keep going.

Batching is correct for execution once a decision is made. It is never correct for the decision itself.

Non-negotiables

Three rules hold no matter how small the work is, or how little time there is:

1. Audit before you build. Never write code for something until you have checked whether it already exists.
2. Every piece of work gets a tracker issue. The issue tracker [profile: issue tracker] is the project management tool. Untracked work is invisible work.
3. Close the loop. Committed, landed, issue closed, and the stakeholder told. "Done" on your machine is not done.

0. Close out the last cycle: do this first

Before any new work. Not at the end of a session, when you are tired and something more interesting is always available. At the start, when there is no momentum to protect.

git status --short                    # anything finished but uncommitted?
git worktree list                     # branches held, work parked mid-flight
gh pr list                            # anything sitting in review?
gh issue list --state open            # anything describing work already shipped?

Then:

• Commit anything finished. Work that exists only in a working tree is one git checkout from gone. This is not hypothetical: on a real project a completed nav fix sat uncommitted through an entire client demo and was invisible to every branch built from.
• Land what is ready, or say plainly why it is not moving. A branch open two weeks is a problem, not a state.
• Close issues describing shipped work.
• Write the "tell the stakeholder" list: what shipped since you last spoke, in their language [profile: stakeholder]. Shipped work they do not know about counts for nothing.
• Name what is still open and why.

Whatever this surfaces is the input to step 1. If the previous cycle ended cleanly, this takes a minute and confirms it.

1. Get it out of their head

The user talks the feature through in plain language: the messy version, edge cases, the "oh and also" parts. Do not interrupt with structure. Let the whole thing land first.

Two possible inputs:

• They talk it out. Take it as-is, no reshaping.
• A meeting transcript. Then the rule is the stakeholder's exact words, never a summary. Summaries lose the thing that matters, a single throwaway line often turns out to be the whole requirement. When something is ambiguous, quote them and ask, rather than resolving it yourself.

2. Question it

Now interrogate. Aim at the parts that change what gets built:

• Who is this for? Check the personas and role gotchas [profile: personas & role gotchas], because projects often have a role that is secretly two things, or a label that means something non-obvious.
• What happens on the unhappy path: nothing found, permission denied, half-filled form?
• Does this need to work on mobile? Honor the platform constraints [profile: platform constraints] (e.g. mobile input patterns).
• Does it touch money, contracts or personal data? Those raise the bar on review.
• What does "done" look like from the stakeholder's side: what would they click to believe it?

Tighten until you could build it without guessing. Then say back what you understood, in their words, and get a yes.

3. Audit: the step that saves the most time

Before writing anything. Check whether it exists already, in this order:

git log --all --oneline -15 -i --grep="<topic>"     # has this been built?
git branch -a --contains <sha>                       # is it merged, or stuck in a branch?
gh pr list --limit 20                                # is it sitting in review?
gh issue list --search "<topic>" --state all         # is there already an issue?
git status --short                                   # is it finished but uncommitted?

Then grep the code for the actual surface. Verify by reading, not by memory.

Classify every item as one of:

If what you are about to add is a helper, formatter, hook, utility or component rather than a whole feature, this git-level audit is the wrong tool. Invoke vertical-slice-matrix (Mode B) instead: count every copy before you touch one, and state the count in the handover. The git checks above answer "does this feature exist"; Mode B answers "how many times have we already written this", which is a different question with a different failure mode.

The same applies to adding a value to an existing closed set (an enum, a status list, a permission set, a method or provider list). Git history will show you the feature that introduced the set and tell you nothing about how many places now declare it.

Report the verdicts, then stop and let your human partner react before you propose work. This is the step most likely to change what gets built; it routinely finds items already done and turns a "big build" into a missing link between two things that already existed. Presenting the audit and starting in the same breath wastes the one moment where the cheapest decision is available.

4. Track it on the issue tracker

Every item gets an issue on [profile: issue tracker]. Scale only the ceremony:

• Small or medium: one issue, written straight from step 2, in the user's language rather than implementation terms. No epic.
• Large: needs a migration, or spans multiple repos, or is more than a couple of days: if the feature-boilerplate skill is installed, invoke it for the full milestone → epic → user-story treatment. If not, do it by hand: open a milestone, an epic issue, and one user-story issue per slice.

The size trigger is concrete: does it need a migration, or more than one repo? If no to both, one issue is enough.

Repos: [profile: repos].

5. Branch and isolate

Always fetch first, and branch from the remote: never from a local base that may be stale.

git fetch origin
git worktree add -b <prefix>/<name> <worktree-dir>/<short-name> origin/<base>

Worktree directory and base branch come from [profile: worktree dir] and [profile: base branch per repo]. One worktree per concern, so unrelated work never tangles and the user's working tree is untouched. The user's working tree is off limits, never commit or stash in it without being asked.

Naming

Use the branch prefixes the repo already favors [profile: branch prefixes]. Typical set:

Match the dominant convention rather than inventing drift: if history uses feat/ and not feature/, use feat/.

Name for the outcome, not the mechanism: feat/owner-marks-job-complete, not feat/lead-patch. Since every piece of work has an issue, leading with its number ties the branch, PR and issue into one chain, feat/195-verified-badges.

The worktree takes the branch's slug, without the prefix or issue number (feat/195-verified-badges → <worktree-dir>/verified-badges). git worktree list should read as a table of contents. No abbreviations, write the words out; the path costs nothing. Never reuse a name for different work. When a feature spans multiple repos, use the same worktree name in each.

Choosing the base

Default: the profile's base branch per repo [profile: base branch per repo]. That is the rule.

The one exception: when you are extending code that has not landed yet, branch from that branch or you are building against code that does not exist. Treat needing that exception as a warning, not a normal case: it means something has been unmerged long enough to become a base of its own. When you hit it, say so, and ask whether landing the parent first is the better move.

Worktrees, and running several agents at once

Check what exists before creating anything: git worktree list, then git worktree prune for entries whose directory is gone.

One branch, one worktree: git enforces this. If a branch you want is already held, branch from it (origin/<branch>) instead of checking it out.

Always create inside the profile's worktree dir, which the repo ignores. Avoid job temp directories: they outlive the session, keep holding their branch, and are invisible until someone runs git worktree list.

A worktree isolates code and nothing else. Ports, database and containers are shared [profile: dev ports, DB]:

• One app instance at a time, or give each agent explicit ports.
• Never let two agents migrate the same database. Give each its own via the clone command [profile: DB clone command].
• Env files do not come with a worktree: they are gitignored, so a fresh worktree has none and will point at the wrong API or fail to boot. Copy them in [profile: env files].
• node_modules/deps are per worktree. Budget for the install; do not assume a new worktree is ready to run.

Give parallel agents non-overlapping surfaces. Two agents editing the same config on separate branches will not conflict while they work and will conflict at merge. Split by feature area, and say which files each owns.

Do not tidy up worktrees or branches after merging unless asked; iteration continues in them.

Long-lived branches for big features

For something large (new tables, multiple repos, weeks of work) a feature branch that smaller branches merge into is reasonable. The cost is real: long-open epic branches drift from base and hide migration chains that cannot run. If you use one, it needs a landing cadence and someone actually running its migrations. Prefer merging in slices over accumulating one large branch.

6. Build

Before you write any helper, formatter, hook, utility or component, invoke vertical-slice-matrix (Mode B) and count what already exists. Not "have a look", count, and carry the number. The threshold decides for you: 1-2 copies leave alone, 3 is judgement, 4+ means consolidate one and delete it in the same change. This is the single cheapest step in the loop and the one most often skipped, because grepping feels like overhead next to writing the thing.

Adding a value to a closed set counts, and it is the case you will miss. An enum, a status list, a permission set, a payment or delivery method, an event type, a role, a flag, an error code. Typing one more string into a list that already exists feels like the smallest edit available, which is exactly why it goes unchecked, and that list is typically declared in several files that will not all get updated. Mode B's first section routes this differently from a helper: a closed set is a fact, so there is no free pass at one or two copies and you make the copies derive instead of migrating one at a time. Run it per capability the change touches, not once per task; counting the capability the feature is about and skipping the one it is extending is how this gets missed.

Ask whether this feature should notify anyone, and record the answer either way. Four questions:

1. Does something happen here a human would want to know while not looking at this screen?
2. Is the person who needs to know different from the person who did it?
3. Does knowing sooner change what they do?
4. Is there already a screen someone watches for this?

Yes, yes, yes, no means it wants a notification. Anything else means it does not, and saying so in the PR is the deliverable: an unasked question looks identical to a deliberate no, and only one of those is a decision.

Treat this like the wide-event log line or the audit entry: a thing every feature accounts for, not a thing some features remember. If the project has a notification registry, adding one should be a declaration plus a publish call [profile: code conventions]; if it costs more than that, the cost is the finding, and it belongs in architecture-guardrails rather than being absorbed quietly.

If the feature changes the state of something two or more parties share (statuses and moves such as accept, decline, withdraw, approve, counter, cancel, expire; screens that must agree on a status; "who can act now" decided in more than one place), invoke lifecycle-feature before writing code, or the project-specific lifecycle-feature-<project> skill if one exists. Its gate decides in five questions; if the answer is "not a lifecycle", it says so and you build plainly.

Match the surrounding code: comment density, naming, existing patterns. Prefer extending a proven pattern over inventing one; if there is already a signal, a guard, a helper doing something similar, mirror it.

Honor the project's code-layout conventions [profile: code conventions] (where copy lives, casing rules, etc.).

7. Verify against a proven baseline

Never trust an exit code or a total if the repo is not green [profile: verification stack].

• Type-check / lint: capture output, then check per file you touched. Totals fluctuate if the repo generates code.
• Tests: if the suite has pre-existing failures, prove it: git stash, run, compare, git stash pop. Do not assume.
• Migrations: apply against a throwaway or cloned database [profile: DB clone command], never the user's dev DB. Test the reverse too.
• Behaviour: for browser-facing work use the project's browser tool [profile: browser tool + seed accounts]. Auth against the local backend with the seed accounts from the profile.

State what you verified and what you did not. "Type-checks clean" and "I ran it" are different claims.

8. Review your own work

Before showing anything, re-read the diff looking for what you got wrong, not what you wrote. This reliably finds things: a missing import, an N+1 from a serializer field, a state you did not consider.

If the review turns up a class of mistake rather than one instance: the same bug you fixed last month, a green build that shipped something broken, a rule that exists only in someone's head, then invoke architecture-guardrails and turn the scar into a check. Fixing only the instance guarantees you meet it again; the skill exists so that "we keep hitting this" becomes a build failure instead of a memory.

Then, if the code-review skill is installed, invoke it for the real pass. If not, do a deliberate review pass yourself: read the whole diff once more against the requirements, checking edge cases, error paths, and anything that touches money, contracts, or personal data.

9. Prove it runs

For anything the stakeholder will demo, a passing test is not proof. Stand it up:

• Clone the dev DB rather than migrating it [profile: DB clone command].
• Apply migrations to the clone, then seed whatever the feature needs to be visible. A feature gated on data nobody has shows a blank page.
• Turn the feature flags on. Anything built behind a flag defaults to off, which means the demo shows nothing.
• Verify through the API before handing over a URL.

10. Document what is true

For a feature worth explaining to the stakeholder, produce the architecture doc:

• Verify every claim against code first: real enum values, real table names, real counts. This is the majority of the work; the diagrams are mechanical once you know what to say.
• Pick views by the question they answer, and cut any you cannot justify:

• Colour-code by real ship state (live / in a branch / not built) derived from git, never memory.
• Include a plain-language section on what is not built.

If the mermaid and artifact-diagramming skills are installed, use them: mermaid for diagram syntax, artifact-diagramming for whether a picture earns its place. If not, write the diagrams in plain Mermaid yourself and cut any that do not answer a real question. A stale doc is worse than none. Regenerate before each stakeholder meeting.

11. Close it: or let step 0 catch it

Ideally you close here: commit everything, open the PR referencing its issue, and write the "tell the stakeholder" list while the work is fresh.

Realistically this is the step that gets dropped (you are at the end of a session and closing out feels like admin. That is exactly why step 0 exists and runs first. Treat this as the preferred path, not the only one. What must not happen is both being skipped) that is how a finished fix ends up invisible through a demo, and how a PR sits unmerged for weeks hiding a migration chain that cannot run.

Whatever is left open (unlanded branches, unanswered questions, deferred scope) is the input to the next cycle's step 0.