Imported from sergey-gusev94/skills (hybrid-build/SKILL.md). Install upstream with npx skills add sergey-gusev94/skills --skill hybrid-build. Copyright stays with the author.

Hybrid Build

Act as the lead. This skill wraps hybrid-implement: divide one frozen scope into coherent increments, take each increment through the full implement, review, fix, and terminal-gate procedure, and commit it before starting the next. Stay in the main conversation — never run this skill or an increment inside a subagent.

For every increment, read ~/.claude/skills/imp/SKILL.md and follow its full procedure, using this skill's own scripts/run-codex-implement.sh and scripts/run-codex-council.sh wherever that procedure invokes its scripts, including the council runner used for hybrid-review. Only Codex writes project files, and only through the implement script. You commit; Codex never does. Commit only under the protocol below. Never push, amend, rebase, run git clean, or otherwise rewrite or repair git state, and never set HYBRID_IMPLEMENT_ALLOW_DIRTY=1. Allow at most one active build run per repository and never two implement sessions at once. Invoking this skill is the user's standing authorization for one local commit per gated increment and nothing more.

Durable state

Keep all run state in $(git rev-parse --absolute-git-dir)/hybrid-build/. This deterministic path is inside the git directory, invisible to git status, and survives compaction and reboots so a fresh session can resume without paths from conversation history:

• scope.md is the frozen definition of done: a verbatim copy of the source document, or the normalized conversational scope, with its source path and a content hash of the frozen scope copy stored in this file. The recorded hash guards that copy's integrity. Never edit it during the run; mid-run drift in the source document alone changes nothing, and authorized scope amendments go in progress.md instead. Only a differing scope presented at re-invocation is a scope mismatch.
• progress.md records the run state — running, done, capped, or blocked, kept current — and the branch, immutable loop-baseline commit, and current-baseline commit used by iteration preflight and updated after each loop commit or adopted descendant; the dependency-ordered checklist, with each item pending, in-progress, done@<commit>, dropped: <reason>, or satisfied-by-prior-work: <evidence>; the consecutive no-progress streak; a short iteration log naming the item, its one-line description, /imp ending state, commit SHA, and checks run; closing-gate findings with their rounds and outcomes; the amendment log; a cross-iteration digest of rejected findings; and deferred out-of-scope ideas.
• iterations/NNN/ contains that increment's frozen /imp packet, /imp step-7 final report, persisted gated change — the tracked patch and the path, mode, and content-hash identity of every untracked file in the gated tree, excluding disposable artifacts produced by checks — and resulting commit SHA. Disposable check artifacts are neither persisted nor committed and do not fail cleanliness during post-gate, post-commit, or closing-gate work; this tolerance is transient, and anything whose disposability is unclear is surfaced instead of guessed.

On invocation, go directly to Frame the run when no state directory exists. When it exists, begin every iteration by re-reading scope.md, progress.md, and git log; never rely on conversation memory. Existing state without a coherent frame — including no valid run state in progress.md — is an incomplete frame: surface it and reframe with the user. Otherwise first verify that the recorded hash matches the frozen copy in scope.md, then compare the scope now presented — the source document's current content or the normalized conversational scope — with that frozen copy and act on the recorded run state; a re-invocation that presents no scope matches by definition. A matching running run resumes from the checklist; a matching done run is already complete, while matching capped or blocked state resumes only after the user resolves the cause and asks to continue, at which point mark it running. A mismatch against running state is a conflict: leave the live run and its recorded state unchanged, refuse this invocation, and ask the user. A mismatch against terminal done, capped, or blocked state is a new run: under the archive rule below, archive the old state files in a timestamped subdirectory within hybrid-build/, then frame afresh. If the frozen copy fails its integrity check, mark the run blocked and halt for the user.

At the user's explicit direction, likewise archive and frame afresh when abandoning a mismatched running run, keeping an intentional history rewrite, or discarding unusable state. Before archiving any run not ended done, surface unresolved blockers such as an unverified loop commit or dirty tree and obtain the user's disposition; never let a blocker silently become the new run's baseline.

