Qstack Loop Trequartista

/qstack-loop-trequartista

Treat the plan as the shape of play, not a cage. Preserve its intent while making careful, visible adaptations when reality offers a better route.

Resolve the plan

1. Use the supplied plan path when present.
2. Otherwise use a plan clearly referenced in the conversation.
3. Otherwise inspect qstack/compound_engineering/plans/*/plan.html, plus legacy compound-engineering/plans/*/plan.html and plan.md files. Use the only plausible candidate; ask if more than one is plausible or none exists. Never select .template/.

Resolve the repository root, read its instruction files, then read the whole plan. Do not edit the plan: it is frozen once execution begins.

Verify approval before implementation. An explicit request to execute this specific plan counts as approval to start only when the plan itself is not marked draft, proposed, or otherwise unapproved and has no unresolved blocking gate. If approval is absent or contradictory, stop and ask.

Choose the review mode

Review depth is the user's cost and quality choice. Resolve the plan, detect whether it has a board, inspect any existing execution.md, and read plan and repository review requirements without writing anything. Then settle the mode before creating or updating execution files, migrating or claiming a board, launching an agent, or editing implementation files.

--review full|final|none supplies the choice for automation. Reject any other value. Always validate an existing execution.md first, with or without the flag:

• if Review mode is present, it appears exactly once and must be full, final, or none;
• no such field means a legacy full run and is not rewritten merely to backfill the field;
• a duplicated, malformed, or unknown value stops preflight without mutation.

Without the flag, reuse that recorded or legacy mode without asking. With the flag, it must match that mode as described below. For a new execution without the flag, ask one startup question, using the host's structured question tool when available and plain text when it is not. With a board, ask:

How much independent adversarial review should this run use?

• Final review only (recommended): one fresh reviewer after all work, balancing coverage and token cost.
• Full review: review every card and the combined result; highest coverage and token use.
• No adversarial review: fastest and lowest token use; rely on validation only.

Without a board, full and final both launch one whole-plan reviewer, so do not present them as different costs. Ask instead:

How much independent adversarial review should this run use?

• One whole-plan review (recommended, recorded as final): balance quality and token cost.
• No adversarial review: fastest and lowest token use; rely on validation only.

Review mode is fixed once execution starts. On a resume, a --review value that differs from the recorded or legacy mode is a conflict: stop and name the mode already in force. Completed cards cannot be retroactively returned to their original isolated per-card review state, and changing fingerprinted execution content would invalidate earlier reviews. Do not ask again on a resume. An invalid or conflicting review flag is a preflight failure. This invocation never claimed the board, so it appends no stood-down and does not alter any coordinator left by an earlier run.

The modes are:

• full: per-card review plus one final plan-level review;
• final: no per-card reviewers, then one final plan-level review;
• none: no reviewers and no review fingerprints.

Without a board, full and final both mean the one whole-plan review that the loop can run; an explicit --review full remains valid and is recorded as full. Review mode controls only the reviews this loop adds. During the read-only preflight, derive the minimum permitted mode from plan and repository instructions. A required final independent review permits only final or full; required per-card independent review permits only full when a board exists. Without a board, a per-card mandate is unsatisfiable: stop preflight and name the requirement rather than pretending the whole-plan review meets it. Remove weaker modes from the startup question and reject a weaker --review, recorded, or legacy mode before any mutation. If only one behavior is permitted, explain the requirement and use its least expensive valid mode without asking a fake choice. The choice changes reviewer agents only; implementation subagents and --parallel are unchanged.

Resolve the board

Look for board-events.js beside the plan. If only the retired board.jsonl exists, resolve the shared protocol below and follow its migration branch before deciding the plan has no board. Stop if both exist.

With no board, run exactly as this skill does without one. The whole plan is the unit of work and execution.md keeps its ## Progress checklist. Existing plans keep working and nothing else in this section applies.

With a board, the board is the progress record and qstack-plan-to-html/references/board-protocol.md is how you work it: folding the board, claiming it, the ready set, the pick, the claim race, the wave, dispatch, what a card owns, the transitions, parking, resuming a blocked card, splitting, and standing down. Both execution loops read that one file, so the protocol cannot say two different things.

Resolve it relative to this skill's installed directory, never a hardcoded path. This skill installs into any of ~70 agent directories and may be a symlink. The protocol lives beside qstack-plan-to-html, which is the skill that writes a board in the first place, so both loops read one copy and neither owns it.

# Resolve the skill's own directory, following a symlink if there is one.
SKILL_DIR=$(dirname "$(readlink -f <path-of-this-SKILL.md>)")
cat "$SKILL_DIR/../qstack-plan-to-html/references/board-protocol.md"

