gstack design-to-ship

Start here for a bounded multi-item outcome

Run a goal from brief to evidence

A goal defines the outcome, tests and limits first, then lets the agent work through an ordered plan inside those limits. You approve the co-authored goal brief, then test usability after the evidence-gated merge; Production is a separate decision. The exact command is /gstack-goal.

Repository docs use the short command names below. In a host that namespaces plugin commands, select /gstack-execution:gstack-goal-new or /gstack-execution:gstack-goal in its command picker.

Before you type the first command

• A current gstack-execution installation, Git/Python, the target checkout and access through the moxywolf-agent GitHub app
• An existing DESIGN.md objective, a checkable outcome and invariants, permitted files, a named approval owner and agreed spending limits
• Working Codex/gpt test drafting, Gemini reading through OpenRouter and an independent builder/reviewer setup; credentials stay in the supported secure configuration. An item model recommendation must still respect builder-family independence
• The goal-test container/runtime and required target dependencies; local mode uses Docker. Browser goals use the Playwright image with Python and Chromium support, not an assumed browser in a Python-only image. Preserve the sealed holdout outside repositories until final validation
• Verified deployment boundaries. Preview variables must contain no production credentials; unresolved access or deployment safety does not become safe merely by selecting local mode

Before item work, read-only Haiku explore and docs agents gather code locations and reference passages; the builder judges that evidence. Item-level model advice is part of gstack. Session model routing is a separate workflow and does not switch the current turn or grant release permission.

Goal brief and test formats · Runtime and review prerequisites

1. 1. Draft a bounded goal

   Co-author the outcome, never-do constraints, scenarios and one-line plan in a live editable document. Read the author’s edits and comments, then confirm the draft is right before the agent writes goals/<id>/GOAL.md and PLAN.md under one existing DESIGN.md objective. The brief fixes allowed paths, scenarios, budget, provider budgets, call limit, item limit, review limit and stop conditions.

   /gstack-goal-new help-output "Our CLI prints useful --help and exits 0; existing invocations keep working"

   Copy 1. draft a bounded goal

2. 2. Prove the tests describe the goal

   Codex from the gpt family drafts the goal tests and hidden holdout. Gemini supplies a plain-English reading of every goal test. The baseline must show every outcome test failing on origin/main and every invariant passing. The builder must belong to neither of those families, normally claude for this drafting path.

3. 3. Approve the brief, then start

   Review the goal PR's outcome, ordered plan, spend cap and plain-English test reading. Give an approving review and instruct its merge at the approved head. Then run the goal command with that goal-approval PR number. Here 42 is illustrative: replace it with the PR that added this goal, not an item or final implementation PR.

   /gstack-goal help-output --pr 42

   Copy 3. approve the brief, then start

4. 4. Build and review each item

   The agent follows PLAN.md in order. Each item goes through /gstack-build on its own branch and PR into goal/<id>, carrying the prior items. A clean cross-vendor review, required checks and the goal's permitted-change checks are required before merging the exact reviewed head. Read release.json's release_lane and matching reasons for each item: contained and wide still need their applicable authority and gates; closed never merges autonomously under DR-113. Invariants must keep passing, and an outcome that passed on an earlier item cannot regress.

5. 5. Validate the whole result

   After every plan item is built and every goal test passes, code reads the sealed holdout and checks its approved hash. A fresh cross-vendor review covers the whole goal diff. In GitHub mode, finalize records RESULT.md and the holdout through a PR into goal/<id>, then propose opens the goal PR into main. The tests, goal-envelope, goal-tests and goal-holdout checks must be green, with coverage checked.

6. 6. Merge on evidence, then test usability

   GO-011 lets the bot merge the final goal PR at its exact head after tests, goal-envelope, goal-tests and goal-holdout pass and a fresh whole-goal cross-vendor review is clean with coverage checked. The runner must allow the merge. The review covers every item while keeping the sealed holdout out of its surface. Then record completion and run /gstack-usability <id>.

Worked example

The help-output example above is illustrative, not a completed run. A suitable brief might require an existing CLI's --help to print usage and exit 0, while its normal invocation keeps its existing output and exit code. First confirm the proposed outcome test fails on main and the compatibility invariant passes. If both already pass, the tests do not demonstrate new work.

The agent might propose one plan item for the help behavior and one for its documentation, with exact stdout, stderr and exit-code criteria. You review the allowed paths, test reading and budget before approving the brief. At the end, the runner checks item evidence, the whole-goal review and sealed holdout before the bot merges. You then try the verified Preview using the usability sheet before deciding on Production.