Before selecting a pending item, reclaim any item left in-progress as the interrupted or halted increment and start with the iteration preflight's branch, ancestry, and clean-tree checks. If the dirty tree, apart from disposable check artifacts, exactly matches that increment's persisted gated change, continue with its commit protocol instead of halting; surface any other dirty tree to the user. When those checks establish that a moved HEAD is a clean descendant of the current baseline, inspect those commits before adopting them: a commit belongs to the interrupted increment when its subject names the checklist item or its iteration directory records that SHA. Compare it with the persisted gated change; if they match, finish the interrupted bookkeeping — record the SHA, mark the item done@<commit>, and advance the current baseline — instead of rerunning it. If they differ or the comparison cannot be established, mark the run blocked and treat the commit as unverified loop work under the commit protocol. If the user chooses to keep it, mark the run running, record the SHA, mark the item done@<commit> with an unverified-loop-work note, advance the current baseline, and require the cumulative closing review; never classify that commit as out of scope. After this classification, finish preflight by adopting any remaining non-loop commits. If no loop commit was reconciled and the item remains unfinished, revalidate it against the current code, freeze its packet again under a fresh iterations/NNN/, and run it with a fresh Codex session.

Frame the run

1. Preflight first: require a git repository with at least one commit, an empty git status --porcelain, and no merge, rebase, or cherry-pick in progress. Have the user resolve any non-ignored disposable artifacts by removing them at their direction or gitignoring them; the implement script requires a strictly clean tree. An untracked scope document inside the project also blocks the run, so have the user commit it or keep it outside the tree. Work on the checked-out branch.
2. Freeze the scope in scope.md. Derive a dependency-ordered checklist of coherent increments. Each must be independently implementable and reviewable and leave the repository working with its relevant checks passing. Coherence, not a numeric size cap, sets the boundary; an increment too small wastes a full implement-and-review cycle. This is the one point at which to raise a materially simpler overall approach with the user, before the loop rather than during individual iterations.
3. Show the checklist and its ordering to the user and obtain confirmation. With preflight still satisfied, write progress.md with running, the checked-out branch, the confirmed checklist, a zero no-progress streak, and the same commit as both loop baseline and current baseline. This completes the frame; only then start the first iteration.

Implement each increment

1. Verify that the tree is clean apart from disposable artifacts produced by checks, the current branch equals the branch in progress.md, and HEAD equals its current-baseline commit, subject to the exact persisted-gate exception under Durable state. If the tree is otherwise dirty, mark the run blocked, halt, and ask the user. If the branch changed, or git merge-base --is-ancestor <current-baseline> HEAD fails after HEAD moved, a reset, rebase, amend, or other non-descendant history change needs the user's decision: mark the run blocked, halt, and never adopt or repair it. At the user's direction, archive an intentionally rewritten run under the archive rule and frame afresh; never adopt the rewrite into the current run. For a clean descendant HEAD, first reconcile any commit belonging to an in-progress increment under Durable state. Then classify the remaining commits: record a user commit that resolves a logged closing-gate finding as gate-finding work included in cumulative review scope; adopt only the rest as non-loop work, logging their range and marking only that range out of scope. Advance the current baseline to HEAD.
2. After reclaiming any in-progress item under Durable state, select the next pending item and revalidate it against the current code: it must still be needed, coherent, and the right next step. Split, merge, or reorder checklist items when evidence warrants it, and log the reason. Drop a scope obligation only with recorded justification and the user's confirmation, never merely because it is hard; a user-confirmed, recorded drop completes the iteration, so continue with the next pending item and run steps 3–4 only for an item that remains selected. Put work that cannot be traced to the effective scope — the frozen scope plus authorized amendments — on the deferred list and report it at the end; do not implement it.
3. Write a self-contained /imp packet for this item alone: objective, acceptance criteria, constraints, non-goals that explicitly list all remaining checklist items so Codex cannot build ahead, pointers to relevant files, checks to run, and the rejected-findings digest as prior rejections. Freeze it under iterations/NNN/ and mark the item in-progress.
4. Before launching the fresh implement run for an increment, require an empty git status --porcelain; if non-ignored disposable artifacts remain from earlier checks, halt and have the user remove them at their direction or gitignore them because the implement script requires strict cleanliness. Then follow /imp through its terminal gate with a fresh Codex session for the increment; resume is only /imp's within-increment fix mechanism. Save its step-7 report under iterations/NNN/. Act on the ending state under the commit protocol, update progress.md, and put only a two-to-three-line summary in the conversation: the increment, ending state and commit, and items remaining. Then continue from durable state.

Commit protocol