Read it in full before you fold the board, and follow it exactly. If it is unavailable, do not work the board from memory: report that the board protocol could not be read, that no card was claimed, and that the workflow is incomplete. Then stop.

This skill's latitude does not reach the protocol. Board ownership in particular is not an adaptation the orchestrator may make, however small and reversible taking a board over looks.

The board sections below are this skill's own rules. Where one sharpens something the protocol states, it names the rule it sharpens instead of restating it.

Start the execution record

Create or resume execution.md beside the plan before changing implementation files. Never overwrite prior notes. Resume only when its mode is trequartista. If another mode is recorded, stop and require explicit approval to transition; record the approved transition before continuing. If its status is complete, require explicit approval to reopen it. If it is blocked, resume only after every blocking item is resolved. Record either status transition. Use this shape:

# Execution

- Plan: <repo-relative path>
- Mode: trequartista
- Review mode: full | final | none
- Status: in-progress | blocked | complete
- Started: YYYY-MM-DD
- Updated: YYYY-MM-DD

## Progress  <!-- omit when board-events.js exists; the board is the progress record -->
- [ ] <plan task or acceptance condition>

## Design decisions
- <choices made where the plan was silent or ambiguous>

## Deviations
- <what changed from the plan, why, impact, and whether approval was required>

## Tradeoffs
- <alternatives considered and why one was chosen>

## Open questions
- [blocking | non-blocking] <question>

## Validation
- <command or check>: <result>

## Adversarial reviews
- <round, reviewer findings, and resolution; or explicit skip for `none`>

Update it when a decision is made, not from memory at the end. Record facts the user should know, not routine narration or private reasoning. Mark replaced entries as superseded rather than deleting history.

Adapt without losing the plan

You may make a deviation without interrupting the user only when it is:

• small and reversible;
• consistent with the plan's stated intent and acceptance criteria;
• invisible to users or an obvious correction of an implementation detail;
• no riskier than the planned approach; and
• recorded in execution.md when the decision is made.

Before making a material deviation, stop and ask one focused question. State what the plan says, what you learned, the recommended change, and the main alternative. Material deviations include changes to scope, user-visible behavior, acceptance criteria, architecture, public APIs, data formats, dependencies, security, privacy, cost, timeline, or irreversible work. If unsure whether a deviation is material, treat it as material.

Record approved changes as approved deviations. Do not rewrite the frozen plan.

Select and claim cards

Arguments

/qstack-loop-trequartista [plan-path] [--tasks T-03 T-07] [--epic <epic-id>] [--limit N|Npt] [--parallel N] [--review full|final|none]

--review applies with or without a board and supplies the startup review choice instead of asking. With a board present the default is the whole board, ordered by this orchestrator. --tasks narrows to the named cards. --epic narrows to one epic. --limit N stops after N cards close, --limit Npt after N points close. --parallel N sets how many cards this run holds at once, and --parallel 1 runs the board serially; without it the wave is the width the protocol's The wave sets. Selection happens here and never on the board. The board renders a file and has no controls.

A narrowed or limited run that leaves cards open cannot satisfy the completion gate. Leave the status in-progress and report which cards remain.

The pick

Take cards from the ready set in the protocol and record why you took each one in the claimed event's reason field. Honest reasons read like these:

• unblocks four cards
• T-04 is done and touched the same files, so the context is loaded
• smallest card that proves the migration works before the rest commit to it

Feel is allowed. Unrecorded feel is not. The ready set itself is not one of this skill's adaptations: a card it excludes stays excluded, whatever route through the plan looks better from here.

The wave

Fill a wave and dispatch it, under the protocol's The wave and Dispatch. Claim every card the ready set offers until one of the four listed stops applies. How many cards to hold is not one of this skill's adaptations, and neither is declining to hold one: the four stops are the whole list, and --parallel already set the width. A wave needs no recording as a deviation, because cards the breakdown left independent are independent.

Where the wave meets this skill's own rule, the rule wins. A non-material adaptation on one card that would change what a sibling card in the same wave is building is material, because the sibling is already building against the unadapted version. Park it and ask, or hold the adaptation until that card closes. The wave is not a licence to adapt around a card you are running beside.

Park and continue

Park under the protocol's Park and continue, with one thing settled here: material decisions park. When a card reaches one, move it to blocked with the question in its note, leave the rest of the wave running, and refill it from the ready set. The run does not stop.

A permitted non-material adaptation is still made on the spot and recorded in execution.md. Parking is for material decisions only.

Resume a blocked card

Follow the protocol's Resume a blocked card. Record the answer in execution.md before the move, under the rule this skill already applies to an approved material deviation: what the plan says, what you learned, and what was approved. The plan stays frozen.

Splitting