Usability before Production

Run /gstack-usability <goal-id> after the goal merges. First verify that the merge deployment serves the changed pages and passes its e2e checks. Keep Preview protection enabled. A custom product domain already attached means the goal is already in Production and must be reported.

The shared task sheet contains five to eight plain-language tasks from the goal’s scenarios, including an error state. Dorian marks each worked, confusing or broken and leaves notes. The agent reads the saved answers back; browser-local storage alone is insufficient. Wording, layout, links and accessibility fixes use their own reviewed build and re-test; behavior changes become a new goal. Unclear cases also become a new goal.

When every task’s latest mark is worked, or Dorian says to ship, ask once for the separate Production decision, naming what goes out and how. An automatic main deployment to a host address is distinct from attaching the product domain. Record the sheets, fixes, follow-on goals and the actual Production decision in USABILITY.md.

gstack-usability source

Commands to choose

/gstack-goal-new <goal-id> "<outcome>"

/gstack-goal <goal-id> --pr <goal-approval-PR> [--builder <family>/<model>]

/init-goal-mode <owner>/<repo>

What the runner controls

In GitHub mode, the agent uses start, next, merged or failed, finalize, propose, complete and record. It asks may before pushes, PRs, merges, review dispatches and outside calls. Unsettled in-scope code choices go to two other model families; a split or other decision type goes to the human. Digests are relayed as printed, while answer and ack record actual human responses.

The ledger is an agent-maintained record, not a global security boundary. GitHub rulesets provide repository enforcement. Printed messages do not prove receipt, and local checks do not create GitHub protection. This page documents source behavior; it does not certify your machine, installed versions, credentials, repository gates or any future run.

Goal-mode troubleshooting

The command is missing

Use /gstack-goal-new and /gstack-goal with hyphens. These are gstack-execution commands. Update or install the plugin in the host you are actually using, then check its command picker. A listing in this guide is not proof of local installation.

Readiness is missing or unknown

The read-only /init-goal-mode check belongs to project-init. Missing GitHub-mode onboarding can use local mode under GO-010; it is not a reason to copy gate files by hand. App access, missing permissions and unverified preview credentials still need resolution.

The brief or baseline is refused

Use the exact goals/README.md formats and one objective from origin/main's DESIGN.md. Include at least one outcome test and one invariant, scoped allowed paths and all deployment environments that require a human decision. Fix an unapproved brief and regenerate tests plus holdout before seeking approval.

The runner refuses the checkout or builder

GitHub-mode goal_run.py runs from the governed repository's own checkout, never an installed-plugin copy. Local-mode scripts run from the moxywolf-plugins checkout with target-repository paths. The builder cannot be from a family that drafted or read the goal tests.

The run is waiting

Exit 3 from goal_run.py next means a human decision or holding escalation. Relay the printed question and options, then record the person's actual words with answer or ack. An acknowledgement does not create a new permission grant. Other nonzero exits stop the current action; inspect the stated reason.

A review, holdout or budget check fails

Stop and report the evidence. Do not lower the model floor, remove acceptance criteria or edit tests to make the gate pass. A missing check is not a pass. A missing or unreadable spend ledger also stops the run. Spend is checked at action and step boundaries; reported costs and in-flight calls can overshoot the threshold.

A check failed or the release lane is closed

A failed ledger check clears only when the identical command and arguments pass from the same working directory. Before an item merge, read release.json's lane and matched paths or effects. Closed never permits an autonomous DR-113 merge; the Release Owner must merge or specifically instruct it. The final goal merge uses GO-011 checks and whole-goal review; Production remains a separate owner decision.

A model recommendation looks cheaper

MR-001/MR-002 defaults to shadow on the floor. Route mode needs at least 20 scored shadow lines and agreement of at least 0.90; record the actual declared_tier. /gstack-build does not launch a builder or switch the interactive session today. A recommendation cannot relax builder-family independence or reviewer floors.

A question remains unknown

Preserve its latest revision, required authority and evidence references. A stale revision, missing evidence or weaker source cannot close it. The wide release lane blocks open repository-authority questions; runtime or human questions remain explicit for the owner to resolve.

main moved while the goal PR was open

GitHub mode uses the documented sync PR into goal/<id>, an allowed may check and resync, then reruns checks at the new head. Local mode requires fresh candidate checks and review at the final head. Earlier approval and green checks do not automatically cover new code.