Zoo Heavy

Zoo Heavy

Read and follow .zoo/zoo.md if it exists.

Canonical artifact: .tasks//spec.md or _tasks//spec.md, unless the user explicitly asks to use a spec file under .spec/.

If a task root such as .tasks/, _tasks/, or a repo-specific alternate is ignored by git, every file under that root is workspace-only Zoo state. Never stage, force-add, commit, or push those files, including additions, modifications, or deletions of paths that were already tracked. Do not count ignored task-root files as uncommitted workflow changes.

Modes

Decide which mode you are in before doing anything else.

Top-level orchestrator mode

Use the full workflow below only when you are the main agent running the task end to end.

Delegated single-step sub-agent mode

If the prompt says you are a delegated sub-agent, gives you one specific step, tells you to write one report, or otherwise scopes you to one Zoo Heavy step, then you are not the orchestrator. In that case:

• execute only the assigned step
• do the work yourself
• do not run the full Zoo Heavy workflow
• do not spawn subagents
• do not wait for subagents
• do not do top-level closeout
• write exactly one report for your step, then stop

When there is any ambiguity, prefer delegated single-step mode over full-workflow mode. Accidentally doing one step too little is easier to recover from than accidentally starting a recursive orchestrator loop.

Spec format

# Title

## User Input

Why:

Original requested scope:

Hard constraints:

Soft preferences:

Unknowns:

Draft ideas to adapt with common sense:

## Spec

### Add Foo superadmin page

• Add the Foo feature package

• Register Foo page below Fubar, with two tabs: Manage and Effective.

• Manage tab displays a configuration form editor with ... sections showing ... controls

• Effective tab renders an HTML template superadmin_foos.html which displays a table, each row corresponding to ...

• Define FooVM struct with at least the following fields:

Xxx string Yyy int ...

• ...

### Add Foo section to customer admin page

• Add a section to shopadmin_customer.html displaying ...

• This section should be gated by PermissionCustomerSeeFoos.

• Extend bocustomers.DoShow to load ...

• Extend vmcustomer.CustomerVM with ...

• ...

### Store the last time X was done in the database

...

### Extend forms framework with support for editing uvwxyz data type

...

## Decision log

• Use the established navigation/page registration pattern for the new superadmin page.

• Gate Foos customer admin with a new PermissionCustomerSeeFoos permission, added to PermissionMacroCustomerView. (We could reuse PermissionCustomerSeeData, but all recent customer admin changes have added dedicated properties for new rows or sections displayed.)

• In customer admin, mark entire Foos section with access tag (“superadmin-only” or “published”). (We could mark every row, but they all share same access control permission.)

...

• (USER INPUT) Do not mention re-fribernation in externally visible docs and user interfaces, it's an internal term that only devs understand; instead word it around “queued updates”.

## Dependency Changes

## Open product and strategic questions

• Can we assume Frubernator will never be used together with Widgerator on the same venue? These two would be clashing on updating the frubenation counter. If these are never used together, we can simply store the counter as a single value. If multiple sources will be contributing the counts, we have to store the contributions separately, and reconcile them somehow, perhaps by taking a max() of the values?

...

## Execution memory

• Registration points: reg-navitems.go, reg-xxx.go, ambiguouspkg/foobars.go
• Added sufoos: impl and TestFoos_*
• Form framework: lifecycle tricky when handling postback on dynamic controls, solved in xxxform.go, needs more testing
• Tests do not sufficiently cover refrubbernation, broke it and only noticed in browser testing, should expand test suite in follow-up subtasks.
• ...

## Refactorings

• Proposal: .proposals/YYYYMMDD-example.md -
• Done: -

## Subtasks

• (next)
• Acceptance:
• Browser impact: possible,
• Plan:
• Evidence: TBD

• (future)

• (future)

Workflow