Follow the protocol's Splitting, including the rule that a card whose depends_on names a split parent waits on that split's children. Two loops that pick ids differently collide on one board, so the id convention there is not yours to adapt either.

A split is a board change, not a plan deviation, and needs no approval, because points are an estimate and the plan never promised one. Children that would cover more or less than the parent covered are a material deviation, and Adapt without losing the plan applies. If the note on an 8 does not say what the card splits into, report that card and leave it alone: filling it in yourself is a material deviation dressed as a board change.

Execute and orchestrate

Break the plan into trackable tasks and keep their status current. With a board, the cards are those tasks and board-events.js is where their status lives. Fill a wave from the ready set, dispatch one subagent per card, and move each card through the protocol's transitions as it gets there. Delegate bounded independent work when agent tools are available, but inspect and integrate every result yourself. Preserve unrelated user changes.

Brief each card's subagent under the protocol's Dispatch, and add what this skill requires: it reports a material decision back rather than taking it, because Adapt without losing the plan is yours and not the subagent's. You park the card.

Build what the plan prescribes. Where it leaves the implementation open, or a lighter build is a deviation you may make under Adapt without losing the plan, write the least code that meets the acceptance criteria of the card, or of the task when there is no board. Before writing anything new, take the highest of these that fully meets the requirement, edge cases included: a helper, component, or pattern already in this repository; the standard library; a native platform feature; a dependency already installed; then the minimum new code. Add no abstraction, configuration, wrapper, or file that neither implementing nor verifying it requires. Before editing a function, grep its callers and fix the shared path once. Never cut validation at a trust boundary, error handling that prevents data loss, security, accessibility, or anything the plan names. When you take a higher rung than the obvious build, record it as a design decision, or as a deviation when the plan prescribed the heavier build.

Implement the full plan, update execution.md continuously, and validate in proportion to risk. Run the repository's relevant tests, linters, type checks, builds, and focused behavioral checks. Do not commit or push unless the user explicitly asks.

Run the selected adversarial reviews

In full mode, run one review per card and one for the plan. A per-card review runs while the card is in review, before it moves to done, and is scoped under the protocol's What a card owns: that card's files, the paths the card actually wrote, and the plan clauses in its refs.

In final mode, move validated cards directly from in-progress to done under the protocol and run only the plan-level review. In none mode, use the same direct card transition, record that adversarial review was skipped by the explicit review choice, and launch no reviewer.

The plan-level review in full or final runs after every other card on the board is done or split, never merely after the last card selected by --tasks, --epic, or --limit. It catches integration and seams no single card's diff showed. Without a board, that is the one whole-plan review. For every enabled review, launch a fresh independent agent. A self-review does not satisfy the selected mode.

Give the reviewer raw evidence rather than your conclusions:

• repository root and plan path;
• execution.md path;
• the base reference and the diff. A full per-card review gets what What a card owns specifies. A plan-level review gets the complete diff including untracked files;
• validation commands already run.

Ask the reviewer to read the plan and inspect the actual implementation without editing files. It must look for missing requirements, material unapproved or undocumented deviations, incorrect behavior, regressions, unsafe assumptions, weak tests, unrequested code (an abstraction, configuration, dependency, wrapper, or file that no plan requirement or its verification calls for), and inaccurate or incomplete execution notes. Require findings to include severity, evidence, and a concrete remedy; require an explicit statement when no blocking findings remain.

Before each review, record a content fingerprint for the reviewed state in execution.md. Include tracked changes, hashes of untracked files, and every substantive section of execution.md; exclude the append-only Adversarial reviews section, the Status and Updated fields, and the plan folder's own append-only bookkeeping: board-events.js, which the gate card's own transitions change during the review it is fingerprinting, and this execution.md, which enters through its substantive sections and would otherwise be hashed twice. A full per-card fingerprint covers that card's files and only the execution.md entries naming that card. A full or final plan-level fingerprint covers the whole change and all of execution.md. Scoping the per-card fingerprint this way is what lets a wave run: the orchestrator writes every card's decisions into one execution.md, so a fingerprint over the whole file would be changed by every sibling and no card review would ever stay valid. Triage every finding yourself. Fix valid findings, update execution.md, and rerun affected validation. If a fix requires a material deviation, ask first under Adapt without losing the plan.

Launch another fresh reviewer after any accepted finding changes code, tests, configuration, dependencies, migrations, generated artifacts, or any fingerprinted execution content, regardless of why it changed. Merely appending that review's unchanged findings and resolution to execution.md does not invalidate it. The last review must match the final implementation fingerprint.

What the wave changed together is what the plan-level review and its whole-change fingerprint are for.

In full or final, changing only Status from in-progress to complete and refreshing Updated after review passes does not require another review. No other post-review change receives this exception. In none, any substantive change after validation requires the affected validation to run again.

