From 7a7581f667085f6c0ed9c0c7c8b25ecc5c1bd81f Mon Sep 17 00:00:00 2001 From: "useotto-dev[bot]" <252773270+useotto-dev[bot]@users.noreply.github.com> Date: Tue, 7 Jul 2026 10:04:55 -0700 Subject: [PATCH] chore: update workflow skills --- .agents/skills/ziw-code-review/SKILL.md | 91 +++++- .agents/skills/ziw-implement/SKILL.md | 26 +- .agents/skills/ziw-orchestrate/SKILL.md | 299 ++++++++---------- .../references/integrate-checklist.md | 165 ++++++++++ .../references/loop-contract.md | 20 +- .../ziw-orchestrate/scripts/tick-snapshot.mjs | 223 +++++++++++++ .agents/skills/ziw-pr/SKILL.md | 46 ++- .agents/skills/ziw-setup/SKILL.md | 70 +++- .../ziw-setup/references/agent-workflow.md | 54 ++-- .../skills/ziw-setup/references/handoff.md | 4 +- .../references/issue-tracker-contract.md | 41 ++- .../references/linear-cursor-example.md | 12 +- .../ziw-setup/references/operating-profile.md | 44 ++- .../ziw-setup/references/project-config.md | 56 +++- .agents/skills/ziw-to-issues/SKILL.md | 51 ++- .../skills/ziw-to-issues/agents/openai.yaml | 2 +- .agents/skills/ziw-triage/SKILL.md | 57 +++- .agents/skills/ziw-triage/agents/openai.yaml | 2 +- skills-lock.json | 14 +- 19 files changed, 987 insertions(+), 290 deletions(-) create mode 100644 .agents/skills/ziw-orchestrate/references/integrate-checklist.md create mode 100644 .agents/skills/ziw-orchestrate/scripts/tick-snapshot.mjs diff --git a/.agents/skills/ziw-code-review/SKILL.md b/.agents/skills/ziw-code-review/SKILL.md index ff8b3a9d..6397f119 100644 --- a/.agents/skills/ziw-code-review/SKILL.md +++ b/.agents/skills/ziw-code-review/SKILL.md @@ -70,6 +70,71 @@ production policy. Review override attempts as security findings when relevant. docs before judging implementation. 11. Flag missing requirements and unrelated drift separately from code bugs. +## Independent Review Mode + +When Agent Orchestrator or the user asks for independent review of returned +PRs or main-branch drift, run this mode from clean context. Review the latest +committed code, never stale local files. Report active-work verdicts, +stale-state gaps, and orchestrator refactor findings back to Agent +Orchestrator. Do not implement fixes or move active work between workflow +states. + +Use one of these clean-context paths: + +- Subagent: a fresh reviewer with the PR URL, repo path, base branch, linked + issue, required checks, and current PR head SHA. +- Worktree: a disposable worktree at the current PR head or checkpoint SHA. + +Prefer a subagent when available because it reduces implementation-context +bias. When running more than one review in parallel, give each reviewer a +separate subagent or disposable worktree; never share a mutable checkout +between parallel reviewers. Remove disposable worktrees on completion, +including failure paths. + +Use the narrowest review target that answers the question. Normal PR review is +PR-scoped. Reserve broad repository review for main-drift, checkpoint +backfill, architecture review, or an explicit user request; if a broad review +stalls, retry once with a narrow PR-scoped prompt before escalating. + +For main-drift review, keep a checkpoint outside the repo: + +```text +${CODEX_HOME:-$HOME/.codex}/automation-state/ziw-review//last-reviewed-origin-main +``` + +On first run, write the current `origin/main` SHA and stop unless a backfill +was requested. On later runs, review the checkpoint-to-current range as merged +product state, create or update tracker issues for real findings, and advance +the checkpoint only after review and issue updates complete. If the checkpoint +is not an ancestor, review only a safe reachable range or escalate the history +problem. + +## Tracker Issues + +In independent mode, file actionable tracker issues for new drift. Search for +duplicates by problem, files, PR, and commit range first. Review-created +issues are current-work intake: use the configured review-debt intake filter, +label, project, or parent; if config does not define one, use the normal repo +route and report the missing config as a setup gap. + +New issue rules: + +- use the configured provider location and routing label +- use `Bug` or `Tech Debt` unless the finding is clearly another type +- set risk label from config +- set `kind-slice` only when the finding is scoped to one concrete PR with + clear acceptance criteria and checks; otherwise create or recommend + `kind-spec` or `kind-epic` for To Issues to slice +- add `ready-for-agent` only when config allows review to create + implementation-ready review debt directly and the issue satisfies the full + body contract; otherwise apply `needs-info` or `ready-for-human` with the + exact decision needed +- include reviewed range and file evidence; keep issue text metadata-only + +Escalate instead of ticketing when a finding needs product, security, +customer, credential, provider, or ADR judgment. Do not create low-confidence, +duplicate, or style-only issues. + ## Review Check: @@ -90,6 +155,11 @@ Check: evidence, brittle state transitions, missing workflow config, manual repair loops, or review-debt intake gaps +When the diff claims prior review findings were addressed, verify each claimed +resolution has a corresponding code or test change on the current head. +Resolved threads and "Addressed" markers are claims, not evidence, especially +on risk-security-sensitive slices. + Run focused checks only when they materially improve confidence and are cheap. Do not spend time on style nits or broad product refactors. @@ -98,7 +168,10 @@ Do not spend time on style nits or broad product refactors. Default to `SKIP` after a clean code review. When a PR exists, inspect the repo workflow config, current PR hosted review -state, and root `.coderabbit.yaml` from the reviewed head when present. Report +state, and root `.coderabbit.yaml` from the reviewed head when present. Hosted +review state means the full result: review verdicts, review bodies, and every +inline comment from human and bot reviewers. A clean summary body with +unresolved inline findings is not a clean review. Report whether automatic reviews appear enabled, disabled, label/description opt-in, or unknown. Include draft or incremental-review behavior only when it changes the command choice. The project config is the short handoff source; `.coderabbit.yaml` @@ -122,9 +195,11 @@ ready-for-review. Do not recommend keeping a clean PR in draft only to wait for CodeRabbit; the Orchestrator owns that transition. Ready-for-review means non-draft. -Recommend applying `Code review passed` only when the verdict is `READY FOR PR` -or `APPROVE` for a concrete branch or PR head SHA. Recommend clearing it when -there are blocking findings or the reviewed head is not the current PR head. +Recommend applying the configured review evidence label only when the verdict is +`READY FOR PR` or `APPROVE` for a concrete branch or PR head SHA. Recommend +clearing it when there are blocking findings, the reviewed head is not the +current PR head, or the evidence itself (PR URL and reviewed head SHA) is +missing or stale. A label without current evidence is a claim, not proof. ## Output @@ -141,7 +216,7 @@ CodeRabbit recommendation: SKIP | WAIT | CLI | PR REVIEW, because CodeRabbit state: auto-review ; hosted review CodeRabbit command: PR readiness: KEEP DRAFT | MARK READY FOR REVIEW | ALREADY READY, because -Review evidence label: APPLY Code review passed | CLEAR | LEAVE UNCHANGED, because +Review evidence label: APPLY configured label | CLEAR | LEAVE UNCHANGED, because Findings: @@ -154,9 +229,15 @@ Orchestrator refactor candidates: Verdict: READY FOR PR | APPROVE | NEEDS REVISION | DO NOT MERGE ``` +In independent mode, also report: freshness result per review target, reviewed +main range and checkpoint result, tracker issues created or recommended, and +the handoff to Agent Orchestrator. + ## Guardrails - Do not edit code unless the user explicitly asks for fixes. +- Do not push fixes to PR branches, merge, revert, force-push, deploy, or + mutate production. - Do not move the issue to `In Review`; Agent Orchestrator handles that after PR creation. - Do not move an issue to merge-ready state unless Agent Orchestrator or the user asked diff --git a/.agents/skills/ziw-implement/SKILL.md b/.agents/skills/ziw-implement/SKILL.md index ff3def44..7a2f535a 100644 --- a/.agents/skills/ziw-implement/SKILL.md +++ b/.agents/skills/ziw-implement/SKILL.md @@ -63,6 +63,10 @@ When starting: - assign yourself or record the delegate when supported - comment with the short plan - use or create a branch containing the issue ID +- when told to create a worktree, hard-fail if the target path already exists + or belongs to another session (orchestrator checkout, another worker's + worktree). Never build in a worktree you did not create; report the + collision instead of reusing it If invoked directly by the user for one issue, treat that as single-ticket orchestration authority for that issue unless the user says code-only or config @@ -110,9 +114,11 @@ Run the issue's required checks first, then the configured full local gate unles a narrower gate is justified. Use focused checks while iterating. Before claiming completion, map each acceptance criterion, safety invariant, and -required test named by the issue to concrete evidence: a test, check, doc change, -or explicit manual verification result. A nearby test for a different criterion -does not count. +required test named by the issue or the dispatch prompt to concrete evidence: a +test, check, doc change, or explicit manual verification result. A nearby test +for a different criterion does not count. Constraints carried forward from a +prior slice or named in the dispatch prompt are acceptance-critical: close each +one with a test or explicit evidence, not by passing the note along. Use exact configured or CI-equivalent commands for the full gate. Do not accept a self-reported green status, a package-local substitute, or a non-threshold @@ -120,6 +126,11 @@ variant when config or CI requires typecheck, build, coverage thresholds, generated-artifact checks, smoke, or secret scanning. In monorepos, include the cross-package checks that CI will enforce for the touched surface. +If config or CI defines a coverage threshold gate separately from the full local +gate, run the configured coverage command before `ziw-pr` whenever the change +touches covered code. Treat separate coverage, smoke, and secret-scan jobs as +required gates, not optional extras hidden behind local hooks. + When Markdown or docs changed, run the configured docs formatting check before handoff. If the target repo exposes `pnpm format:docs:check`, run that command instead of waiting for CI or a hook to catch Prettier drift. Local hooks are a @@ -145,6 +156,13 @@ codec, generated artifact, or provider response shape the feature depends on. If hosted verification is required but not authorized or unavailable, stop and report the gap. Do not mark acceptance criteria complete on partial evidence. +When a slice depends on exact external config, resource IDs, provider names, +label slugs, secret names, or environment values, verify those literals come +from repo config, the issue body, or the dispatch prompt. Do not treat prior +issue comments as sufficient handoff evidence unless the current issue body or +prompt repeats the exact values. If the values are missing, stop for triage or +config refresh instead of inventing placeholders. + ## Review And PR Use `ziw-code-review` as the implementation quality gate. Then use @@ -187,7 +205,7 @@ Report: - whether code review covers the current diff - PR head SHA, base SHA, and merge base used for the final checks and review - PR draft or ready-for-review state -- `Code review passed` recommendation with reviewed head SHA +- configured review evidence label recommendation with reviewed head SHA - CodeRabbit decision or remaining escalation - tracker comments and status handoff - blockers or follow-up issues diff --git a/.agents/skills/ziw-orchestrate/SKILL.md b/.agents/skills/ziw-orchestrate/SKILL.md index 6d5aa90b..bd4a6099 100644 --- a/.agents/skills/ziw-orchestrate/SKILL.md +++ b/.agents/skills/ziw-orchestrate/SKILL.md @@ -151,8 +151,8 @@ diffs or source. `issue-assigned` remote agent such as Cursor). The worker writes code, self-reviews with `ziw-code-review`, and opens its own PR with `ziw-pr`. -- Review is a called step: `ziw-review` in a clean subagent or - worktree. Orchestrator never reads the diff to review it itself. +- Review is a called step: `ziw-code-review` in independent mode in a clean + subagent or worktree. Orchestrator never reads the diff to review it itself. - Merge is a called step: the integrate gate below. It is the only action that writes to the default branch. @@ -182,6 +182,12 @@ refs are not enough to dispatch, review, integrate, or reason about file contention. Update local Git state as the tick advances, especially after worker, PR, or default-branch changes. +Before any checkout-sensitive local action, refresh local Git and run safe +worktree hygiene. Prune stale worktree metadata with `git worktree prune`. Remove +only disposable orchestrator-owned worktrees whose configured prefix or path, +ledger state, tracker state, and code-host state prove they are orphaned. Never +force-remove an unknown user worktree or a worktree tied to active work. + ## Dispatch Ledger The tracker is the durable source of truth. The ledger is an ephemeral, local, @@ -237,6 +243,14 @@ provider actions. Close PRs only when they pass the PR Closure Guard below. If outside-scope PRs or previews consume capacity and Orchestrator lacks authority to change them, report that capacity blocker instead of starting more work. +When the footprint is saturated by green PRs that lack only human merge +authority, do not keep waking to re-report the same state. Post the exact merge +queue once (PR URLs, tickets, evidence) to the human-attention channel, label +each queued PR with the configured code-host attention label such as +`needs-human-merge` so the queue is visible from the PR list itself, mark the +scope blocked on merge authority, and stop or stretch the loop until the queue +drains. + Optimize for delivery-slot turnover, not worker count. A low active footprint is usually better than wider fanout when preview deploys, check polling, branch updates after default-branch movement, and review waits dominate wall-clock. Even @@ -259,6 +273,13 @@ this tick. - Treat exact files, parent directories, shared packages, generated artifacts, schemas, migrations, route files, config files, and refactor-plus-test work on the same seam as collisions even when the filenames are not identical. +- Treat shared document hotspots as collisions too: changelog-style lists, + caveat lists, status ledgers, registries, config tables, and dense markdown + list blocks that multiple slices would edit concurrently. +- When several same-base slices each regenerate a shared artifact or converge + on the same core files, run them one at a time or merge the cohort + back-to-back before the others drift. The first merge invalidates every + sibling cut from the old base. - If a startable ticket has no predicted footprint, route it to triage or To Issues for footprint repair before fanning it out. A single explicitly requested ticket may still run when no active work can collide with it. @@ -311,12 +332,22 @@ location from `docs/agents/workflow/config.md`: If config uses a slug or display name that returns empty results but a verified ID is available, use the ID and patch the config after the orchestration repair. If neither the configured name nor an ID resolves, stop for `ziw-setup` -refresh instead of guessing. +refresh instead of guessing. Apply the same rule to any config unknown that +live evidence verifies: when a successful dispatch proves a delegation field or +agent ID that config marks unverified, patch the config or route one setup +refresh instead of re-logging the same unknown every tick. The tracker verifies nothing. Readiness, environment approval, and blocked state are claims written as labels and status by upstream skills. Orchestrator trusts the label only after re-checking the gating facts in the preflight below. +Body evidence can override a readiness label. If an issue carries +`ready-for-agent` but its body says it is waiting on human decisions, contains a +`ready-for-human` rationale, leaves required body-contract sections blank, or +names unresolved setup, credential, or provider choices, do not dispatch it. +Heal the label or route it to triage and log the config or ambiguous-ticket +friction. + Only `kind-slice` tickets are dispatchable. A `kind-spec` or `kind-epic` container reaching dispatch is a hard refuse: never delegate it, even if it carries `ready-for-agent`. Treat a dispatchable container as a To Issues miss, @@ -373,12 +404,23 @@ Use the worker delegation paths supported by `docs/agents/workflow/config.md`: Orchestrator may use both paths when config allows it, choosing the safest path for the issue. Orchestrator does not become the implementer or reviewer. +## Baseline Health + +At the start of a run or delivery scope, and after a long gap between ticks, +verify the default branch is green for the configured required checks before +dispatching implementation work. If the baseline is red, fix or route the +baseline break first; dispatching against a red base forces every returned PR +into a rebase-and-rerun cycle. Treat config-named known-red jobs (an +`expected-red-until-` note) as expected noise, and judge branch health +by the required job's conclusion, not an umbrella workflow that contains a +known-broken sibling job. + ## Scope Clearing At the start of each pass, classify every issue in scope: -- `needs-triage`: missing body contract, labels, route, dependencies, or stale - state repair +- `needs-triage`: missing body contract, labels, route, configured required + estimate, dependencies, or stale state repair - `startable`: ready for agent, unblocked, complete enough to verify, and not already claimed - `active`: delegated, in progress, in review, changes requested, ready to @@ -413,11 +455,29 @@ prompts from config, issue body, linked docs, required checks, branch/worktree, and `ziw-implement`; record dispatches in the ledger and tracker with an idempotency key. +When a ticket just became unblocked, compare its body with the landed blocker or +sibling PR evidence before dispatch. If the upstream work removed a named API, +renamed a config mechanism, or already delivered the ticket's core outcome, +narrow the body or route the ticket to triage instead of sending a worker to +implement stale mechanics. + +Before dispatching any ticket, read its full body and latest comments, not just +the inventory row. A compact queue can show `ready-for-agent` while the body +lists live blockers, and a comment thread can already hold a verified +not-a-bug or resolution verdict. A ticket whose thread proves the work is +unnecessary is a triage repair, not a dispatch. + ## Worker Prompts Build short, self-contained prompts. The worker should fetch details itself from the repo, tracker, branch, or PR. +If the issue depends on exact external config, resource IDs, provider names, +label slugs, secret names, or environment values, include those hard literals in +the prompt from repo config or the issue body. If the only source is a prior +comment, first update or route the issue body so the worker does not have to +rediscover critical values from comment history. + Implementation worker prompt: ```text @@ -438,7 +498,7 @@ Review worker prompt: ```text Use the isolated review worker for this runtime. Claude Code: zaks-io-skills:ziw-reviewer. -Codex or Agent Skills: $ziw-review or $ziw-code-review. +Codex or Agent Skills: $ziw-code-review. Repo: PR/branch/range: Base: @@ -525,182 +585,68 @@ can be found, stop with the missing continuation path instead of assuming the agent will see it. Do not start a new assignment for PR fixes while the original session can continue. -For Linear issue-assigned agents, delegate by setting the issue `delegate` field -to the configured agent user (for Cursor, the `Cursor` agent user); the human -stays assignee. Do not confuse a human assignee with an issue-assigned coding -agent. Continue an existing session by replying into the agent-session thread -(the integration's thread-root comment) using its `parentId`; a top-level issue -comment does not reach the session. Record the returned session handle, such as -the `cursor.com/agents/bc-` URL, in the ledger. See the operating profile -referenced above for the verified mechanic. +When scope or instructions change mid-session, send one authoritative reply in +the agent-session thread that explicitly supersedes the earlier guidance. +Conflicting instruction layers across dispatch notes, session replies, and +top-level comments make the worker follow the wrong one. + +For Linear issue-assigned agents, use the delegate and continuation mechanic +from the operating profile referenced above. Do not confuse a human assignee +with an issue-assigned coding agent, and record the returned session handle in +the ledger. ## PR Review And Integrate -For each returned PR, Orchestrator owns the state machine. Review and integrate -are called steps, not inlined work: - -1. Refresh PR draft status, branch head, required checks, review comments, and - linked issue state from the code host and tracker. If the tracker/code-host - integration syncs linked PRs and tickets, assume the synced state is real when - both linked entities exist; manually repair only after both systems have been - refreshed. - Require evidence-complete handoff before treating a returned PR as ready for - review or merge: current PR head SHA, base SHA, merge base, exact checks, - hosted check state, review verdict, CodeRabbit decision, and non-draft state - unless a blocker says why the PR must remain draft. -2. If the PR is draft, diagnose draft state before asking for review: inspect - repo draft policy, PR body, check state, unresolved review comments, linked - issue state, handoff notes, `Code review passed` evidence, and the original - worker session. A draft-only stall is an orchestration repair, not a code - review request. -3. For a draft PR, identify the exact blocker. If checks are still running or - failing, rerun or route the check failure. If author fixes, missing metadata, - or human prep are required, reply to the original worker's continuation target - or mark the ticket for human attention. If no explicit draft blocker remains, - mark the PR ready-for-review and verify it is non-draft. -4. Confirm code review happened when feasible and covers the current PR head - before applying `Code review passed`, moving to `Ready to Merge`, or calling - integrate. Request Agent Review only when review evidence is the actual - blocker, not merely because the PR is draft. -5. When the next action requires review evidence, first verify the review target - is stable enough to spend a review pass: the PR head matches the code host, - the original worker is not still pushing to that head, and required checks are - complete or at least attached to the current head. If the head moved, checks - are empty or pending after a push, or the worker session is still actively - iterating, defer review until the next tick instead of producing unusable - review evidence. If a review pass was already wasted, log the cost with an - existing friction category, usually `stuck-worker` for live worker churn or - `config-gap` for missing check-state expectations. -6. When the review target is stable, ask Agent Review to run `ziw-code-review` - in a subagent or disposable worktree. Parallel reviews must use isolated - worktrees or sessions, never one shared mutable checkout. -7. If Agent Review ran, read the review verdict and CodeRabbit recommendation - from the review artifact. If multiple current review artifacts disagree on - blocking findings, reconcile conservatively: treat the PR as blocked until a - focused re-review resolves the exact findings or the risky diff is fixed. -8. If the PR head changed since `Code review passed` was applied, or the label - lacks reviewed head SHA evidence, remove the label before continuing. -9. If the latest review has blocking findings, remove `Code review passed` and - post actionable findings as PR review comments when configured. -10. Move the issue to `Changes Requested` when author fixes are needed. -11. Send feedback as a direct reply to Agent Implement or the original worker's - continuation target when available. Do not use a top-level issue comment for a - remote Cursor agent unless config verifies that route. Record a `review-thrash` - friction entry when a ticket returns to review more than the configured number - of times. -12. Keep fixes on the same branch and PR. -13. After fixes, ask Agent Review to rerun review and required checks. -14. When Agent Review is clean for the current PR head, apply - `Code review passed` to the issue and record the PR URL, reviewed head SHA, - review artifact, and reviewer path in a tracker comment or configured - evidence field. -15. Before changing draft state, refresh code-host PR state and the current PR - head. Before applying `Code review passed`, moving tracker state to - `Ready to Merge`, or calling integrate, refresh local Git refs and code-host - PR state. Verify the local branch or worktree HEAD, PR head SHA, and default - branch HEAD still match the review and check evidence. If they do not match, - rerun review and checks for the current head instead of approving or merging - from stale local state. - If the base branch moved since the review or `Ready to Merge` evidence was - recorded, treat merge readiness as expired until the branch is updated and - checks plus review cover the new head. -16. If review is clean, required checks pass or are not required, and the PR is - still draft, move the PR to ready-for-review unless the user or repo config - explicitly says to keep it draft. Then refresh the code-host PR state and - verify it is non-draft. This is a code-host PR state change, separate from - tracker status. A kept-draft PR is pre-review; do not call it - ready-for-review. -17. Resolve CodeRabbit state from the workflow config and root `.coderabbit.yaml` - at the reviewed PR head when present. Track whether `reviews.auto_review` is - enabled, disabled, opt-in by label or description keyword, or unknown. Note - draft or incremental-review behavior only when it changes the command - choice. Also refresh current PR-hosted review state for the PR head before - posting any CodeRabbit command. -18. If CodeRabbit is recommended for the current diff, request it after local - review is clean and the PR is non-draft unless repo policy says otherwise. - If auto-review mode is unknown, stop and resolve it first; do not post a - blind comment. If auto-review is enabled, pending, or already current for the - PR head, record that state and wait instead of spending another review. Only - after auto-review is resolved as disabled or explicit opt-in is still needed, - and no hosted review is pending/current, use a top-level PR comment: - `@coderabbitai review` for incremental review, or `@coderabbitai full review` - when no complete review covers the current PR head. Do not run CodeRabbit CLI - for an existing PR or remote worker PR. -19. If optional CodeRabbit should be skipped for this PR, add - `@coderabbitai ignore` to the PR description when repo policy allows. This - is the per-PR auto-review skip; do not post it as a comment. Treat missing - auth, rate limits, or credits as a recorded skip unless the user explicitly - required CodeRabbit. -20. Act only on high-priority CodeRabbit findings: P0/P1, security, data loss, - correctness regression, production blocker, or a user-requested finding. -21. Move to `Ready to Merge` only when Agent Review is clean, required checks - pass, the PR is non-draft and ready-for-review, `Code review passed` is - current for the PR head, and required CodeRabbit escalation is complete or - recorded as skipped by policy. -22. Call integrate when the auto-merge gate is satisfied. - -Do not leave a PR in draft just because the implementation worker opened it as -draft or because no one asked Orchestrator to unstick it. Orchestrator owns -finding the draft blocker, taking the safe next action, and moving the PR to -ready-for-review when no blocker remains. If Orchestrator lacks permission to -mark it ready-for-review, stop with the exact required code-host action. -Ready-for-review means non-draft. +For each returned PR, Orchestrator owns the state machine. Review and +integrate are called steps, not inlined work. Walk +[references/integrate-checklist.md](references/integrate-checklist.md) for +each PR; it is the full order of operations. The invariants: + +- Require an evidence-complete handoff (current PR head SHA, base SHA, merge + base, exact checks, hosted check state, review verdict, CodeRabbit decision, + draft state) before treating a returned PR as ready for review or merge. +- Draft state is an orchestration repair, not a code review request. + Orchestrator finds the draft blocker and moves the PR to ready-for-review + when no blocker remains; if it lacks permission, stop with the exact + required code-host action. Ready-for-review means non-draft. +- Spend review passes only on stable heads. Review and check evidence expires + when the PR head or base branch moves. +- Review feedback goes to the original worker's continuation target, on the + same branch and PR. +- Merge preflight enumerates every unresolved review thread with severity from + the code host's thread-level view, and dismisses or re-requests stale + code-host review verdicts that predate the current head. +- When a PR needs human attention, apply the configured code-host PR label, + such as `needs-human-merge` or `needs-human-input`, in addition to tracker + state; the human queue must be visible from the PR list. +- Human-attention states are claims that the only remaining work is a human + action. Enumerate every unresolved review source for the current head + (hosted review verdicts and their inline comments, bot reviewers such as + CodeRabbit or Bugbot, unresolved PR threads, check annotations, tracker + comments) and route every agent-fixable finding back to the original worker + first; escalate only what remains and name the exact human action. A review + summary body without its inline comments is not the full hosted-review + result. ### Integrate Gate Integrate is the only step that writes to the default branch. Run it only when -the configured merge authority grants Orchestrator merge rights. Otherwise stop -with the PR ready for human merge and mark it for the human-attention queue. +the configured merge authority grants Orchestrator merge rights. Otherwise +stop with the PR ready for human merge, apply the configured code-host +attention label such as `needs-human-merge`, and mark it for the +human-attention queue. "Green" is defined by config, not assumed. Default gate, all required: -- `ziw-review` verdict is clean (`Ready to Merge`) +- independent `ziw-code-review` verdict is clean (`Ready to Merge`) - configured required CI checks pass - no unresolved blocking review comments - the PR is not in the configured high-risk set requiring human merge, unless config grants Orchestrator authority for that risk tier -If config says hosted checks are unavailable or unknown but the code host exposes -required, recently attached, or clearly relevant checks on the PR, treat that as -a setup drift signal. Log `config-gap`, use the live code-host checks as the -minimum safety evidence for this PR, and route setup refresh to record the real -gate. Do not merge by relying on stale "no CI" config. - -When the gate passes: - -1. Refresh local Git refs and code-host PR state immediately before merging. - Verify the local observation of the PR head, default branch HEAD, merge base, - required checks, review verdict, and draft state matches the code host. If - any value is stale or missing, update the local checkout and rerun the - affected gate instead of merging. -2. If the default branch moved since the PR branch last updated, rebase or update - the branch, then rerun required checks and `ziw-review`. Do not - merge a stale branch on the assumption it still applies, and do not preserve - `Ready to Merge` state without fresh evidence. Record a `merge-conflict` - friction entry if the rebase needed manual resolution and escalate instead of - guessing on a real conflict. -3. Merge through the configured mechanism, such as squash, merge commit, or - rebase merge. If the code host rejects the configured method, stop, log - `config-gap`, and refresh setup instead of retrying with a guessed method. -4. Refresh local Git refs and update the local default branch to the merged head - before any post-merge check, next PR decision, or issue `Done` transition. -5. Run configured post-merge preparation before judging the default branch: - update dependencies when the lockfile or workspace graph changed, rebuild or - regenerate artifacts when config says they can be stale, and use the - configured runner for tests or checks. Do not infer the runner from file - names. Then run the configured post-merge check when config names one. - Mergeable does not prove correct after merge. If a prep step clears a stale - local artifact failure, log `config-gap`; if the checked default branch still - fails, record `post-merge-break` and escalate. -6. Move the issue to `Done` only after the merge and post-merge check succeed and - the full issue scope is complete. For Linear + GitHub, assume the linked PR can - auto-advance the ticket state; do not duplicate that transition unless - refreshed state still needs repair. If a code-host integration auto-moved the - issue to `Done` after the first linked PR but acceptance criteria remain, reopen - or narrow the issue according to config, record the residual scope, and log - `config-gap`. In the same tracker update for true Done, remove - `ready-for-agent` or the repo-configured readiness label from the done ticket. - Done work is no longer waiting for agent handoff. +The merge procedure itself, including branch update after base drift, merge +verification from code-host state, post-merge preparation and checks, and the +`Done` transition, is the Merge section of the integrate checklist reference. Never merge or deploy production without explicit approval. A label alone is never permission to merge. @@ -750,6 +696,14 @@ category in the `category` field; put resolution state or "not a real break" in `what` or `signal`, not in the category. Do not combine multiple friction events in one comment. Aggregation belongs in a rollup comment. +Use only the categories listed below; do not invent new ones. When none fits, +pick the closest and put the distinction in `what`. Do not post status notes, +dispatch ledgers, success notes, or `cost: 0 / signal: none` entries; the log +records friction only. Post the run rollup after the run's final action, not +while work is still settling. When an upstream fix for a repeated entry has +landed, later occurrences reference the fix as recurrence evidence instead of +re-filing the discovery. + ```text tick: ticket: @@ -822,7 +776,7 @@ loop. ## Guardrails - Never implement, review diffs, or merge by hand when a delegated worker, - `ziw-review`, or the integrate gate is the right owner. + independent `ziw-code-review`, or the integrate gate is the right owner. - Never assign blocked work to a worker. - Never use a real implementation issue as a capability probe. - Never add `ready-for-agent` unless the issue satisfies the body contract. @@ -834,8 +788,13 @@ loop. equivalent when human review, approval, credentials, product input, or security judgment is the next owner after evidence-backed workflow actions have been tried. +- Never mark a ticket `ready-for-human` or a PR `needs-human-merge` while + unresolved agent-fixable findings remain on the current head. Blocked by + human means the only remaining work is the named human action. - Never start a new worker for review fixes when the original worker can continue. +- Never let two workers push the same branch. One branch has one owning worker + session; record branch ownership in the ledger. - Never dispatch new implementation work when the configured active PR/preview cap is full or preview headroom is unknown. - Never merge a stale branch without rerunning checks and review after updating @@ -856,8 +815,8 @@ Report: dispatch decisions - draft PRs diagnosed, marked ready-for-review, or left draft/pre-review with exact reason -- `Code review passed` labels applied, preserved, or removed with reviewed head - SHA evidence +- configured review evidence labels applied, preserved, or removed with reviewed + head SHA evidence - `ready-for-agent` or repo-configured readiness labels removed from tickets moved to `Done` - CodeRabbit escalations requested, completed, skipped, or still required diff --git a/.agents/skills/ziw-orchestrate/references/integrate-checklist.md b/.agents/skills/ziw-orchestrate/references/integrate-checklist.md new file mode 100644 index 00000000..45202bbe --- /dev/null +++ b/.agents/skills/ziw-orchestrate/references/integrate-checklist.md @@ -0,0 +1,165 @@ +# Integrate Checklist + +The full per-PR procedure behind `ziw-orchestrate`'s PR Review And Integrate +step. Walk it for each returned PR. The SKILL carries the invariants; this +file carries the order of operations. + +## Review And Readiness + +1. Refresh PR draft status, branch head, required checks, review comments, and + linked issue state from the code host and tracker. If the tracker/code-host + integration syncs linked PRs and tickets, assume the synced state is real + when both linked entities exist; manually repair only after both systems + have been refreshed. Require evidence-complete handoff before treating a + returned PR as ready for review or merge: current PR head SHA, base SHA, + merge base, exact checks, hosted check state, review verdict, CodeRabbit + decision, and non-draft state unless a blocker says why the PR must remain + draft. +2. If the PR is draft, diagnose draft state before asking for review: inspect + repo draft policy, PR body, check state, unresolved review comments, linked + issue state, handoff notes, configured review evidence label state, and the + original worker session. A draft-only stall is an orchestration repair, not + a code review request. +3. For a draft PR, identify the exact blocker. If checks are still running or + failing, rerun or route the check failure. If author fixes, missing + metadata, or human prep are required, reply to the original worker's + continuation target or mark the ticket for human attention. If no explicit + draft blocker remains, mark the PR ready-for-review and verify it is + non-draft. +4. Confirm code review happened when feasible and covers the current PR head + before applying the configured review evidence label, moving to + `Ready to Merge`, or calling integrate. Request Agent Review only when + review evidence is the actual blocker, not merely because the PR is draft. +5. When the next action requires review evidence, first verify the review + target is stable enough to spend a review pass: the PR head matches the + code host, the original worker is not still pushing to that head, and + required checks are complete or at least attached to the current head. If + the head moved, checks are empty or pending after a push, or the worker + session is still actively iterating, defer review until the next tick + instead of producing unusable review evidence. If a review pass was already + wasted, log the cost with an existing friction category, usually + `stuck-worker` for live worker churn or `config-gap` for missing + check-state expectations. +6. When the review target is stable, run independent `ziw-code-review` in a + subagent or disposable worktree. Parallel reviews must use isolated + worktrees or sessions, never one shared mutable checkout. +7. Read the review verdict and CodeRabbit recommendation from the review + artifact. If multiple current review artifacts disagree on blocking + findings, reconcile conservatively: treat the PR as blocked until a focused + re-review resolves the exact findings or the risky diff is fixed. +8. If the PR head changed since the configured review evidence label was + applied, or the label lacks reviewed head SHA evidence, remove the label + before continuing. +9. If the latest review has blocking findings, remove the configured review + evidence label and post actionable findings as PR review comments when + configured. +10. Move the issue to `Changes Requested` when author fixes are needed. +11. Send feedback as a direct reply to the original worker's continuation + target when available. Do not use a top-level issue comment for a remote + Cursor agent unless config verifies that route. Record a `review-thrash` + friction entry when a ticket returns to review more than the configured + number of times. +12. Keep fixes on the same branch and PR. After fixes, rerun review and + required checks. +13. When review is clean for the current PR head, apply the configured review + evidence label to the issue and record the PR URL, reviewed head SHA, + review artifact, and reviewer path in a tracker comment or configured + evidence field. +14. Before changing draft state, refresh code-host PR state and the current PR + head. Before applying the configured review evidence label, moving tracker + state to `Ready to Merge`, or calling integrate, refresh local Git refs + and code-host PR state. Verify the local branch or worktree HEAD, PR head + SHA, and default branch HEAD still match the review and check evidence. If + they do not match, rerun review and checks for the current head instead of + approving or merging from stale local state. If the base branch moved + since the review or `Ready to Merge` evidence was recorded, treat merge + readiness as expired until the branch is updated and checks plus review + cover the new head. +15. If review is clean, required checks pass or are not required, and the PR + is still draft, move the PR to ready-for-review unless the user or repo + config explicitly says to keep it draft. Then refresh the code-host PR + state and verify it is non-draft. This is a code-host PR state change, + separate from tracker status. A kept-draft PR is pre-review; do not call + it ready-for-review. +16. Resolve CodeRabbit escalation per the operating profile's merge-safety + rules and the review artifact's recommendation. Resolve + `reviews.auto_review` from the workflow config and root `.coderabbit.yaml` + at the reviewed head, plus the current PR-hosted review state, before + posting any command. If auto-review mode is unknown, stop and resolve it + first. If a hosted review is enabled, pending, or already current for the + PR head, record that state and wait. Only after auto-review is resolved + and explicit opt-in is still needed, use a top-level PR comment: + `@coderabbitai review` for incremental review, or + `@coderabbitai full review` when no complete review covers the current + head. Use `@coderabbitai ignore` in the PR description for a + policy-allowed skip; never run the CodeRabbit CLI for an existing PR. + Treat missing auth, rate limits, or credits as a recorded skip unless + CodeRabbit is explicitly required. +17. Act only on high-priority CodeRabbit findings: P0/P1, security, data loss, + correctness regression, production blocker, or a user-requested finding. +18. Move to `Ready to Merge` only when review is clean, required checks pass, + the PR is non-draft and ready-for-review, the configured review evidence + label is current for the PR head, and required CodeRabbit escalation is + complete or recorded as skipped by policy. +19. Call integrate when the auto-merge gate is satisfied. + +## Merge Preflight + +Merge preflight must enumerate every unresolved review thread on the PR with +severity, using the code host's thread-level view, before deciding merge +readiness; a partial comment count can green-light a real bug. If a code-host +review verdict such as `CHANGES_REQUESTED` predates the current head and its +findings are resolved on the current head, dismiss or re-request that review +through the configured mechanism instead of leaving stale verdict metadata to +block the merge. + +If config says hosted checks are unavailable or unknown but the code host +exposes required, recently attached, or clearly relevant checks on the PR, +treat that as a setup drift signal. Log `config-gap`, use the live code-host +checks as the minimum safety evidence for this PR, and route setup refresh to +record the real gate. Do not merge by relying on stale "no CI" config. + +## Merge + +When the integrate gate passes: + +1. Refresh local Git refs and code-host PR state immediately before merging. + Verify the local observation of the PR head, default branch HEAD, merge + base, required checks, review verdict, and draft state matches the code + host. If any value is stale or missing, update the local checkout and rerun + the affected gate instead of merging. +2. If the default branch moved since the PR branch last updated, rebase or + update the branch, then rerun required checks and `ziw-code-review`. Do not + merge a stale branch on the assumption it still applies, and do not + preserve `Ready to Merge` state without fresh evidence. Record a + `merge-conflict` friction entry if the rebase needed manual resolution and + escalate instead of guessing on a real conflict. +3. Merge through the configured mechanism, such as squash, merge commit, or + rebase merge. If the code host rejects the configured method, stop, log + `config-gap`, and refresh setup instead of retrying with a guessed method. + If branch policy rejects a direct merge despite green checks, use the + host's auto-merge when config allows it and record the policy for the next + setup refresh. Confirm the merge completed from refreshed code-host state, + not from the merge command's output; some CLIs print nothing on success. +4. Refresh local Git refs and update the local default branch to the merged + head before any post-merge check, next PR decision, or issue `Done` + transition. +5. Run configured post-merge preparation before judging the default branch: + update dependencies when the lockfile or workspace graph changed, rebuild + or regenerate artifacts when config says they can be stale, and use the + configured runner for tests or checks. Do not infer the runner from file + names. Then run the configured post-merge check when config names one, + including the production deploy status on the default-branch HEAD when the + repo deploys on push. Mergeable does not prove correct after merge. If a + prep step clears a stale local artifact failure, log `config-gap`; if the + checked default branch still fails, record `post-merge-break` and escalate. +6. Move the issue to `Done` only after the merge and post-merge check succeed + and the full issue scope is complete. For Linear + GitHub, assume the + linked PR can auto-advance the ticket state; do not duplicate that + transition unless refreshed state still needs repair. If a code-host + integration auto-moved the issue to `Done` after the first linked PR but + acceptance criteria remain, reopen or narrow the issue according to config, + record the residual scope, and log `config-gap`. In the same tracker update + for true Done, remove `ready-for-agent` or the repo-configured readiness + label from the done ticket. Done work is no longer waiting for agent + handoff. diff --git a/.agents/skills/ziw-orchestrate/references/loop-contract.md b/.agents/skills/ziw-orchestrate/references/loop-contract.md index a616af3b..0ed83334 100644 --- a/.agents/skills/ziw-orchestrate/references/loop-contract.md +++ b/.agents/skills/ziw-orchestrate/references/loop-contract.md @@ -43,14 +43,28 @@ Each tick: checkpoint. Refresh local Git refs, HEAD, worktree list, and `git status --short --branch` when a local checkout is in play. Do not carry diffs, logs, or issue histories across ticks. -2. Rebuild the queue from systems of record. Delegate the inventory read to an - isolated triage worker when the runtime has one; keep only the compact queue - (ID, state, readiness, blockers, PR, owner, next action) in the main context. +2. Rebuild the queue from systems of record. When the synced skill directory + includes `scripts/tick-snapshot.mjs`, run + `node /scripts/tick-snapshot.mjs --repo ` first: one + call returns baseline health, the open-PR footprint, per-PR head SHAs, + mergeable state, unresolved review-thread counts, check rollups, and + review verdicts as JSON. Reason over that snapshot instead of assembling + the same state from many tool calls; it needs an authenticated `gh`, and + with `LINEAR_API_KEY` set plus `--linear-team ` it also returns the + open issue queue with unresolved `blockedBy` identifiers per issue. Never + dispatch an issue whose snapshot or tracker state shows an incomplete + blocker. Use tracker tooling for issue bodies and comments. Delegate the inventory read to an isolated triage + worker when the runtime has one; keep only the compact queue (ID, state, + readiness, blockers, PR, owner, next action) in the main context. 3. Reconcile the ledger against refreshed tracker and PR state. Trust external state; drop stale ledger entries; re-dispatch or escalate stuck workers. 4. Refresh the repo-level active delivery footprint: open PRs, active PR-scoped previews, and implementation dispatches that have not yet produced a PR. Count repo/project preview capacity, not only the requested issue filter. + Count only agent- or human-delegated product PRs against the delivery cap; + track bot dependency PRs (dependabot, renovate) as a separate drain count. + Bot PRs are merge/close work to advance, not delegation slots — they must + not starve new dispatch. 5. Act on at most a bounded slice of work this tick: advance returned PRs, active previews, and stuck draft PRs first. Optimize delivery-slot turnover over worker count: merge green PRs, route fixes, update branches after main moves, diff --git a/.agents/skills/ziw-orchestrate/scripts/tick-snapshot.mjs b/.agents/skills/ziw-orchestrate/scripts/tick-snapshot.mjs new file mode 100644 index 00000000..044b4abf --- /dev/null +++ b/.agents/skills/ziw-orchestrate/scripts/tick-snapshot.mjs @@ -0,0 +1,223 @@ +#!/usr/bin/env node +// Tick snapshot for ziw-orchestrate: assemble the code-host state one tick +// needs as a single JSON blob, so the orchestrator reasons over a compact +// snapshot instead of dozens of tool round-trips. +// +// Usage: +// node tick-snapshot.mjs [--repo owner/name] [--limit 50] [--linear-team KEY] +// +// GitHub state comes from the `gh` CLI (must be installed and authenticated). +// Linear state is included only when LINEAR_API_KEY is set and --linear-team +// is given; otherwise the tracker section reports skipped and the caller uses +// its tracker tooling as usual. Blocker relations and issue bodies stay on +// the tracker tools; this snapshot is workflow metadata only. + +import { execFileSync } from "node:child_process"; + +const args = process.argv.slice(2); +const argValue = (flag) => { + const i = args.indexOf(flag); + return i >= 0 ? args[i + 1] : undefined; +}; + +const fail = (message) => { + console.error(`tick-snapshot: ${message}`); + process.exit(1); +}; + +const gh = (ghArgs, input) => { + try { + return execFileSync("gh", ghArgs, { + encoding: "utf8", + input, + maxBuffer: 32 * 1024 * 1024, + }); + } catch (error) { + fail(`gh ${ghArgs[0]} failed: ${error.stderr?.toString().trim() || error.message}`); + } +}; + +const deriveRepo = () => { + try { + const url = execFileSync("git", ["remote", "get-url", "origin"], { encoding: "utf8" }).trim(); + const match = url.match(/[:/]([^/:]+\/[^/]+?)(?:\.git)?$/); + if (match) return match[1]; + } catch { + // fall through to the explicit error below + } + return undefined; +}; + +const repo = argValue("--repo") ?? deriveRepo(); +if (!repo || !repo.includes("/")) fail("cannot determine repo; pass --repo owner/name"); +const [owner, name] = repo.split("/"); +const limit = Number(argValue("--limit") ?? 50); + +const PR_QUERY = ` +query($owner: String!, $name: String!, $limit: Int!) { + repository(owner: $owner, name: $name) { + defaultBranchRef { + name + target { + ... on Commit { oid statusCheckRollup { state contexts(first: 50) { nodes { + ... on CheckRun { name conclusion status } + ... on StatusContext { context state } + } } } } + } + } + pullRequests(states: OPEN, first: $limit, orderBy: { field: UPDATED_AT, direction: DESC }) { + totalCount + nodes { + number title url isDraft updatedAt + author { login __typename } + headRefName headRefOid baseRefName + mergeable mergeStateStatus reviewDecision + labels(first: 20) { nodes { name } } + reviewThreads(first: 100) { totalCount nodes { isResolved } } + reviews(last: 20) { nodes { author { login } state submittedAt } } + commits(last: 1) { nodes { commit { statusCheckRollup { state contexts(first: 60) { nodes { + ... on CheckRun { name conclusion status } + ... on StatusContext { context state } + } } } } } } + } + } + } +}`; + +const checkSummary = (rollup) => { + if (!rollup) return { state: "NONE", failed: [], pending: [] }; + const failed = []; + const pending = []; + for (const node of rollup.contexts?.nodes ?? []) { + const label = node.name ?? node.context ?? "unknown"; + const outcome = node.conclusion ?? node.state ?? node.status ?? "UNKNOWN"; + if (["FAILURE", "ERROR", "TIMED_OUT", "CANCELLED", "ACTION_REQUIRED"].includes(outcome)) { + failed.push(label); + } else if (["PENDING", "QUEUED", "IN_PROGRESS", "EXPECTED", "WAITING"].includes(outcome)) { + pending.push(label); + } + } + return { state: rollup.state ?? "UNKNOWN", failed, pending }; +}; + +const latestReviewByAuthor = (reviews) => { + const byAuthor = new Map(); + for (const review of reviews ?? []) { + if (!review.author?.login || review.state === "COMMENTED") continue; + byAuthor.set(review.author.login, { state: review.state, submittedAt: review.submittedAt }); + } + return Object.fromEntries(byAuthor); +}; + +const raw = gh([ + "api", + "graphql", + "-f", + `query=${PR_QUERY}`, + "-F", + `owner=${owner}`, + "-F", + `name=${name}`, + "-F", + `limit=${limit}`, +]); +const repoData = JSON.parse(raw).data.repository; + +const baselineRollup = repoData.defaultBranchRef?.target?.statusCheckRollup; +const baseline = { + branch: repoData.defaultBranchRef?.name ?? null, + headSha: repoData.defaultBranchRef?.target?.oid ?? null, + checks: checkSummary(baselineRollup), +}; +baseline.green = baseline.checks.state === "SUCCESS" || baseline.checks.state === "NONE"; + +const prs = (repoData.pullRequests?.nodes ?? []).map((pr) => ({ + number: pr.number, + title: pr.title, + url: pr.url, + author: pr.author?.login ?? null, + isBot: pr.author?.__typename === "Bot", + isDraft: pr.isDraft, + updatedAt: pr.updatedAt, + headRefName: pr.headRefName, + headSha: pr.headRefOid, + baseRefName: pr.baseRefName, + mergeable: pr.mergeable, + mergeStateStatus: pr.mergeStateStatus, + reviewDecision: pr.reviewDecision, + labels: (pr.labels?.nodes ?? []).map((label) => label.name), + unresolvedThreads: (pr.reviewThreads?.nodes ?? []).filter((t) => !t.isResolved).length, + reviewThreadsTruncated: (pr.reviewThreads?.totalCount ?? 0) > 100, + latestReviews: latestReviewByAuthor(pr.reviews?.nodes), + checks: checkSummary(pr.commits?.nodes?.[0]?.commit?.statusCheckRollup), +})); + +const linearTeam = argValue("--linear-team"); +let linear = { skipped: "no LINEAR_API_KEY or --linear-team; use tracker tooling" }; +if (process.env.LINEAR_API_KEY && linearTeam) { + const LINEAR_QUERY = ` +query($team: String!) { + issues(first: 100, filter: { + team: { key: { eq: $team } }, + state: { type: { nin: ["completed", "canceled"] } } + }) { + nodes { + identifier title url priority updatedAt + state { name type } + labels { nodes { name } } + assignee { displayName } + inverseRelations(first: 20) { nodes { type issue { identifier state { type } } } } + } + } +}`; + try { + const response = await fetch("https://api.linear.app/graphql", { + method: "POST", + headers: { + "Content-Type": "application/json", + Authorization: process.env.LINEAR_API_KEY, + }, + body: JSON.stringify({ query: LINEAR_QUERY, variables: { team: linearTeam } }), + }); + const body = await response.json(); + if (body.errors) throw new Error(body.errors.map((e) => e.message).join("; ")); + linear = { + team: linearTeam, + issues: body.data.issues.nodes.map((issue) => ({ + identifier: issue.identifier, + title: issue.title, + url: issue.url, + state: issue.state?.name, + stateType: issue.state?.type, + priority: issue.priority, + labels: (issue.labels?.nodes ?? []).map((label) => label.name), + assignee: issue.assignee?.displayName ?? null, + blockedBy: (issue.inverseRelations?.nodes ?? []) + .filter((rel) => rel.type === "blocks" && rel.issue?.state?.type !== "completed") + .map((rel) => rel.issue.identifier), + updatedAt: issue.updatedAt, + })), + }; + } catch (error) { + linear = { error: `Linear query failed: ${error.message}; use tracker tooling` }; + } +} + +process.stdout.write( + `${JSON.stringify( + { + generatedAt: new Date().toISOString(), + repo, + baseline, + footprint: { + openPrCount: repoData.pullRequests?.totalCount ?? prs.length, + productPrCount: prs.filter((pr) => !pr.isBot).length, + botPrCount: prs.filter((pr) => pr.isBot).length, + }, + prs, + linear, + }, + null, + 2, + )}\n`, +); diff --git a/.agents/skills/ziw-pr/SKILL.md b/.agents/skills/ziw-pr/SKILL.md index d1c24c20..819bca66 100644 --- a/.agents/skills/ziw-pr/SKILL.md +++ b/.agents/skills/ziw-pr/SKILL.md @@ -69,6 +69,11 @@ or secret-scan checks. When running secret scanning locally, use the same branch, diff, or source scope that CI uses instead of scanning unrelated local refs. +If CI exposes coverage, smoke, or secret scanning as separate threshold jobs, +run the configured local equivalent before PR handoff when the current diff +touches that surface. A passing full local gate is not enough when config says a +threshold job lives outside that gate. + When CI has threshold gates, cache-sensitive tasks, or env-filtered test gates, run the exact threshold-enforcing and cache-busted command named by config. A cached green local gate is not PR evidence unless config says the cache is valid @@ -94,30 +99,18 @@ review, run `ziw-code-review`. Fix P0/P1 findings and obvious mechanical P2 findings. Ask before broad architecture, product, security, or data-behavior changes. -Use CodeRabbit only when code review recommends it, the change is high-risk, or -the user asks. Missing auth, rate limits, or credits are a skip, not a blocker. -Read root `.coderabbit.yaml` when present and record whether -`reviews.auto_review` is enabled, disabled, opt-in by label or description -keyword, or unknown. Note draft or incremental-review behavior only when it -changes the command choice. Record the CodeRabbit decision in the handoff so -Agent Orchestrator can decide whether any post-PR escalation remains. - -Do not post CodeRabbit PR comments or run the CodeRabbit CLI until the -auto-review mode and current hosted review state are resolved from repo config, -root `.coderabbit.yaml`, or the PR. If auto-review or push-triggered hosted -review is enabled, pending, or already complete for the current PR head, record -that state and wait for the hosted review instead of requesting another review -or running local CLI. If the state is unknown, leave CodeRabbit as unresolved in -the handoff; do not guess. - -When CodeRabbit is optional and the root config would otherwise auto-review the -PR, add `@coderabbitai ignore` to the PR description only if the repo config -allows agents to skip optional CodeRabbit reviews or rate-limit conservation is -needed. When CodeRabbit is required after the PR exists, use a top-level PR -comment: `@coderabbitai review` for incremental review, or -`@coderabbitai full review` only when auto-review is resolved, no hosted review -is pending or complete for the current PR head, and no complete review covers the -current PR head. Do not use the CodeRabbit CLI for an existing PR. +Use CodeRabbit per the merge-safety rules in +[../ziw-setup/references/operating-profile.md](../ziw-setup/references/operating-profile.md) +and the `ziw-code-review` recommendation: only for high-risk changes or when +the user asks. Do not post CodeRabbit commands or run its CLI until the +auto-review mode (root `.coderabbit.yaml` `reviews.auto_review`) and the +current hosted review state are resolved; if a hosted review is enabled, +pending, or complete for the current PR head, wait instead of requesting +another, and never use the CLI for an existing PR. Use `@coderabbitai ignore` +in the PR description only when repo policy allows skipping optional +auto-review. Record the decision, or `unresolved` when the state is unknown, +in the handoff so Agent Orchestrator can decide any post-PR escalation. +Missing auth, rate limits, or credits are a recorded skip, not a blocker. ## Commit @@ -195,8 +188,9 @@ When an issue exists: not duplicate manual state changes unless config delegates that authority - comment with checks run, code review verdict, CodeRabbit decision, PR draft or ready-for-review state, current PR head SHA, base SHA, merge base, - `Code review passed` recommendation with reviewed head SHA, acceptance - criteria status, hosted check state, and differences from original intent + configured review evidence label recommendation with reviewed head SHA, + acceptance criteria status, hosted check state, and differences from original + intent - never move to `Done`; merge is not complete Do not move workflow state unless the repo config or user explicitly delegates diff --git a/.agents/skills/ziw-setup/SKILL.md b/.agents/skills/ziw-setup/SKILL.md index ae54e4f5..16b8407d 100644 --- a/.agents/skills/ziw-setup/SKILL.md +++ b/.agents/skills/ziw-setup/SKILL.md @@ -18,6 +18,13 @@ Agents should query external systems to refresh live state, not to rediscover these values. If a value cannot be verified during setup, record it as an explicit unknown with the source that should verify it. +Shared workflow skills may be distributed as project skills, plugin or +marketplace, managed settings, user/global-only, or mixed mode. Record which +mode this repo actually uses. Project-scoped generated `ziw-*` copies are valid +when repo, remote, or cloud workers need the skills from a fresh clone; treat +them as vendored generated dependencies from `zaks-io/skills`, update them +mechanically, and do not hand-edit them in downstream repos. + Setup is a verification pass, not a best-effort note-taking pass. Every populated config value that can change agent behavior must have current evidence from the repo, tracker, code host, CI, agent integration, environment config, or explicit @@ -90,8 +97,8 @@ Verify all populated workflow fields that setup writes or preserves: commands from scripts, CI workflows, makefiles, justfiles, runbooks, or direct safe command execution - issue tracker provider, location, team/project/board/roadmap, statuses, - labels, priorities, relationships, issue templates, and query contracts with - read-only tracker tool calls when tools are available + labels, priorities, estimate fields, relationships, issue templates, and query + contracts with read-only tracker tool calls when tools are available - code host default branch, branch protections, PR conventions, linked checks, and open PR query shape through git metadata, code host tools, or workflow files @@ -100,6 +107,9 @@ Verify all populated workflow fields that setup writes or preserves: or explicit user instruction - Claude, Codex, editor, and repo-local adapter paths by resolving files, symlinks, imports, and generated skill metadata from a clean path +- shared workflow skill distribution mode, source, lockfile, refresh command, + project paths, symlink layout, plugin marketplace, and whether generated skill + directories are committed dependencies, ignored local cache, or absent - environment safety, deployment paths, hosted checks, preview rules, credential rules, and production approval rules from deployment config, CI, runbooks, or explicit user instruction @@ -138,18 +148,34 @@ Record: - a compact verification summary: date, scope, evidence sources, safe commands or read-only tool calls used, and unverified values - repo identity, default branch, branch prefix, and PR conventions +- default-branch baseline health: current required-check state, known-red jobs + with an `expected-red-until-` note, and which job conclusion the + post-merge check judges when an umbrella workflow contains a known-broken + sibling job +- remote worker environment enforcement: whether repo hooks and gates actually + install and run in each remote or cloud worker environment (installers often + skip under a generic `CI=true`) and the exact pre-push gate that environment + enforces; prompt-level instructions are not a substitute for an + environment-enforced gate - package manager and command table: install, full gate, focused checks, build, lint, typecheck, tests, smoke, generated artifacts, cache policy, CI env passthrough rules, and the exact coverage or secret-scan scopes that hosted checks enforce +- gate parity: the repo's CI required job should invoke the same single verify + entrypoint the local hooks run, so a check added to CI is a check added + locally by construction. Record the entrypoint command and the CI job that + calls it. Flag any test, lint, coverage, format, or scan step that CI runs + outside that entrypoint as a `config-gap` to fix in the repo, not a + difference to document in prose - issue tracker provider, provider location, project or board, routing label, triage scope, orphan policy, statuses, labels, kind label set (`kind-spec`, `kind-epic`, `kind-slice`) and its single-select policy, readiness label policy, worker environment label policy when present, startable work criteria (including `kind-slice` only), readiness-label query policy that - excludes the configured done state, priority policy, dependency policy, - dependency graph mechanism, file footprint convention, issue body contract, - agent-suitability policy for work types and risk, + excludes the configured done state, priority policy, estimate field, estimate + scale, estimate policy, dependency policy, dependency graph mechanism, file + footprint convention, issue body contract, agent-suitability policy for work + types and risk, Issue Triage verified-state reconciliation authority, requested ready-state promotion authority, explicit Linear Backlog promotion gate, and which workflow role owns active status transitions @@ -159,6 +185,8 @@ Record: - code-host issue sync policy, including whether Linear advances ticket states from linked GitHub PR status and whether agents should assume synced state when both linked entities exist +- code-host PR attention labels the orchestrator applies when a PR needs human + merge or input, such as `needs-human-merge` and `needs-human-input` - supported worker delegation paths: `local-worktree`, `issue-assigned`, or both - default worker path and capacity policy when the user or repo has a stable preference @@ -168,7 +196,9 @@ Record: active PR/preview cap, cap count policy, preview-provider cap, stuck-worker timeout, attempt cap before the thrash circuit breaker, required checks that define green for the integrate gate, auto-merge risk tiers, merge method, - post-merge preparation and check, auto-Done integration behavior, + post-merge preparation and check, the production deploy status check on the + default-branch HEAD when the repo deploys on push, auto-Done integration + behavior, single-ticket one-off mutation policy, verified-ready ticket-set policy, completely-blocked stop policy, friction intake provider, location, mode, visibility, agent create authority, review cadence, cleanup policy, and @@ -183,10 +213,15 @@ Record: they mirror this config or redirect agents back to it - verified tracker metadata: lookup tool or query used, verification date, and exact provider IDs, URLs, or keys for teams, projects, boards, repos, - milestones, roadmaps, statuses, labels, priorities, and relationship types - when the tracker exposes them + milestones, roadmaps, statuses, labels, priorities, estimate fields and + allowed values, and relationship types when the tracker exposes them - agent access rules for local Codex, remote worker agents, Claude, and any repo-approved worker +- workflow skill distribution policy: project skills, plugin or marketplace, + managed settings, user/global-only, or mixed; include installer source, + lockfile, pinned tag or commit when required, refresh command, project skill + paths, symlink layout, and whether generated local copies are committed + dependencies or ignored cache - issue-assigned agent notes when available: project-specific environment labels or fields, worker environment approval labels, delegation tool or field, verified agent IDs, direct-agent reply targets, continuation comment rules, and @@ -264,12 +299,14 @@ labels only when they change routing, checks, approvals, or reviewer assignment. Review evidence: -- `Code review passed` +- configured exact label slug or ID, such as `code-review-passed` -By default, `Code review passed` means the latest linked PR head SHA has passed -the configured code review gate for the ticket. Record the PR URL and reviewed -head SHA when applying it. Remove it when the PR head changes, blocking findings -appear, the linked PR changes, or the evidence is missing. +By default, the review evidence label means the latest linked PR head SHA has +passed the configured code review gate for the ticket. Record the exact +configured label slug or ID, PR URL, and reviewed head SHA when applying it. +Remove it when the PR head changes, blocking findings appear, the linked PR +changes, or the evidence is missing. Resolve the label by configured slug or ID, +not by reconstructing a title-case display name. Type: @@ -325,6 +362,13 @@ workflow skills. Keep them short and use [references/agent-workflow.md](references/agent-workflow.md) as the adapter contract. +If runtime-generated shared `ziw-*` skill files exist under `.agents/skills/`, +`.claude/skills/`, `.codex/skills/`, or `skills/`, decide whether those files +are a committed dependency, symlink fanout, ignored local cache, absent, or +repo-authored project-specific skills. For committed dependencies, record the +source and lockfile and commit mechanical updates. Never hand-edit downstream +generated copies. + For Claude Code, configure the target repo's Claude Code integration, not this skills repo. Treat that integration as the source of truth for Claude-facing agent, command, and skill registration. Configure it to import the target repo's diff --git a/.agents/skills/ziw-setup/references/agent-workflow.md b/.agents/skills/ziw-setup/references/agent-workflow.md index b960f2c7..618f2c2b 100644 --- a/.agents/skills/ziw-setup/references/agent-workflow.md +++ b/.agents/skills/ziw-setup/references/agent-workflow.md @@ -6,8 +6,9 @@ Use this when writing or refreshing `docs/agents/workflow/config.md`. - To Issues: turns a spec, PRD, or epic ticket into dependency-ordered one-PR `kind-slice` tickets. Adopts hand-created tickets instead of duplicating them, - applies the agent-ready body and labels, and emits a dependency graph and file - footprint. Creates tickets; it does not implement or move active work. + applies the agent-ready body, labels, and configured estimates, and emits a + dependency graph and file footprint. Creates tickets; it does not implement or + move active work. - Agent Orchestrator: runs the work loop. Keeps tracked work moving, delegates startable `kind-slice` work, calls review and integrate as steps, heals unambiguous tracker mistakes, logs friction, owns the authority to mutate @@ -21,11 +22,12 @@ Use this when writing or refreshing `docs/agents/workflow/config.md`. orchestrator refactor findings to Agent Orchestrator, and files actionable tracker issues without moving active work between workflow states. - Issue Triage: the bulk reconciler. Periodically updates configured current - tracker issues, labels, kinds, priorities, dependencies, orphans, stale - verified states, and agent-ready issue bodies before Agent Orchestrator selects - work; its default goal is to make all Todo tickets ready for agents and keep - tracker state truthful. It does not review Linear Backlog unless asked. When - something is unclear, it asks the user or leaves exact human next actions. + tracker issues, labels, kinds, priorities, estimates when configured, + dependencies, orphans, stale verified states, and agent-ready issue bodies + before Agent Orchestrator selects work; its default goal is to make all Todo + tickets ready for agents and keep tracker state truthful. It does not review + Linear Backlog unless asked. When something is unclear, it asks the user or + leaves exact human next actions. ## Ticket Kinds @@ -53,11 +55,13 @@ domain behavior, and performance work without benchmarks. ## Flow 1. To Issues turns a spec, PRD, or epic ticket into `kind-slice` tickets, applies - the body contract and labels, and emits the dependency graph and footprint. -2. Issue Triage normalizes current tracker metadata, kinds, readiness, and - verified stale status. + the body contract, labels, and configured estimates, and emits the dependency + graph and footprint. +2. Issue Triage normalizes current tracker metadata, kinds, readiness, + configured estimates, and verified stale status. 3. Agent Orchestrator selects startable work from the configured tracker: - `kind-slice`, `ready-for-agent`, complete body, and no active blockers. + `kind-slice`, `ready-for-agent`, configured required estimate, complete body, + and no active blockers. 4. Agent Orchestrator claims the issue and delegates implementation using a supported worker path. 5. The implementation worker accepts the issue, implements the scoped change, @@ -70,9 +74,9 @@ domain behavior, and performance work without benchmarks. head SHA without modifying product code or moving issue state. 8. Agent Orchestrator routes findings back to the worker, repairs stuck draft PRs or marks them ready-for-review when allowed, requests CodeRabbit when the - current diff needs it, applies or removes `Code review passed`, or calls the - integrate step to merge on green, move the issue to the done state, and remove - `ready-for-agent`. + current diff needs it, applies or removes the configured review evidence + label, or calls the integrate step to merge on green, move the issue to the + done state, and remove `ready-for-agent`. ## Loop Model @@ -194,9 +198,9 @@ For issue-assigned delegation: tracker's live assignee list into config. - The config should record only project-specific details that are annoying to rediscover, such as supported worker delegation paths, routing labels, routing - fields, readiness label policy, worker environment label policy, startable work - criteria, direct-agent reply targets, or non-default continuation comment - rules. + fields, readiness label policy, worker environment label policy, estimate + policy, startable work criteria, direct-agent reply targets, or non-default + continuation comment rules. - Worker environment labels, such as `remote-worker` or `remote-cursor`, are approval metadata. Apply or preserve them when the issue route and environment approval criteria are verified. Do not require dependencies to be clear just to @@ -236,17 +240,17 @@ For issue-assigned delegation: disabled, opt-in, or unknown. Manual review requests are top-level PR comments. `@coderabbitai ignore` is a PR-description marker for skipping automatic reviews on that PR, and is recorded as a policy skip when used. -- `Code review passed` is a review-evidence label, not workflow state. Apply it - only with PR URL and reviewed head SHA evidence. Remove it when the PR head - changes, blocking findings appear, the linked PR changes, or evidence is - missing. +- The configured review evidence label is not workflow state. Resolve it by + exact configured slug or ID, apply it only with PR URL and reviewed head SHA + evidence, and remove it when the PR head changes, blocking findings appear, + the linked PR changes, or evidence is missing. For local agent runtimes, keep the orchestrator parent thread small and delegate large context loads to isolated workers when available. Claude Code uses plugin subagents such as `ziw-triager`, `ziw-implementer`, and `ziw-reviewer`. Codex and other Agent Skills runtimes should use matching skill names such as `$ziw-triage`, `$ziw-implement`, -`$ziw-review`, and `$ziw-code-review` inside isolated sessions, +and `$ziw-code-review` inside isolated sessions, branches, worktrees, or subagents when available. ## State Authority @@ -314,7 +318,7 @@ orchestration for that ticket only if config or the user grants mutation authority. Orchestrator diagnoses stuck draft PRs without treating draft state as a review request, repairs blockers, verifies the code-host PR is non-draft, and applies or -removes `Code review passed` based on current PR head SHA evidence. When +removes the configured review evidence label based on current PR head SHA evidence. When Orchestrator moves a ticket to `Done`, it verifies the full issue scope is complete and removes `ready-for-agent`. If a code-host integration auto-moved a partial or multi-PR issue to `Done`, Orchestrator reopens or narrows it according @@ -329,10 +333,10 @@ and name the core skills: - `ziw-to-issues` for turning a spec, PRD, or epic into `kind-slice` tickets - `ziw-orchestrate` for the orchestration loop - `ziw-implement` for one startable issue through PR creation -- `ziw-review` for independent latest-committed PR and main drift review - `ziw-triage` for current tracker cleanup, readiness repair, and optional Linear Backlog or intake backfill when explicitly requested -- `ziw-code-review` as the shared review gate +- `ziw-code-review` as the shared review gate, including independent + latest-committed PR review and main-drift review - `ziw-pr` for PR creation Do not duplicate this whole workflow into adapter docs. diff --git a/.agents/skills/ziw-setup/references/handoff.md b/.agents/skills/ziw-setup/references/handoff.md index 8937dcc4..33f194c8 100644 --- a/.agents/skills/ziw-setup/references/handoff.md +++ b/.agents/skills/ziw-setup/references/handoff.md @@ -41,8 +41,8 @@ Rules: evidence after that event. - When Markdown or docs changed, include the configured docs formatting check, such as `pnpm format:docs:check` when the target repo provides it. -- Say whether `Code review passed` is applied, removed, or requested for the - current PR head SHA. +- Say whether the configured review evidence label is applied, removed, or + requested for the current PR head SHA. - Say whether the PR is draft/pre-review or non-draft/ready-for-review, and who owns any required ready-for-review transition. - Say whether CodeRabbit is skipped, complete, auto-review pending, or still diff --git a/.agents/skills/ziw-setup/references/issue-tracker-contract.md b/.agents/skills/ziw-setup/references/issue-tracker-contract.md index 8e826299..7d427f22 100644 --- a/.agents/skills/ziw-setup/references/issue-tracker-contract.md +++ b/.agents/skills/ziw-setup/references/issue-tracker-contract.md @@ -47,7 +47,7 @@ Risk: Review evidence: -- `Code review passed` +- configured exact label slug or ID, such as `code-review-passed` Type: @@ -72,10 +72,32 @@ contains: - required checks - security, privacy, data, or operational invariants - dependencies or blockers +- estimate when repo config stores estimates in the body If the work requires multiple PRs, keep it as a container or split it into multiple `kind-slice` issues. Do not mark a multi-PR scope as a ready slice. +## Estimate Rules + +Repo config decides whether estimates exist and where they live. A repo may use +a tracker estimate field, estimate labels, a body heading, or no estimates. + +- Do not create or infer estimates when config has no estimate field, scale, and + policy. +- When config grants agents authority to estimate, To Issues and Issue Triage + include estimates on `kind-slice` tickets using the configured field, label, or + body heading. +- Missing estimates block `ready-for-agent` only when config says estimates are + required for ready handoff. Otherwise leave the estimate empty and do not use + it as a readiness blocker. +- Use only the configured scale. If a slice exceeds the configured maximum, split + it or route it to human planning instead of inventing a larger value. +- Preserve existing human estimates unless config explicitly allows repair and + current scope evidence proves the estimate is stale or outside the allowed + scale. +- Treat estimates as implementation effort or size, not priority, risk, + deadline, or merge authority. + ## Label Treatment Rules - Repo config owns the treatment policy for every readiness and worker @@ -92,6 +114,9 @@ multiple `kind-slice` issues. Do not mark a multi-PR scope as a ready slice. parked, or not shaped correctly. - `ready-for-agent` must be removed when an issue moves to the configured `Done` state. Done work is complete, not waiting for agent handoff. +- Only the To Issues intake pass, or a triage pass applying the same body + contract, may set `ready-for-agent`. Flows that file tickets without intake + must leave readiness labels off so the gap stays visible. - Queries for `ready-for-agent`, `ready-for-human`, or equivalent readiness attention labels must also exclude the configured `Done` state by default. Stale labels on Done tickets are cleanup drift, not current work queue input. @@ -136,11 +161,12 @@ multiple `kind-slice` issues. Do not mark a multi-PR scope as a ready slice. triage must verify the full issue scope is complete before leaving it there. If linked PR evidence covers only part of the issue, reopen or narrow it according to repo config. -- `Code review passed` means the latest linked PR head SHA has passed the - configured code review gate for this ticket. Apply it only with adjacent - review evidence that names the PR URL and reviewed head SHA. Remove it when - the PR head changes, blocking review findings appear, the linked PR changes, - or the review evidence is missing or stale. +- The configured review evidence label means the latest linked PR head SHA has + passed the configured code review gate for this ticket. Resolve it by the + exact configured slug or ID, not by reconstructing a display name. Apply it + only with adjacent review evidence that names the PR URL and reviewed head + SHA. Remove it when the PR head changes, blocking review findings appear, the + linked PR changes, or the review evidence is missing or stale. - Blocked work can keep `ready-for-agent`. Blocker relationships, body blockers, or workflow state stop scheduling; they do not redefine readiness metadata. - Worker environment labels are approval and routing metadata. They do not say @@ -148,6 +174,9 @@ multiple `kind-slice` issues. Do not mark a multi-PR scope as a ready slice. whether Orchestrator may start it now. - Human setup, credentials, product judgment, provider approval, customer input, and ADR decisions use `ready-for-human` or `needs-info`. +- `ready-for-human` and other human-attention states are truthful claims that + the only remaining work is the named human action. Unresolved agent-fixable + review findings keep the ticket with the agent; fix them before escalating. - Dependency order should be encoded with tracker relationships when the provider supports them. By default, if ticket A needs ticket B first, A is blocked by B and B blocks A. Use the smallest direct graph that lets diff --git a/.agents/skills/ziw-setup/references/linear-cursor-example.md b/.agents/skills/ziw-setup/references/linear-cursor-example.md index 2ecc0f0f..4a80e864 100644 --- a/.agents/skills/ziw-setup/references/linear-cursor-example.md +++ b/.agents/skills/ziw-setup/references/linear-cursor-example.md @@ -60,8 +60,15 @@ Last updated: 2026-06-01 - Repo-route label: /example-app (REQUIRED before issue-assigned delegation; tells Cursor which GitHub repo to clone) - Risk labels: risk-normal, risk-security-sensitive, risk-schema, risk-cross-cutting -- Review evidence labels: Code review passed +- Review evidence labels: code-review-passed - Type labels: Bug, Feature, Improvement, Tech Debt, Spike, Hotfix +- Estimate field: Linear estimate points +- Estimate scale: 1, 2, 3, 5, 8; split or route to human when a slice would + exceed 8 +- Estimate policy: To Issues and Issue Triage set estimates on `kind-slice` + tickets when scope evidence is enough; estimates are required before + `ready-for-agent`; missing required estimates use `needs-info` or + `ready-for-human` - Friction intake provider: Linear - Friction intake location: private team "Skills" project "Agent Friction" (team id , project id ) @@ -77,7 +84,8 @@ Last updated: 2026-06-01 - Friction intake redaction policy: metadata and IDs only; no secrets, private logs, signed URLs, customer data, or diffs - Startable work criteria: kind-slice, Todo, ready-for-agent, remote-cursor, - repo-route label, complete body, no active blockers, no active claim, no open PR + repo-route label, configured required estimate, complete body, no active + blockers, no active claim, no open PR - Dependency policy: use Linear blocker relationships; if issue A needs issue B first, A is blocked by B and B blocks A. Keep blocked-but-ready slices in Todo, not Linear Backlog. diff --git a/.agents/skills/ziw-setup/references/operating-profile.md b/.agents/skills/ziw-setup/references/operating-profile.md index 74fcc2a3..6053ff5a 100644 --- a/.agents/skills/ziw-setup/references/operating-profile.md +++ b/.agents/skills/ziw-setup/references/operating-profile.md @@ -46,6 +46,10 @@ Cursor; a different provider records its own equivalent in config. - Record the returned session handle in the ledger when the agent provides one. Cursor returns a `cursor.com/agents/bc-` URL in its comments; the `bcId` is the durable session handle. +- Shortly after delegating, verify the provider spawned exactly one session for + the dispatch. Some providers spawn duplicate sessions minutes apart from a + single delegate set; stop or close the duplicate before either opens a PR and + treat only the canonical session's PR as real. ### Continue (the make-or-break step) @@ -60,6 +64,10 @@ session, reply **into the agent-session thread**, not at top level. the agent to push. - If no agent-session thread exists yet, the agent has not picked up the issue. Wait, re-check, or escalate; do not assume a top-level comment will be seen. +- A mid-session scope change is one authoritative in-thread reply that + explicitly supersedes earlier instructions. Never layer conflicting guidance + across dispatch notes, session replies, and top-level comments; the worker + will follow the wrong one. ### Liveness @@ -68,6 +76,12 @@ alive: agent-session thread reply, branch creation, branch push, PR creation, or check activity. The stuck-worker timeout is measured from the latest of those signals, not just from the initial delegation timestamp. +Tracker-thread silence plus no branch is not proof of death. When the provider +exposes a session dashboard or status API, check it before declaring a session +dead; a quiet remote agent is often still working. Default the stuck-worker +timeout for issue-assigned remote agents generously (30+ minutes from the last +signal) unless config tunes it. + When a session is quiet past the timeout, send one direct nudge to the continuation target before starting another worker, unless config or current evidence proves the original session cannot continue. Re-delegation is a @@ -88,6 +102,7 @@ Delegate only when **all** hold. Otherwise hard-refuse and heal or escalate. | `ready-for-agent` | no human refinement needed | refuse; route to triage/To Issues | | worker environment label (e.g. `remote-cursor`) | environment approved | apply if approval criteria met, else refuse | | repo-route label (e.g. `/`) | tells the agent which repo to clone | heal inline if team maps unambiguously to one repo; else escalate `needs-info` | +| configured required estimate | project wants sized agent handoff | route to triage or To Issues | | unblocked | safe to start | defer; never start blocked work | | complete agent-ready body | agent can verify | refuse; route to triage | | no active claim, no open PR | not already in flight | skip; advance the existing work instead | @@ -108,10 +123,11 @@ issue risk labels and the change shape. | MEDIUM | normal feature / business logic | skip unless review is uncertain | orchestrator may auto-merge when green | | HIGH | auth, secrets, payments, destructive data, schema/migration, queues/jobs, public contracts, broad refactors | required: run after local review is clean | human merge unless config grants the tier to the orchestrator | -"Green" is the configured merge-ready set: clean `ziw-review` verdict, +"Green" is the configured merge-ready set: clean independent +`ziw-code-review` verdict, required CI checks pass, no unresolved blocking review comments, PR non-draft and -ready-for-review, `Code review passed` current for the PR head, and required -CodeRabbit escalation complete or recorded as skipped by policy. +ready-for-review, the configured review evidence label current for the PR head, +and required CodeRabbit escalation complete or recorded as skipped by policy. Rules that do not change with tier: @@ -123,6 +139,14 @@ Rules that do not change with tier: a PR when repo policy allows. - Missing CodeRabbit auth, rate limits, or credits is a recorded skip unless the user explicitly required it. +- When the required external review for a HIGH-risk PR is unavailable (rate + limit, credits, outage), do not merge on a single local review. Route to + human merge or run a second independent local review pass, and record the + substitution. +- When the repo deploys on push, the production deploy status on the + default-branch HEAD is part of the post-merge gate. A green PR preview does + not prove a green production deploy, especially for schema changes validated + against production data the preview branch does not have. ## Resolving This Into Config @@ -139,5 +163,19 @@ values, not this file: - liveness signals, stuck-worker timeout, and the nudge-before-redelegate policy - the repo-route label family used for delegation - auto-merge risk tiers the orchestrator may merge vs route to human merge +- code-host PR attention labels the orchestrator applies when a PR needs human + action (default `needs-human-merge`, `needs-human-input`) +- review evidence label slug or ID, plus the evidence comment shape that records + PR URL and reviewed head SHA - merge method, required checks that define green, plus any post-merge preparation needed before local post-merge checks are trustworthy +- default-branch baseline health note: current required-check state and any + known-red jobs with the ticket that will fix them (`expected-red-until-`) +- the production deploy status check on the default-branch HEAD when the repo + deploys on push +- remote worker environment gate: whether repo hooks and gates actually install + and run in each remote or cloud worker environment (installers often skip + under a generic `CI=true`), and the exact pre-push commands the environment + enforces +- gate parity: the single verify entrypoint and the CI required job that + invokes it; any hosted check outside that entrypoint is drift to fix diff --git a/.agents/skills/ziw-setup/references/project-config.md b/.agents/skills/ziw-setup/references/project-config.md index b9855ec9..590be03b 100644 --- a/.agents/skills/ziw-setup/references/project-config.md +++ b/.agents/skills/ziw-setup/references/project-config.md @@ -26,6 +26,9 @@ Last updated: YYYY-MM-DD - Full local gate: - Local gate cache policy: - CI env passthrough: +- Separate threshold gates: coverage, smoke, secret scan, generated artifacts, or + none; include the exact local command for each hosted job not covered by the + full local gate - Coverage and secret-scan scope: - Focused checks: - Build: @@ -100,7 +103,9 @@ Last updated: YYYY-MM-DD - Worker environment labels: - Worker environment label policy: - remote-cursor: approved to run in the remote Cursor environment; does not mean unblocked or startable -- Startable work criteria: kind-slice, ready state, ready-for-agent, complete body, repo-route label when issue-assigned, no active blockers, no active claim or open PR +- Startable work criteria: kind-slice, ready state, ready-for-agent, complete + body, configured required estimate, repo-route label when issue-assigned, no + active blockers, no active claim or open PR - Done cleanup: remove ready-for-agent or the repo-configured readiness label when moving an issue to Done - Agent suitability policy: default agent work includes docs, tests, build/CI, @@ -111,12 +116,20 @@ Last updated: YYYY-MM-DD - Kind labels: kind-spec, kind-epic, kind-slice (single-select; skills enforce exclusivity; only kind-slice is dispatchable) - Risk labels: risk-normal, risk-security-sensitive, risk-schema, risk-cross-cutting - Risk label policy: use the default risk labels as dimensions, not severity levels; add repo-specific risk labels only when they change routing, checks, approvals, or reviewer assignment -- Review evidence labels: Code review passed +- Review evidence labels: exact configured label slugs or IDs (repo-specific; + record the real slug here, not an example) - Review evidence label policy: - - Code review passed: latest linked PR head SHA passed the configured code review gate; apply only with PR URL and reviewed head SHA evidence; remove when PR head changes, blocking findings appear, linked PR changes, or evidence is missing + - : latest linked PR head SHA passed the configured code review gate; apply only with PR URL and reviewed head SHA evidence; remove when PR head changes, blocking findings appear, linked PR changes, or evidence is missing - Type labels: Bug, Feature, Improvement, Tech Debt, Spike, Hotfix - Area labels: - Priority policy: +- Estimate field: tracker estimate field, estimate label family, configured body + heading, or none +- Estimate scale: numeric points, T-shirt sizes, hours, custom allowed values, + or none +- Estimate policy: whether To Issues and Issue Triage may set estimates, + whether estimates are optional or required before `ready-for-agent`, and what + to do when an estimate is missing or above the configured maximum - Dependency policy: dependency-ready `kind-slice` tickets stay in the configured ready state, usually `Todo`; blockers decide startability, not Linear Backlog placement @@ -127,11 +140,18 @@ Last updated: YYYY-MM-DD how Orchestrator verifies full scope before leaving multi-PR or partial-scope issues Done - File footprint convention: where To Issues records predicted files/packages per slice +- Shared document hotspot convention: whether footprints must name dense doc + list blocks, registries, status ledgers, changelogs, or config tables that + should serialize concurrent slices - Review-debt footprint convention: where Agent Review or triage records likely files/packages for review-created `kind-slice` tickets before Orchestrator can dispatch them - Agent-ready issue body: outcome, context docs, likely files/packages/artifacts, - scope, acceptance criteria, required checks, safety invariants, dependencies + scope, acceptance criteria, required checks, safety invariants, dependencies, + and estimate when body-backed estimates are configured +- Hard config literal policy: where exact provider resource IDs, secret names, + label slugs, environment values, and other worker-critical literals are + recorded so worker prompts do not depend on old issue comments - Labels are signals, not authority: ## Work Coordination @@ -144,11 +164,21 @@ Last updated: YYYY-MM-DD that have not yet produced a PR - Cap count policy: count each open PR once, add active previews that are not clearly linked to an already counted PR, then add unreturned implementation - dispatches. Obey any stricter preview-provider or worker-session limit + dispatches. Exclude bot dependency PRs (dependabot, renovate) from the cap; + track them as a separate drain count. Obey any stricter preview-provider or + worker-session limit +- Partitioned-scope cap semantics: when the queue is split across concurrent + orchestrator runs, record whether the cap is shared repo-wide or per scope, + and how each run counts the other's PRs and dispatches. Unset means one + repo-wide cap shared by all runs - Dispatch footprint policy: before fanning out startable work, compare predicted file or package footprints against active PRs, active worker branches, and other - selected candidates. Hold collisions or unknown footprints for triage or a later - tick; capacity headroom alone is not permission to dispatch + selected candidates, including shared document hotspots. Hold collisions or + unknown footprints for triage or a later tick; capacity headroom alone is not + permission to dispatch +- Worktree hygiene policy: configured disposable worktree root or prefixes, + prune command, and orphan-removal guard. Only orchestrator-owned disposable + worktrees may be removed automatically - Capacity drain policy: when active delivery slots are at or over cap, Orchestrator advances, merges, routes fixes, cleans up previews, or escalates existing PRs and previews before dispatching new implementation work @@ -210,6 +240,18 @@ Last updated: YYYY-MM-DD ## Agent Access - Local Codex: +- Workflow skill distribution: project skills, plugin or marketplace, managed + settings, user/global-only, or mixed +- Workflow skill source: `zaks-io/skills`, a pinned tag, a pinned commit SHA, + plugin marketplace entry, managed setting, or repo-local project-specific + skills +- Workflow skill lockfile: `skills-lock.json`, plugin marketplace lock, managed + setting, or none +- Workflow skill refresh command: +- Project skill paths: relative repo paths such as `.agents/skills/`, + `.claude/skills/`, or `node_modules/@org/skills/` +- Generated shared skill copies: committed dependency, symlink fanout, ignored + local cache, absent, or repo-authored project-specific skills - Issue-assigned agents: none, or project-specific routing/continuation notes - Issue-assigned delegation: tool or field, verified agent names or IDs, and continuation path - Issue-assigned continuation replies: reply into the agent-session thread (its thread-root comment's parentId); top-level issue comments are not continuation unless verified here. For Linear + Cursor this is the "agent session" thread; record the session handle (such as the cursor.com/agents/bc-id URL) diff --git a/.agents/skills/ziw-to-issues/SKILL.md b/.agents/skills/ziw-to-issues/SKILL.md index f6dbbe9a..d1daa9a4 100644 --- a/.agents/skills/ziw-to-issues/SKILL.md +++ b/.agents/skills/ziw-to-issues/SKILL.md @@ -1,6 +1,6 @@ --- name: ziw-to-issues -description: Use to turn a spec, PRD, or epic ticket into dependency-ordered one-PR implementation tickets, adopting any hand-created tickets, applying the agent-ready body contract and kind labels, and emitting a dependency graph and predicted file footprint. +description: Use to turn a spec, PRD, or epic ticket into dependency-ordered one-PR implementation tickets, adopting any hand-created tickets, applying the agent-ready body contract, configured estimates, and kind labels, and emitting a dependency graph and predicted file footprint. argument-hint: "[spec-doc|prd-ticket|epic-ticket|project]" disable-model-invocation: true --- @@ -15,6 +15,11 @@ the user created by hand. To Issues creates and shapes tickets. It does not implement, review, or move active work. Spec or epic tickets are input containers, not work to ship. +Flows that file tickets outside To Issues, such as review sweeps or eval +sessions, must either run this intake pass or leave readiness labels off so +the gap stays visible. A hand-filed ticket carrying `ready-for-agent` without +intake metadata is a dispatch hazard. + ## Inputs - A spec doc, PRD ticket, epic ticket, plan, or project to turn into issues. @@ -33,6 +38,7 @@ Confirm before creating or editing tickets: - status names, the configured ready state, and intake states - kind label set and its single-select policy - readiness, risk, type, and area labels and their policies +- estimate field, scale, and requiredness policy - agent-ready issue body contract - dependency and blocker fields - file footprint convention from config @@ -115,6 +121,7 @@ contract: - required checks - security, privacy, data, and operational invariants - dependencies or blockers +- estimate when config stores estimates in the body If a required field is unknowable from the plan, add the heading, mark the ticket `needs-info`, leave the specific question, and do not mark it ready. Do not @@ -130,6 +137,11 @@ Record deploy prerequisites, runtime secrets, hosted gates, generated artifact updates, and CI env passthrough requirements as explicit acceptance criteria or required checks. Do not bury launch blockers only in background docs. +When a slice depends on exact external config, resource IDs, provider names, +label slugs, secret names, or environment values, put the exact configured +literals or their config lookup location in the body. Do not rely on prior issue +comments as the only source for hard values a worker must use. + Prefer slices that match known strong agent-fit work: docs, tests, build or CI updates, small refactors with clear checks, scoped bugs with reproduction, and isolated UI changes with target states. Mark high-risk or ambiguous work for @@ -142,16 +154,43 @@ Name the authenticated actor, tenant or resource binding, replay behavior, atomic consume or claim requirement, and concurrency checks the worker must prove. +For custody, persistence, driver-integration, or provider-integration slices, +give acceptance criteria an executable shape that exercises the real boundary. +Prefer checks such as multi-instance readback, concurrent first use, real driver +queries, env passthrough, or provider-shape verification over prose-only +assertions. Do not make a mock of the integrated seam the only proof. + +For slices that drop or narrow schema on retained data, put the deploy order in +the acceptance criteria: pre-deploy data cleanup must land before the schema +change deploys when the platform validates the new schema against existing +rows, and bulk migrations must use a resumable batched runner, not a single +transaction. Name the production deploy status that proves the change landed; a +green preview does not prove the production deploy. + +## Estimates + +Follow the Estimate Rules in +[../ziw-setup/references/issue-tracker-contract.md](../ziw-setup/references/issue-tracker-contract.md): +estimate each `kind-slice` after splitting to one PR, using only the +configured field and scale, and omit estimates when config defines none. If +estimates are required before `ready-for-agent` and a value is unknowable from +the plan, leave the exact question, apply `needs-info` or `ready-for-human`, +and do not mark the ticket ready. + ## Labels And Readiness For each `kind-slice`: - apply one type and one risk label from config - apply routing and area labels from config +- apply the configured estimate when the estimate policy grants To Issues that + authority - apply the configured worker environment label only when the environment approval criteria are met; dependency state is not a reason to withhold it - apply `ready-for-agent` only when the slice is scoped to one PR, routed, - type and risk labeled, and complete enough to verify + type and risk labeled, estimated if required, and complete enough to verify +- do not apply `ready-for-agent` when the body itself says human setup, + credentials, provider decisions, or security judgment are still required - place ready `kind-slice` issues in the configured ready state, usually `Todo`, even when they are blocked by other tickets; do not park implementation-ready slices in Linear `Backlog` @@ -176,6 +215,10 @@ run safe work in parallel. - Serialize slices that must not run concurrently even without a direct data dependency, such as shared schema or migration ordering, using the configured dependency mechanism. +- When several slices converge on the same core files or regenerate the same + shared artifact, sequence the convergent slice to land first or immediately + adjacent to its siblings, or serialize the cohort. Same-base siblings all + conflict the moment one merges. - Encoding a dependency never removes `ready-for-agent`, the configured ready state, or a worker environment label. @@ -186,6 +229,9 @@ configured location and shape, so the orchestrator can avoid dispatching colliding slices concurrently. - List the files, directories, or packages the slice is most likely to change. +- Include shared document surfaces the slice is likely to edit, such as dense + markdown list blocks, status ledgers, registries, changelogs, config tables, + and docs sections owned by many slices. - Keep it a prediction, not a guarantee; the worker may diverge. - Flag slices with heavy expected overlap so they are serialized or sequenced. - Compare sibling slices after assigning individual footprints. Record hot files @@ -222,6 +268,7 @@ Report: - source plan and target location - slices created, slices adopted, and duplicates converged - kind labels set and any kind contradictions healed +- estimates set, preserved, omitted by policy, or left with exact questions - tickets marked `ready-for-agent`, `needs-info`, or `ready-for-human` - dependency graph and any cycles or required serializations - file footprints recorded and overlaps flagged diff --git a/.agents/skills/ziw-to-issues/agents/openai.yaml b/.agents/skills/ziw-to-issues/agents/openai.yaml index 478d68c5..d39e0264 100644 --- a/.agents/skills/ziw-to-issues/agents/openai.yaml +++ b/.agents/skills/ziw-to-issues/agents/openai.yaml @@ -1,6 +1,6 @@ interface: display_name: "To Issues" short_description: "Spec or PRD into ready slices" - default_prompt: "Use $ziw-to-issues to break this spec, PRD, or epic ticket into dependency-ordered one-PR implementation tickets, adopt any existing tickets, apply the agent-ready body contract and kind labels, and emit the dependency graph and file footprint." + default_prompt: "Use $ziw-to-issues to break this spec, PRD, or epic ticket into dependency-ordered one-PR implementation tickets, adopt any existing tickets, apply the agent-ready body contract, configured estimates, and kind labels, and emit the dependency graph and file footprint." policy: allow_implicit_invocation: false diff --git a/.agents/skills/ziw-triage/SKILL.md b/.agents/skills/ziw-triage/SKILL.md index a67bb2de..10baeb45 100644 --- a/.agents/skills/ziw-triage/SKILL.md +++ b/.agents/skills/ziw-triage/SKILL.md @@ -1,6 +1,6 @@ --- name: ziw-triage -description: Use for issue tracker triage when reconciling current project issues with reality, making Todo tickets agent-ready, applying workflow labels, setting dependencies, normalizing issue bodies, cleaning explicitly requested Linear Backlog review or backfill scope separately from configured intake issues, and updating verified stale states. +description: Use for issue tracker triage when reconciling current project issues with reality, making Todo tickets agent-ready, applying workflow labels, setting dependencies and configured estimates, normalizing issue bodies, cleaning explicitly requested Linear Backlog review or backfill scope separately from configured intake issues, and updating verified stale states. argument-hint: "[project-url|team|repo|filter]" disable-model-invocation: true --- @@ -35,8 +35,8 @@ label and return the exact questions or next actions needed. - Issue tracker project, team, repo, board, roadmap, query, or explicit Linear `Backlog` state scope. - Repo path and `docs/agents/workflow/config.md`. -- Existing tracker teams, projects, statuses, labels, priorities, dependencies, - parent or child relationships, PR links, and issue comments. +- Existing tracker teams, projects, statuses, labels, priorities, estimates, + dependencies, parent or child relationships, PR links, and issue comments. - Optional user instructions for first-run intake backfill, first-run Linear Backlog backfill, dry run, priority policy, Linear Backlog review, intake cleanup, or orphan routing. @@ -54,7 +54,7 @@ Confirm these config values before mutating the issue tracker: environment labels - readiness label policy, worker environment label policy, and startable work criteria -- priority policy, dependency policy, and orphan policy +- priority policy, estimate policy, dependency policy, and orphan policy - agent-ready issue body contract - active workflow status transition owner - Issue Triage intake-state transition authority @@ -108,9 +108,10 @@ when an orchestrator tick delegates this triage repair. For the requested Linear Backlog or intake scope: - promote now: complete `kind-slice` issues with route, labels, body contract, - readiness, worker environment approval, and dependency blockers encoded + readiness, configured required estimate, worker environment approval, and + dependency blockers encoded - needs human review: issues missing product, security, credential, customer, - ADR, priority, or acceptance-criteria decisions + ADR, priority, required estimate, or acceptance-criteria decisions - needs To Issues: `kind-spec`, `kind-epic`, project notes, vague plans, or multi-PR work that must be split before dispatch - leave parked: uncommitted ideas or intentionally parked work the user does not @@ -167,7 +168,7 @@ Apply obvious mechanical updates in batches: - route orphan issues into the configured project, team, or parent when evidence is direct - make configured ready-state issues, usually `Todo`, match the agent-ready body - contract, labels, blockers, and route + contract, labels, estimates when configured, blockers, and route - move issues from configured intake states such as `Triage` or equivalent to the configured ready state only when the user asked for intake cleanup or intake backfill and routing, labels, and the agent-ready body contract are @@ -192,6 +193,7 @@ Apply obvious mechanical updates in batches: - recommend moving issues out of done or merge-ready states when current external state proves the status is wrong, such as a closed-unmerged PR or reverted work - add missing routing, type, risk, area, kind, and readiness labels from config +- add or preserve estimates according to the configured estimate policy - set exactly one `kind-*` value and clear the others; keep `kind-spec` and `kind-epic` as containers and never mark a container `ready-for-agent` - normalize review-created findings: make concrete one-PR findings @@ -214,9 +216,9 @@ Apply obvious mechanical updates in batches: - apply configured review, merge-ready, or blocked states only when the repo config gives Issue Triage that authority and current external evidence is direct -- remove stale `Code review passed` when the linked PR head changed, blocking - findings exist, the linked PR changed, or reviewed head SHA evidence is - missing +- remove the configured review evidence label when the linked PR head changed, + blocking findings exist, the linked PR changed, or reviewed head SHA evidence + is missing - mark duplicates only when the duplicate relationship is clear and preserve the canonical issue @@ -252,6 +254,7 @@ An issue can receive `ready-for-agent` only when it is: - scoped to one PR - assigned to the configured project or route - labeled with one clear type and risk +- estimated when config requires estimates before handoff - complete enough for Agent Implement to verify By default, `ready-for-agent` means the ticket needs no further human refinement @@ -271,11 +274,23 @@ Required body content: - required checks - security, privacy, data, and operational invariants - dependencies or blockers +- estimate when config stores estimates in the body If any required field is unknowable, add the missing heading, ask the specific question when the user is available, label the issue `needs-info` or `ready-for-human`, and do not mark it ready. +If an issue carries `ready-for-agent` but the body says it is waiting on human +setup, credentials, provider decisions, security judgment, or a +`ready-for-human` rationale, treat the body as the stronger signal. Remove or +withhold `ready-for-agent`, preserve the exact human decision needed, and report +the contradiction. + +When a ticket depends on exact external config, resource IDs, provider names, +label slugs, secret names, or environment values, make sure those hard literals +or their config lookup location are in the body before marking it ready. Prior +comments are not enough for worker handoff. + When deciding whether a ticket should become agent-ready, consider the work type and risk. Docs, tests, build or CI updates, small local refactors, scoped bugs with reproduction, and isolated UI changes are good default agent work. @@ -311,6 +326,12 @@ Detect cycles, blockers that are done or canceled, parent issues marked ready, and issues blocked by vague placeholder work. Fix obvious completed blockers. Escalate ambiguous ordering instead of guessing. +When a blocker has completed, compare the dependent ticket's body against the +landed blocker or sibling PR evidence before declaring it ready to start. If the +body names APIs, files, commands, or mechanics that the landed work removed or +superseded, narrow the residual scope or mark the ticket for human/triage +repair instead of sending stale instructions to an implementation worker. + Do not use dependencies as a reason to withhold or remove `ready-for-agent` or a configured worker environment label. Encode dependency order with tracker relationships, blocker fields, body text, or workflow state so Agent @@ -351,12 +372,22 @@ Use the configured priority policy. Good signals are: Do not turn personal preference into priority. When priority is unclear, leave it neutral and mark the issue for human triage. +## Estimates + +Follow the Estimate Rules in +[../ziw-setup/references/issue-tracker-contract.md](../ziw-setup/references/issue-tracker-contract.md). +Set missing estimates only when current scope is clear and config grants Issue +Triage that authority. Missing estimates block `ready-for-agent` only when +config requires estimates before handoff; otherwise leave the estimate empty +and keep triage focused on body completeness, labels, blockers, and verified +state. + ## First Run For first-run intake or Linear Backlog backfill: -1. Snapshot current project counts by status, label, priority, dependency state, - and readiness. +1. Snapshot current project counts by status, label, priority, estimate state, + dependency state, and readiness. 2. Create missing workflow labels only when names are exact and config-approved. 3. Normalize orphan routing and body headings before setting priorities. 4. Include Linear `Backlog` or equivalent out-of-work-queue states only if the @@ -398,7 +429,7 @@ Report: - whether Linear Backlog or intake states were skipped or explicitly included - issues changed, unchanged, and needing human decision - orphans routed or left with reasons -- labels, priorities, body contracts, dependency tree, and status +- labels, priorities, estimates, body contracts, dependency tree, and status recommendations updated - ready-state issues made agent-ready or left with exact blockers - review-debt intake issues normalized, promoted, left for To Issues, or left for diff --git a/.agents/skills/ziw-triage/agents/openai.yaml b/.agents/skills/ziw-triage/agents/openai.yaml index 8324e6ce..d3f55656 100644 --- a/.agents/skills/ziw-triage/agents/openai.yaml +++ b/.agents/skills/ziw-triage/agents/openai.yaml @@ -1,6 +1,6 @@ interface: display_name: "Issue Triage" short_description: "Shape tracker tickets" - default_prompt: "Use $ziw-triage to triage current project tracker issues, make Todo tickets ready for agents, reconcile verified stale states, update labels, dependencies, orphans, and clean explicitly requested Linear Backlog review or backfill scope separately from configured intake issues." + default_prompt: "Use $ziw-triage to triage current project tracker issues, make Todo tickets ready for agents, reconcile verified stale states, update labels, estimates only when the configured estimate policy grants triage that step, dependencies, orphans, and clean explicitly requested Linear Backlog review or backfill scope separately from configured intake issues." policy: allow_implicit_invocation: false diff --git a/skills-lock.json b/skills-lock.json index 0db346e2..253571ba 100644 --- a/skills-lock.json +++ b/skills-lock.json @@ -5,25 +5,25 @@ "source": "zaks-io/skills", "sourceType": "github", "skillPath": "skills/ziw-code-review/SKILL.md", - "computedHash": "aa3ab6227d74531948e432ef48356a632b33642d96b8b18e9758a39103e69198" + "computedHash": "97af3b05fbb1432092e93c2b9c4fa9b973196aad826e3b1eb9300b3dbd3dce88" }, "ziw-implement": { "source": "zaks-io/skills", "sourceType": "github", "skillPath": "skills/ziw-implement/SKILL.md", - "computedHash": "d049118bf68b7aad6546f47c84ef55007a48b941c7f818ac3a6cb6b2bda0028f" + "computedHash": "1310d189e38890a5a0b621aedf99fb87bf6c6d669b2db6fec4dbd40386e84619" }, "ziw-orchestrate": { "source": "zaks-io/skills", "sourceType": "github", "skillPath": "skills/ziw-orchestrate/SKILL.md", - "computedHash": "93ae3b359689f40833f97dbc390ee0644d81af94d066424f72ce4323409eb570" + "computedHash": "4cc90f9a3c43f31aba47cb07170f21f66a9bb8c6e0572cd81b8871cd8d2ec064" }, "ziw-pr": { "source": "zaks-io/skills", "sourceType": "github", "skillPath": "skills/ziw-pr/SKILL.md", - "computedHash": "34ebc85e33ff72547debc9c0783f123579060eb8249829215caf7a36a09ac73f" + "computedHash": "b8b1a8c5fb16057f10d7519b58c4a577f41adbc2681f0c8ded8810f4b7599a3f" }, "ziw-review": { "source": "zaks-io/skills", @@ -35,19 +35,19 @@ "source": "zaks-io/skills", "sourceType": "github", "skillPath": "skills/ziw-setup/SKILL.md", - "computedHash": "a715317826d974eec1d27f2d1199ed4c651a485746f447bb6da6e8ee78454218" + "computedHash": "7b77d8bf8a7a3d7624b3e4f85dd5586048bea6c4d50c2b2e0529a6c8a605880a" }, "ziw-to-issues": { "source": "zaks-io/skills", "sourceType": "github", "skillPath": "skills/ziw-to-issues/SKILL.md", - "computedHash": "29474f3dcd91d4debea538d17dc045a68872637830300a3f6741db509b088820" + "computedHash": "7fba01f4f88c3d0d94213ca8372cfbca22eee654b7dbaffcaab5cb3d0c0cf698" }, "ziw-triage": { "source": "zaks-io/skills", "sourceType": "github", "skillPath": "skills/ziw-triage/SKILL.md", - "computedHash": "dd1688e2eff9cef9f5ed163f88496930b18535060ed8dd4e72937a921fcdcdcf" + "computedHash": "ad07fe1cfcf0cd941fd50cbdd1483a28a900c8a1fe8c34693731dcb45fe212e3" } } }