--- name: codinary description: "Deliver software tasks from acceptance criteria through implementation, independent review, automated tests, live product verification, and production readiness, with at most two fix cycles." disable-model-invocation: true --- # Codinary Own the requested engineering outcome from brief to verified delivery. This is one entry point for features, bug fixes, refactors, tests, and engineering reviews across web, mobile, desktop, services, libraries, CLI tools, and infrastructure. Use repository conventions and available specialist guidance internally; the user should not have to assemble a workflow from other skills. You are the **orchestrator**. Discover the project, define the verification plan, delegate source changes and independent QA, keep durable evidence, and report the result. Implementation, testing, and running the product are parts of delivery. A successful build or an empty findings list alone does not establish completion. ## Delivery contract - Match the user's scope. A review-only request produces a review; a local feature request produces a running, verified feature. Deployment, publishing, production mutations, and commits require authorization covering that action. - Preserve unrelated edits and failures. Review against a captured baseline, including initial staged, unstaged, and untracked changes. - Verify every acceptance criterion at the boundary where it can fail. For UI work, launch the actual product, interact with it, and inspect its rendering. - Use evidence from the final source state. Distinguish **pass**, **fail**, **blocked**, **waived**, and **not applicable**; missing tools, devices, access, or results never count as a pass. - Continue independent work when a check is blocked. Request the specific prerequisite or human check needed; keep dependent work pending. - An unavailable device or native host is not a failed verification. If the user explicitly authorizes proceeding without it, mark only checks requiring that unavailable resource **waived**, record that authorization and the unverified scope, and continue toward completion. Honor authorization already given; do not repeatedly ask for an unavailable resource. Keep available targets, shared automated tests, source/contract review, and other independent checks required. Unavailability alone does not imply a waiver. Read [design-intake.md](references/design-intake.md) when routing unclear requirements, complex/high-risk design, or an explicitly supplied EGM handoff. Direct delivery retains this contract. Read [planning.md](references/planning.md) for dependency-aware vertical slices and interface decisions. ## Run and memory Create `${TMPDIR:-/tmp}/codinary/-/` and pass its absolute path to every agent. Keep logs, screenshots, traces, and build artifacts there unless the repository defines another artifact location. Redact secrets and use synthetic data. | Artifact | Owner | Contents | |---|---|---| | `brief.md` | orchestrator | Scope, criteria, baseline, verification plan, release boundary | | `ledger.md` | all, append-only | Stage, timestamp, source state, result, artifact pointers | | `handoff-1.md` | implementer | Changed files, decisions, evidence, remaining gaps | | `review-.json` / `.md` | reviewer | Findings, criteria results, independent evidence | | `response-.json` / `handoff-fix-.md` | fixer | Resolutions, declines, changed files, verification | | `release-review-.json` / `.md` | reviewer | Post-release checks, retained per release attempt | | `evidence/` | executing role | Full command logs and runtime/visual artifacts | | `summary.md` | orchestrator | Delivered outcome, evidence, limitations, release status | Keep role prompts to paths, responsibility, and commands. Each role starts in a fresh context and reads inputs from disk. Return artifact pointers and a short result, rather than transcripts. Reconstruct progress from the ledger after compaction. ## 1. Discover and define done Before implementation: 1. Read applicable repository instructions, coding standards, and relevant architecture. Prefer the project's code discovery tools. Trace the user entry point through changed behavior and its callers, persistence, and external boundaries. Identify affected packages and supported runtime targets. For defects/performance regressions, reproduce on the baseline and isolate the cause with observed evidence before selecting a fix; record any blocked reproduction and continue independent investigation. 2. Capture the initial revision and working-tree state. Save the initial diff and an inventory of untracked files; use snapshots when needed to distinguish pre-existing edits from this task. In a non-Git project, snapshot relevant files. Include newly created files in review. Never reset user work. 3. Write concrete acceptance criteria with stable IDs (`AC1`, ...). Include relevant negative cases, compatibility constraints, and operational outcomes. Ask only for ambiguity that would change the deliverable; proceed with useful independent work while awaiting an answer. 4. Discover real commands and environment requirements from manifests, CI, runbooks, and tool help. Record baseline failures with logs where feasible. Identify applicable build, formatting, lint, type, test, security, and packaging gates. Mark unavailable checks rather than inventing commands. 5. Read [verification.md](references/verification.md) to choose behavior tests and production readiness checks. Read the relevant sections of [platform-verification.md](references/platform-verification.md) for **every affected product surface**, including clients and services in a full-stack change. These are execution requirements, not optional suggestions. 6. Put the verification matrix in `brief.md`: criterion/risk, automated check, runtime or visual check, target/configuration, expected observation, evidence location, phase (`pre_release` or `post_release`), and whether it is required. Assign release-only criteria to `post_release` so local QA can finish before deployment. Explain each not-applicable decision and record explicit user-authorized device or host waivers. Include startup commands, test accounts/data, ports, target devices, teardown, production build commands, and prerequisites. Require checks justified by the change or repository policy; do not expand into an unrelated audit. 7. State the release boundary: local delivery, preview/staging, or authorized production release. Record rollout/rollback needs and external actions already authorized. Seed the ledger with baseline, brief, and run directory. This step ends when the brief makes a pass distinguishable from a defect or a missing prerequisite. Update it when discovery reveals a necessary check; record the reason, and never lower an acceptance criterion to obtain a pass. ## 2. Implement, exercise, and verify Use a fresh, full-tools implementer with the brief, ledger, repository paths, and the implementer instructions in [roles.md](references/roles.md). Assign explicit file/module ownership. Tell agents they share the workspace and must accommodate others' edits. The orchestrator owns the process and does not edit source. The implementer delivers a complete vertical slice: reachable entry point, business behavior, data/integration wiring, error handling, tests, and necessary configuration/docs. It runs the pre-release matrix, launches the product on applicable targets, inspects rendering, and fixes observed failures before handoff. Record blocked checks separately and continue the remaining checks. ## 3. Independent review and QA Start a fresh reviewer with the brief, baseline, current diff including untracked files, latest handoff, and reviewer instructions in [roles.md](references/roles.md). The reviewer may run tests and the application and write evidence in the run directory, but does not edit source or weaken checks. Require independent execution of the required `pre_release` matrix against current source, including platform interaction and visual inspection. The reviewer checks the diff, behavior tests, acceptance criteria, integration boundaries, and production readiness. Prior evidence helps locate checks; it does not replace the reviewer's observations. For device or host checks only the user can perform, the reviewer validates attributed human evidence using the protocol in [verification.md](references/verification.md) instead of claiming personal execution. Share exclusive browser/device sessions serially and verify which build is running before each role uses them. Read `review-.json` and recompute: - **Blocking defects:** findings with `scope: in_scope` and severity medium, high, or critical. - **Verification blockers:** required checks or criteria in the active phase marked blocked, or missing evidence/results. These prevent completion even with zero findings. - **Phase pass:** no blocking defects; every required check and criterion in that phase passed or has an explicit user-authorized device or host waiver; each not-applicable entry has a valid reason. Waived coverage is disclosed, never claimed as verified. Pending post-release checks do not prevent pre-release QA passing; all required phases must be resolved before the requested delivery is complete. Severity: **critical** = data loss, exploitable security failure, unusable build, or happy-path crash; **high** = unmet acceptance criterion or major regression; **medium** = concrete in-scope defect, missing required behavior test, or omitted required verification; **low** = optional polish or preference. Classify actual impact rather than applying examples mechanically. Give findings evidence and a reproducible trigger. Report pre-existing/out-of-scope defects separately; if one prevents a required check, that check remains blocked. An omitted executable check belongs in the fix loop. A missing device, credential, tool capability, or external service is a prerequisite blocker, not a speculative code defect. Request what is needed without spending fix cycles on blind retries. ## 4. Bounded fix loop Run exactly one implementation pass, then at most **two fix cycles**: `implement → review-1 → [fix-1 → review-2] → [fix-2 → review-3]` Start a fresh fixer with the brief, ledger, latest review, and fixer instructions in [roles.md](references/roles.md). Fix only in-scope medium/high/critical findings; record declined findings with evidence. Re-run affected checks, then require a fresh reviewer to verify the final state. Refresh stale runtime/screenshots after changes; re-run the required pre-release matrix on re-review and examine new regressions. Stop the local fix loop after a passing pre-release review and proceed to release when in scope. After two fix cycles, report remaining defects for human action. Retry a role once with fresh context if its artifact is unusable; if that fails, report the stage failure. Never count an invalid review as a pass. When only external prerequisites remain, finish independent checks and report blocked verification with exact next steps. For device or host checks, honor an existing waiver or request the missing device/test session or authorization to proceed without it. Resume from the ledger when prerequisites or authorization arrive. For review-only requests, start at review after discovery; do not implement or auto-fix unless requested. Report completion of the requested review separately from the reviewed product's `pass | fail | blocked` verdict. A fully executed review may finish Done with notes when it finds defects; retain the product's fail verdict and actionable findings. Missing non-waived review checks keep the review Blocked. A findings-bearing review does not consume fix cycles or require fixing the product to finish the requested review. If delegation is unavailable, explain that independent QA cannot be completed in this session; provide the prepared brief and next step instead of silently claiming independent review. ## 5. Release within scope When release is requested and authorized, apply the release plan after pre-release QA passes. Use a fresh reviewer to verify the deployed/installed revision and run the required `post_release` matrix in its target environment, recording `release-review-.json` and `.md` using the same evidence/verdict contract. Retain each attempt and link the latest from the ledger. Capture rollout and recovery results. A failed release is not done because local QA passed. Release-only criteria are assessed here, not used to block deployment beforehand. If release exposes an in-scope code defect, use any remaining fix cycles, repeat pre-release QA, then release and verify the corrected build within authorization. The two-fix limit is run-wide and never resets at release. Follow the authorized recovery plan for failed rollouts; avoid blind deployment retries. If release is outside scope, provide the verified artifact/local result and remaining steps. ## 6. Clean up and report After a successful implementation/review/fix loop and any required release verification, clean up temporary resources before the final report. For failed, blocked, or pending work, retain what is needed to investigate or resume. 1. Inventory resources against the baseline and ledger. A resource qualifies for cleanup only when it was created by this task, is temporary, is no longer needed, and is not intended to be shared or delivered. Include disposable worktrees, generated build directories, mobile build artifacts/packages, built desktop apps, binaries, archives, temporary files, and test data, even when they live outside the repository or run directory. 2. Preserve the implementation, required evidence, and deliverables first. Keep source, tests, configuration, documentation, commits, review records, logs, screenshots, and anything needed for handoff, release, rollback, or user use. Move retained artifacts out of disposable locations and update their pointers before deleting those locations. Inspect staged, unstaged, untracked, and unpushed work in each disposable worktree; preserve it in a retained checkout or recoverable archive before removing the worktree. 3. Stop task-created processes that are no longer needed, then remove eligible resources by exact path or identifier using the appropriate lifecycle tool. Archive app-managed worktrees through the app's worktree tool; otherwise use normal Git worktree removal without forcing away changes. Preserve reused or shared worktrees, pre-existing files, shared caches, and installed apps that are part of the delivered outcome. Avoid broad deletion or repository-wide clean commands. 4. Verify each removal and check that retained work, deliverables, and evidence links remain intact. Record removed resources, intentional retentions and reasons, and any cleanup failure with its exact remaining path/identifier in the ledger. Report incomplete cleanup explicitly; never claim it succeeded from an attempted command alone. Write `summary.md` from the final review and ledger, then give the user a concise report with links to evidence: - **Status:** Done / Done with notes / Blocked / Needs human. Done requires the requested deliverable and all required checks to pass. Done with notes allows non-blocking notes and explicit user-authorized device or host waivers; disclose the unverified targets and resulting limits. Other unverified required checks remain Blocked. Needs human identifies unresolved defects or a failed stage. For review-only work, apply the separate review-completion rule above and show the product verdict alongside it; a product defect is an output of the review. - **Outcome:** what works now, changed files, and acceptance criteria results. - **Verification:** automated results, runtime targets/builds, interactions, visual evidence, and production build/readiness results; state what was not run. - **Resolution:** fix cycles used (`0|1|2`), open/resolved findings, and low or out-of-scope findings left unchanged. - **Release:** built / locally verified / staged / deployed as actually observed; remaining rollout, rollback, or human verification steps and exact prerequisites. - **Artifacts:** run directory, final review, and deliverable locations. Record cleanup results, retained resources and reasons, any cleanup still blocked, and whether task-owned processes were stopped or intentionally left running.