• This section is for top-level orchestrator mode only.
• This workflow is opt-in. Do not create/use Zoo Heavy for routine small tasks unless the user asks.
• Start or switch tasks with Bureau MCP tools.
• Use .tasks//spec.md as the spec source of truth.
• If the user explicitly asks to use a spec file under .spec/, that file overrides the default Bureau spec path and becomes the spec source of truth. Keep Bureau for task/report/evidence operations.
• If spec.md does not exist, planner drafts it from the user request.
• User Input records what the user asked for and must be updated when the user clarifies, corrects, or overrides direction. It preserves the exact original scope for closeout; do not backfill agent-added extras into it.
• If the user request references a ticket, issue, PR, or similar work item, its contents are part of the user request. Read it before planning and capture its hard constraints, soft preferences, unknowns, and draft ideas in User Input; direct user chat overrides ticket text when they conflict.
• If the user asks for revisions or follow-up changes to a prior Zoo Heavy run, continue in the same Bureau task and same spec. Do not start a new task/spec unless the user explicitly asks. Update User Input, reopen planning by adding or promoting a real (next) revision subtask, and preserve prior completed subtasks/evidence.

If spec has no active (next) subtask because planning has not started, run planner to define the first real (next) implementation subtask, draft future subtasks, and write the active-subtask plan for that real work. If all known subtasks are (done) and no (future) remains, run planner as the final task-completion check instead. Do not create a planning-only subtask.

Planning principles:

• Keep exactly one active execution target while the task is in progress: (next).
• Each completed subtask must keep the system shippable and tested; browser-impact work must include browser verification.
• Prefer smaller subtasks. Split a standalone functional slice into its own subtask when it either provides independent user value or has complex implementation that can be tested on its own; avoid splitting purely by file/layer when the slice cannot be validated independently.
• More subtasks is better than fewer when the slices are reviewable and testable. Treat each subtask as roughly one reasonable reviewable commit or small PR: if work is expected to touch a larger set of things, could plausibly stand on its own, and has observable testable output, make it its own subtask.
• The primary implementation path must answer the user's direct ask first. Do not bury the requested outcome inside broader discovered work unless that broader work is technically required for the direct ask.
• Significant scope expansion requires explicit user approval before implementation. Significant expansion includes new jobs, persisted state or migrations, new settings, public/API contract changes, broad subsystem behavior changes, operational dashboards/recovery mechanisms, and other work a user would not naturally expect from the direct ask.
• Significant scope expansion goes through the proposal system first. If it technically blocks the direct ask, write the proposal, then use the user-interview or Ask User path to approve the expansion before implementation. If it does not block the direct ask, leave the proposal recorded in Refactorings and continue the primary scope; the user can approve or request that work later.
• Zoo Heavy is not a waterfall. Plan the active (next) subtask deeply; future subtasks may include lightweight draft plans or current-best-guess notes, but avoid spending much time on details before promotion.
• Use what was learned in completed subtasks, reports, tests, browser verification, and code review to re-plan the next subtask and adjust future subtask drafts before promoting them.
• Future subtasks are scope boundaries and hypotheses; any tactical notes on them are provisional drafts.
• When planning, implementation, or review finds work affecting pre-existing code outside the active subtask, use zoo-refactoring: consequential cross-cutting changes become proposals requiring human approval, broad mundane refactors become separate subtasks/commits before or after the current subtask depending on whether they technically block it, and small low-pollution edits stay in the current subtask.
• Delegated subagents that classify a finding as proposal-worthy or separate-subtask work must write the proposal path or a Refactoring request in their report; the orchestrator owns recording proposals in Refactorings, editing spec.md, ordering subtasks, stashing, routing, and commit separation.
• After each completed subtask, rerun planner, plan_reviewer, and plan uberreview before coding the next one so the whole spec and active plan reflect the latest learnings.
• During the initial planning pass, collect all consequential unclear user questions and run one user interview before implementation starts.
• After implementation starts, research the uncertainty before blocking: inspect code, history, docs, production configuration, and production data when appropriate to collect enough evidence for the safest decision. Then use common sense, document the decision in Decision log, and proceed unless the choice is a high-impact product/strategy decision or super consequential tactical decision with no safe default.
• [blocker] questions in Open product and strategic questions or new step reports are a hard gate only when that high bar is met: the orchestrator must run user interview immediately and must not route to other steps until blockers are resolved.
• Default execution mode is continuous: after a subtask is completed, the orchestrator must run docs_writer, then commit, then continue into the next routed step automatically. Do not stop between subtasks unless blocked, a mandatory step fails, the user asks to pause, or a final planner report explicitly declares Full task status: complete, Reviewed: yes, and Closed out: yes. When the final planner report closes the full task, start final closeout by reading .zoo/task-finish.md if it exists; those instructions take priority over this skill, including whether to run zoo-rebase. Unless task-finish overrides it, run zoo-rebase, then use zoo-report before sending the final response.