When full or final requires a reviewer and the host cannot launch an independent agent, report that limitation and do not mark the work complete. Do not silently substitute another review method. none requires no agent.

The gate card

A board written by the current breakdown ends with a review epic holding one card: the plan-level review, made visible on the board. The protocol's ready-set condition 5 offers it only once every other card on the board is done or split, whenever those cards arrived. That card is where the plan-level review above runs in full and final, and it is the one card not closed before that review starts. Run no second plan-level review beside it, and no per-card review of the gate card itself. A board with no review epic was written before this rule, and the plan-level review above runs as it stands.

Work this card yourself rather than dispatching a subagent for it: the two reviewers below are the only agents it launches, and a subagent cannot write the board events this card needs. Move it through the protocol's The transitions, which holds it in review for the whole round, and then:

1. record the plan-level fingerprint defined above, over the whole change and all of execution.md;
2. launch both in one dispatch so they run concurrently, a fresh plan-adherence agent and a fresh code-review agent, against that one fingerprint. Both are fresh, and independent of each other and of you.

Give the code-review agent the change without the plan folder's own record: execution.md, board-events.js, and outcome.md. That record is the adherence agent's primary input, it grows every round, and /qstack-review requires a reviewer to read every file it is handed in full. Exclude those three by name rather than by folder, since the plan folder also holds real deliverables, and say in the brief that they were excluded so the omission is not read as a silent skip.

Open no remediation card until both agents have reported: triaging the first while the second still runs spends rounds on findings the other may answer. Triage every finding yourself first: a reviewer agent can be wrong, and a finding you reject is recorded in execution.md with the evidence that refutes it rather than turned into work. Every P0 and P1 finding you accept becomes a remediation card in the same review epic: one created event you write yourself, under the protocol's Subagents never write, carrying the § clauses the finding traces to as its refs, points from the closed set, non-empty files naming the paths the fix will write, and a depends_on the protocol refuses a card without. Take the next free id under the protocol's Splitting. Those files never include the gate card's own execution.md, which the gate card owns for as long as it is live. A finding whose only fix is in execution.md gets no card: fix it yourself under the gate card and record what changed in that card's own note, because a remediation card naming that path could never satisfy ready-set condition 3. Work each remediation card through the board like any other. P2 findings go in execution.md and block nothing.

Remediation changes the fingerprint, so both agents run again on the new one. The gate card moves from review to done when both pass at one shared fingerprint, or on the human override below. Nothing else closes it, and the protocol's The transitions is where that is stated, including why it is never split.

The gate is not one of this skill's adaptations. A P0 or P1 finding is answered by a fix or by that override, never by a note in execution.md explaining why the deviation was reasonable. Where the fix needs a material deviation, ask first under Adapt without losing the plan, and the finding stays open until the answer arrives.

In none mode the gate card carries no review, because that mode launches no reviewer. Move it straight from in-progress to done with gate review omitted: review mode none in the move's note, and record the same skip in execution.md. That is the review mode the user chose rather than an override, and it accepts no finding unfixed, because none was raised.

The human override

A gate card also closes on an explicit human override: one board note naming who overrode it, why, and every finding accepted unfixed, followed by the moved to done from whichever status the card is in, review if the round is still open and blocked if it was already parked. Record the same three facts in execution.md.

Only a human instruction produces that note. A loop never writes an override for itself, and a stalled or repeatedly failing review is not permission to write one. What the loop does instead is park the card under the protocol's Park and continue, moving it from review to blocked with every finding that stands in its note, then ask and stand down. A reviewer the host cannot launch and a run that is out of budget end the same way. Parking rather than leaving it in review is what lets a later run resume it: standing down on a card still in review leaves it unclaimable, because the protocol's Standing down requires every claimed card to reach done, split, blocked, or released first, and only blocked has a documented way back.

Completion gate

Set execution.md to complete and report completion only when:

• every plan requirement and acceptance condition is satisfied as written, covered by a recorded permitted non-material deviation, or covered by an explicitly approved and recorded material deviation;
• with a board, every card is done or split, every card you claimed is one you closed, split, or released under your own slug, and your stood-down is on the board under the protocol's Standing down;
• relevant validation passes;
• in full or final, the final independent review fingerprint matches the current implementation; in none, execution.md explicitly records that review was skipped by the selected mode;
• no blocking finding or question remains; and
• execution.md accurately reflects all decisions and deviations.

Otherwise leave the status in-progress or blocked, append stood-down anyway, and state exactly what remains. In the final response, summarize the implementation, validation, selected review mode and outcome, deviations, open questions, and execution file. With a board, report the waves too: which cards ran together, and where the board held the run to one card. A run that was serial because every card depended on the last says so.