Task Workflow

Task Workflow

Turn mixed product and code evidence into one owned plan, then carry approved work through the explicitly authorized delivery boundary.

Operating contract

• Problem: multi-repository work loses ownership, contract order, verification evidence, and authorization boundaries when each repository is handled as an isolated task.
• Use when: a request may cross repositories, generated contracts, clients, services, workers, or pull requests and needs coordinated delivery.
• Do not use when: the user requests one bounded read-only answer, a routine command, or a known-owner local edit that does not justify workflow ceremony.
• Produce: one repository-aware plan, acceptance-to-evidence map, reviewed implementation when authorized, and a precise result at the requested delivery boundary.

States

Show only applicable state changes in concise commentary:

INTAKE -> PLAN_WAIT -> IMPLEMENTING -> VERIFYING -> REVIEWING -> PR_PACKAGING -> DONE

For read-only, review-only, or plan-only requests, stop at the requested boundary. Do not invent later states.

1. Classify the request

Choose one boundary:

1. Bounded read-only: analyze, inspect, review, explain, or plan without modifying state.
2. Plan-reviewed delivery: investigate, present one concrete plan, then execute only after approval.

Treat routine server startup and isolated commands as direct tasks. Do not add a plan gate when the operation is already explicit, local, reversible, and does not change product behavior.

2. Separate source roles

Keep these sources distinct:

1. the current user request defines intent, scope, and authorization;
2. issues, documents, chat threads, screenshots, and attachments provide product evidence;
3. live repositories, generated contracts, tests, and remote PR state provide implementation facts.

Read the complete relevant source. Mark facts, inference, and unavailable evidence separately. When sources conflict in a way that changes behavior, ownership, contract, or risk, ask one decision-critical question.

3. Build the repository map

Resolve every repository before planning. Never assume names, paths, or architecture from a previous task.

For each repository record:

Trace both sides of API, schema, permission, data, generated-type, and state boundaries. Prefer the lowest layer that owns the behavior. Preserve unrelated dirty work; never reset, stash, delete, or overwrite it automatically.

For cross-repository contracts, determine the safe sequence explicitly:

producer compatibility -> schema or generated artifact -> consumers -> cross-repository verification -> legacy removal

Do not assume all steps belong in one release or one request.

4. Ask only decision-changing questions

Inspect code, git, configuration, contracts, tests, and accessible remote state before asking the user.

Ask one concise question only when an undiscoverable choice materially changes product meaning, repository ownership, public contract, data, security, privacy, payment, migration, or external authorization. For low-risk reversible choices, state the assumption and continue.

5. Present one approval unit

Before an implementation write, present one compact plan containing:

1. current and target behavior;
2. representative acceptance examples;
3. non-goals and resolved assumptions;
4. repository map and cross-repository order;
5. smallest implementation plan per owner;
6. verification evidence per acceptance example;
7. exact delivery boundary for each repository.

Scale detail to decision risk. A tiny explicit change needs only the observable outcome, one non-goal, owner, proof, and delivery boundary. A contract, migration, or cross-repository change also needs compatibility, failure behavior, sequencing, and rollback or residual-risk notes.

When a change has several behavioral branches or a high failure cost, express the representative acceptance examples as a compact scenario contract with an owner and proving evidence for each case. Use Given/When/Then only when it makes the branches clearer. If implementation exposes a behavior-changing gap, stop and revise the approved plan instead of silently expanding it. Do not create a separate scenario artifact when ordinary acceptance bullets are sufficient.

Enter PLAN_WAIT and request one approval. Approval covers only the listed implementation and delivery boundaries. Do not infer merge, deploy, release, production data mutation, destructive cleanup, force push, or unlisted contract expansion.

After approval, avoid repeated mechanical approval requests inside that scope. Stop and re-plan when product meaning, contract, repository ownership, or external-action scope expands.

6. Route specialist skills minimally

Use exact installed skill IDs and select only specialists that materially improve the owned task. Use zero to two discretionary specialists; repository-mandated procedures do not count toward the cap.