Subtask Loop

Execute this loop for the active (next) subtask:

Before planning a newly active (next) subtask, read and follow .zoo/subtask-start.md if it exists.

1. planner: research the codebase, update the whole spec from user input, codebase context, and execution memory; keep future subtasks as lightweight current-best-guess drafts; write the detailed tactical HOW for the active (next) subtask in a plan report.
2. plan_reviewer: review both the overall spec and the active-subtask plan, then issue approved or revise.
3. orchestrator: after plan_reviewer approves, use the zoo-uberreview skill to run an uberreview of the approved plan. If uberreview reports findings, route back to planner, then plan_reviewer, then plan uberreview again. Do not proceed to implementation until normal plan review and plan uberreview both have no unresolved findings.
4. test_writer: write/update tests and define Browser test intent.
5. implementer: implement minimal correct change.
6. browser_verifier: run browser checks for browser-impact subtasks with the harness in-page browser tool (Codex: Codex Browser Use; Claude Code: Chrome extension MCP), use the OS-level automation fallback (Codex: Codex Computer Use) only when the in-page tool cannot cover the needed interaction, and produce screenshot/video evidence.
7. code_reviewer: review for bugs/regressions/missing tests.
8. orchestrator: after code_reviewer approves, check the latest Final-state validation entries from test_writer, implementer, browser_verifier, code_reviewer, and any fixes reports. If relevant passing validation is missing or stale for the current code state, run it once yourself before or in parallel with code uberreview. Use zoo-uberreview to review the code written for the subtask, telling reviewers that validation has passed or is orchestrator-owned and that they must not rerun broad suites. If validation fails or uberreview reports findings, route back to fixes and validation, then code_reviewer, then code uberreview again. Do not complete the subtask until final-state validation, normal code review, and code uberreview all have no unresolved findings.
9. orchestrator (no report required after this): follow references/end-of-step.md, enforce blocker gate, then choose next step.

If blocked, run problem_solver.

Browser-impact rule:

• Any subtask that touches or could potentially affect a user in-browser flow is browser-impact work.
• Browser-impact work MUST be tested in browser before the subtask is marked (done).
• Browser verification should use the repo's browser/app harness mode when it exists and covers the needed flow. Read and follow .zoo/browser.md if it exists.
• Browser verification should use the harness in-page browser tool (Codex: Codex Browser Use; Claude Code: Chrome extension MCP) for navigation, interaction, inspection, screenshots, and evidence capture. Use the OS-level automation fallback (Codex: Codex Computer Use) only when the in-page tool cannot exercise the required browser-visible behavior, or when the browser appears frozen (currently happening when a native alert or print dialog is displayed, or similar).
• Browser-impact work MUST include screenshot evidence under .tasks//evidence/.
• Video evidence is required when screenshots are insufficient (animation, transient states, timing-sensitive behavior).

Closeout rule:

• docs_writer runs during closeout for completed subtasks (not as a normal pre-closeout execution step).
• Final task closeout starts by reading .zoo/task-finish.md if it exists, immediately after all workflow commits are complete. Instructions in that file take priority over this skill's closeout instructions, including skipping or replacing zoo-rebase. Unless task-finish overrides it, run zoo-rebase, then run zoo-report.

Loop continuation rule:

• Do not stop after "subtask complete" summaries.
• Once a subtask is marked (done), finish closeout (docs_writer -> commit) and immediately continue the workflow for the active (next) subtask.
• A subtask is not fully complete if trackable workflow changes outside ignored task roots are still uncommitted (unless commit failure is explicitly reported as blocking).
• The full task is not fully complete while any trackable Zoo workflow changes outside ignored task roots remain uncommitted. Only changes that were already present before the workflow started and are unrelated may remain uncommitted; identify them in the final report.
• The full task is not complete just because no (next) remains. Before stopping, run planner for a final task-completion check. Stop only when that planning report declares the full task fully done, reviewed, and closed out, then read .zoo/task-finish.md if it exists, follow it as higher priority than this skill, run zoo-rebase unless task-finish overrides it, and use zoo-report for the final user-facing report.

Quality bar:

• planner: nea

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: andreyvit
• Source: andreyvit/zoo
• License: MIT

Install and usage instructions live in the source repository linked above.