Commit only between iterations and never while an implement or council script run is outstanding. On clean or minor-fixed, first persist the exact gated change under iterations/NNN/, excluding disposable check artifacts, then stage and commit exactly that change and no artifacts using a repository-style message whose subject names the checklist item. If a hook blocks the commit, disclose that fact, rerun the gate and refresh the persisted gated change before retrying, and never bypass it with --no-verify. After a commit succeeds, verify that the tree is clean apart from disposable artifacts produced by checks and the committed content matches the persisted gated change. If the created commit differs, including when a hook rewrote files but let the commit succeed, mark the run blocked, disclose that the commit is unverified, and halt; never amend it or add a corrective commit for that increment. If the user later keeps that commit, finish its bookkeeping under Durable state and retain it as loop work requiring cumulative closing review, not adopted out-of-scope work. Surface unattributed leftover files instead of sweeping them into the commit. Otherwise record the commit SHA under iterations/NNN/ and in progress.md, mark the item done@<commit>, and advance the current baseline to that SHA.

A completed /imp run whose convincing no-change result shows the item was already satisfied is a successful outcome: mark it satisfied-by-prior-work: <evidence> and create no empty commit. On capped or blocked, update the run state and halt the entire loop without committing. A capped increment has unresolved findings or unperformed verification, and later work must not build on it. Report the ending state and uncommitted tree to the user; after resolution, re-invocation resumes from deterministic state.

Close the run

There is no numeric iteration cap. Update the durable no-progress streak only after a completed iteration: reset it to zero when the iteration produces a commit, recorded satisfied-by-prior-work evidence, or a user-confirmed logged drop; otherwise increment it. Two consecutive completed iterations with none of those outcomes are a stall: mark the run blocked and halt. A capped or blocked iteration records its own halt cause and takes precedence without advancing the stall streak.

When no pending checklist work remains, run the iteration preflight in full, including reconciliation of any in-progress commit and classification, adoption, and logging of descendant commits. If preflight restores an item to the loop, continue the loop; otherwise begin a closing gate on the exact final tree and record its starting branch and HEAD. A commit the user made to resolve a prior closing-gate finding is gate-finding work included in cumulative review scope, never adopted out of scope. Require a clean tree apart from disposable artifacts produced by the gate's checks, trace every element of the effective scope — the frozen scope plus authorized amendments — to a commit or a user-confirmed, logged drop, and run the project's relevant checks. Disposable artifacts alone do not fail this requirement. Record every closing-gate finding — a failing project check, untraced effective-scope element, substantive check-produced change, or other defect — and adjudicate it like a review finding. Accepted findings become checklist items and the loop continues; a finding that cannot be addressed through an increment or needs the user's decision halts with the state its cause dictates. A substantive, non-disposable project-file change produced by a check also marks the run blocked: surface the dirty tree to the user and never commit the ungated content; after the user resolves it, re-invocation resumes from the checklist, and the closing gate runs again when no pending work remains. For a multi-increment run or any run retaining unverified loop work or gate-finding work, also read ~/.claude/skills/hybrid-review/SKILL.md and follow its full procedure, using this skill's council script, to review the cumulative loop-baseline-to-HEAD change against the effective scope; identify every adopted non-loop commit range as out of scope and include retained unverified loop commits and gate-finding work as work requiring verification. This cumulative review is required because per-increment reviews cannot expose every integration defect. Disclose and use a completed review labeled partial. Only when no closing review can be produced at all may you retry once; if the retry also produces no review, mark the run capped and halt. Adjudicate findings from every completed review as usual, but on second and later closing-review rounds accept only regressions and clear correctness or security defects and record other findings for the final report. Record each closing round and outcome in progress.md. At gate completion, including after the cumulative review, confirm that the branch, HEAD, and tree apart from allowed disposable artifacts are unchanged since the gate began; if any changed, the gate is invalid and must restart from full preflight.

Finish with an honest report and exactly one current state, recorded in progress.md: done when every effective-scope element is traced and the last closing gate passed; capped when the run is currently halted because an increment's /imp run ended capped or required closing verification could not be completed; or blocked when the run is currently halted by an unresolved blocked increment, policy drift, stall, unverified commit, dirty gate finding, failed state-integrity check, or decision only the user can make. A resolved halt does not carry forward after the run resumes, so a run whose last state passed the closing gate ends done. Never present a halt as success. List every increment with its commit and ending state, amendments and drops with reasons, deferred out-of-scope ideas, checks run, and the state directory path.

Archive, do not author: the frozen increment packet, /imp report, and commit message describe each change; generate no separate per-commit document. When an increment changes behavior described by the project's own documentation, that documentation update is part of the coherent increment and belongs in the same commit.