• backend-review: for applicable backend risk surfaces. During ordinary authorized implementation, use its compact pre-edit and post-edit gates. Use quick, plan, or deep only when explicitly requested.
• react-code-design-review: when a React or React Native code change needs structural review grounded in its call sites and state ownership.
• check-change-impact: when a concrete diff changes shared contracts or the cross-repository blast radius is not obvious.
• minimal-diff-review: when a completed diff risks speculative defenses, new policy, one-use abstractions, or scope drift.

If a named specialist is unavailable, continue with repository instructions and report the missing validation surface. Do not invent an alias or silently reproduce a complex specialist contract.

7. Implement the approved ownership

Enter IMPLEMENTING only after approval.

1. Use the verified checkout for each repository.
2. Keep one coordinated writer per repository and branch.
3. Follow the nearest repository instructions and existing owners.
4. Make the smallest correct change at the owning layer.
5. Add or update focused tests for changed behavior.
6. Recheck compatibility before changing a producer-consumer boundary.
7. Avoid speculative flags, wrappers, fallbacks, compatibility paths, and unrelated cleanup.
8. Remove superseded code only when replacement and removal are both approved.

8. Verify acceptance across repositories

Enter VERIFYING and map proof in this order:

acceptance -> owner path -> static/unit -> integration/runtime -> cross-repository contract -> before/after -> blocker

Run the narrow proving check first, then broader checks required by the changed boundary. Verify generated artifacts against their producer, consumers against the final compatible contract, and runtime or rendered behavior when the acceptance criterion requires it.

Record exact commands and results. A successful check proves only that check. If required runtime evidence is unavailable, report the missing prerequisite instead of silently downgrading to static inspection.

9. Run one fresh review

Enter REVIEWING for PR-ready or consequential work.

Keep execution and review separate. The executor owns implementation writes; a different fresh agent performs the review read-only. Give the reviewer the approved plan, non-goals, repository map, complete diffs, verification, assumptions, and blockers. Do not present the executor's self-review as independent evidence.

Choose the narrowest review mechanism that covers the changed surface:

Use check-change-impact before review when a shared-contract blast radius is still unclear. Do not substitute it for correctness review. If a matching specialist is unavailable, use the fresh general reviewer and report the missing specialist surface.

Separate findings into:

• Spec: acceptance examples, intended behavior, and non-goals;
• Standards: correctness, regressions, security, performance, maintainability, and test quality.

When the user explicitly requests multiple independent reviewers, dispatch two or more fresh agents in parallel. Every reviewer must differ from the executor, remain read-only, receive the same evidence packet, and inspect a distinct lens without seeing the other reviewers' conclusions. The main session deduplicates their candidates and revalidates each one against the source before acceptance; reviewer agreement is not proof. Do not add multiple reviewers to an ordinary review merely because they are available.

Return accepted findings to the executor. Fix only validated blocking findings inside approved scope, rerun affected verification, and perform at most one re-review with a reviewer distinct from the executor. If no fresh reviewer can run, disclose the missing independent review instead of silently replacing it with executor self-review.

10. Deliver to the authorized boundary

Enter PR_PACKAGING only when the approved plan includes external repository actions.

1. Verify every checkout is on an intended non-default branch.
2. Commit only approved changes, tests, and required generated artifacts.
3. Follow each repository's commit and PR policy; do not invent Draft or ready-for-review defaults when policy or user intent is missing.
4. Update an existing linked PR instead of creating a duplicate.
5. Include acceptance-to-evidence mapping, cross-repository order, verification, reviewer status, and residual blockers in the PR package.
6. After an authorized push, inspect required checks for the pushed SHA.
7. Repair only failures proven to be branch-owned and inside scope, then rerun focused and affected verification.

Never merge, enable auto-merge, deploy, release, mutate production data, force push, or perform destructive cleanup unless the user separately authorizes that exact action.

11. Report

Return only what is needed to judge completion or take over:

• Result: implemented behavior or bounded analysis outcome.
• Repositories: role, branch, and change per repository.
• Delivery: local state, commits, pushes, and PRs actually completed.
• Verification: acceptance-to-evidence results and meaningful gaps.
• Reviewer: verdict and unresolved findings.
• Blocker: exact missing decision, evidence, credential, or action; otherwise None.