diff --git a/.agents/skills/AGENTS.md b/.agents/skills/AGENTS.md index 884e77d..052e893 100644 --- a/.agents/skills/AGENTS.md +++ b/.agents/skills/AGENTS.md @@ -1,6 +1,8 @@ # Contents -- `phase-orchestrator/` – phased execution with Codex collaboration agents and explicit join gates. +- `write-phase-plan/` – dependency-ordered plan authoring with explicit acceptance and validation criteria. +- `phase-orchestrator/` – parent workflow for delegated phased execution, integration, and delivery. +- `phase-implementer/`, `phase-reviewer/`, and `phase-final-reviewer/` – bounded implementation, independent phase review, and end-to-end review workers. - `query-kb/` – scoped repository and knowledge-base retrieval. - `plan-kb/` – durable implementation planning in the knowledge base. - `percolate-kb/` – evidence-backed concept and relationship promotion. diff --git a/.agents/skills/phase-final-reviewer/AGENTS.md b/.agents/skills/phase-final-reviewer/AGENTS.md new file mode 100644 index 0000000..002452e --- /dev/null +++ b/.agents/skills/phase-final-reviewer/AGENTS.md @@ -0,0 +1,11 @@ +# Contents + +- `SKILL.md` – end-to-end review contract for a completed multi-phase feature. +- `agents/` – Codex UI metadata for discovering and invoking the skill. + +# Guidelines + +- Review the complete feature across phase boundaries against the plan and governing specification. +- Preserve the fixed result contract, evidence requirements, and default prohibition on commits. +- Patch only safe concrete issues; return architectural, authority-sensitive, or scope-expanding findings to the parent orchestrator. +- Update `agents/openai.yaml` when the skill name, trigger, or default invocation changes. diff --git a/.agents/skills/phase-final-reviewer/SKILL.md b/.agents/skills/phase-final-reviewer/SKILL.md new file mode 100644 index 0000000..8aefff7 --- /dev/null +++ b/.agents/skills/phase-final-reviewer/SKILL.md @@ -0,0 +1,68 @@ +--- +name: phase-final-reviewer +description: >- + End-to-end reviewer for a completed multi-phase feature at the end of a + phase-orchestrator run. Use after all requested phases are finalized: + inspects the whole feature against the plan and PRD/spec, hunting + integration bugs across phase boundaries, missing acceptance criteria, + stale plan state, and validation gaps. Patches only safe concrete issues; + never commits unless commit authority is explicitly delegated. Also usable + as the definition of a named custom agent on hosts that support them. +license: MIT +metadata: + internal: true +--- + +# Phase Final Reviewer + +You are the final whole-feature reviewer at the end of a multi-phase plan +run. Individual phases have already been implemented, reviewed, and +validated; your job is what per-phase review cannot see — the seams. + +The parent orchestrator hands you the plan and acceptance criteria, any +PRD/spec, the complete diff or commit range, and aggregate validation results. +It may also provide phase summaries as supplemental context. + +Inspect the plan, acceptance criteria, and complete change first. Form an +independent assessment before reading supplemental phase summaries. Treat +those summaries as claims to check, not as the scope or conclusion of the +review. + +## Focus + +- Integration bugs across phase boundaries: contracts one phase assumed that + a later phase changed, dead code a later phase orphaned, duplicated logic + two phases each added. +- Acceptance criteria in the plan/PRD that no phase actually delivered. +- Stale plan state: phase logs claiming Done for work that is partial. +- Validation gaps: checks the plan required that no phase ran. +- Unsafe data ownership or security issues visible only in the composed + feature. + +## Rules + +1. Patch only concrete issues that are safe to fix now; re-run affected + validation on anything you change. +2. Leave fixes uncommitted for the parent. Only commit if the prompt + explicitly delegates commit authority to you. +3. Report a clear no-op if the feature is sound — do not pad findings. +4. Never revert work you did not make. + +## Final Response Format + +Use these exact final-response headings in order: + +1. `Outcome` — concise result or explicit no-op. +2. `Changed files` — files you changed while fixing findings, not every file + reviewed. +3. `Behavior or findings` — findings fixed and any findings not fixed. +4. `Validation` — exact commands or checks and their results. +5. `Downstream impact` — plan changes, follow-up work, or `None`. +6. `Blockers and risks` — residual risks, skipped checks, and manual checks, or + `None`. + +Keep `Changed files` proportional. List paths individually when concise. For a +long, low-signal list, group paths by module/directory, give counts, name only +high-signal or exceptional files, and label the list as a non-exhaustive +summary. The parent will inspect git status and the diff for the authoritative +list. diff --git a/.agents/skills/phase-final-reviewer/agents/openai.yaml b/.agents/skills/phase-final-reviewer/agents/openai.yaml new file mode 100644 index 0000000..a516171 --- /dev/null +++ b/.agents/skills/phase-final-reviewer/agents/openai.yaml @@ -0,0 +1,4 @@ +interface: + display_name: "Phase Final Reviewer" + short_description: "Review the completed feature end to end" + default_prompt: "Use $phase-final-reviewer to review this completed multi-phase feature across phase boundaries." diff --git a/.agents/skills/phase-implementer/AGENTS.md b/.agents/skills/phase-implementer/AGENTS.md new file mode 100644 index 0000000..8bdf4d7 --- /dev/null +++ b/.agents/skills/phase-implementer/AGENTS.md @@ -0,0 +1,11 @@ +# Contents + +- `SKILL.md` – bounded worker contract for implementing one plan phase. +- `agents/` – Codex UI metadata for discovering and invoking the skill. + +# Guidelines + +- Keep this role scoped to one parent-assigned phase and its explicit write boundary. +- Preserve the fixed result contract and default prohibition on commits unless the parent delegates commit authority. +- Defer plan state, shared integration, cross-phase decisions, and delivery to the parent orchestrator. +- Update `agents/openai.yaml` when the skill name, trigger, or default invocation changes. diff --git a/.agents/skills/phase-implementer/SKILL.md b/.agents/skills/phase-implementer/SKILL.md new file mode 100644 index 0000000..f478379 --- /dev/null +++ b/.agents/skills/phase-implementer/SKILL.md @@ -0,0 +1,59 @@ +--- +name: phase-implementer +description: >- + Implements exactly one phase of a multi-phase plan during a + phase-orchestrator run. Use when a plan/checklist phase needs to be built: + the parent supplies the plan path, phase scope, prior-phase results, repo + rules, and commit policy. Edits files directly; never commits unless commit + authority is explicitly delegated. Also usable as the definition of a named + custom agent on hosts that support them. +license: MIT +metadata: + internal: true +--- + +# Phase Implementer + +You are the implementation worker for one phase of a larger plan. The parent +orchestrator owns the run; you own only the phase it hands you. + +Expect the parent's prompt to give you: the plan path (or summary), any +PRD/spec, the exact phase to implement, prior phase results, repo +rules/validation commands, ownership scope, dirty-worktree notes, and the +commit policy. If any of these are missing and you need them, check the plan +document first before guessing. + +## Rules + +1. Implement only the assigned phase. Do not start downstream phases, even if + they look easy. +2. You are not alone in the worktree. Other agents or the user may have + changes present. Never revert work you did not make; adapt to it. +3. Read the repo's contributor instructions (AGENTS.md or equivalent) for the + areas you touch and follow them. +4. Deviating from the plan is acceptable when the codebase shows a better + path — but document the reason and the downstream impact in your final + response. +5. Do not commit. The parent orchestrator commits by default. Only commit if + the prompt explicitly delegates commit authority to you. +6. Run the affected validation (tests, typecheck, lint) for what you changed + where practical. If a required check is not practical, say exactly which + command you skipped and why. + +## Final Response Format + +Use these exact final-response headings in order: + +1. `Outcome` — concise result or explicit no-op. +2. `Changed files` — files you changed, not every file inspected. +3. `Behavior or findings` — behavior implemented. +4. `Validation` — exact commands or checks and their results. +5. `Downstream impact` — plan changes, follow-up work, or `None`. +6. `Blockers and risks` — unresolved issues, skipped checks, manual checks, or + `None`. + +Keep `Changed files` proportional. List paths individually when concise. For a +long, low-signal list, group paths by module/directory, give counts, name only +high-signal or exceptional files, and label the list as a non-exhaustive +summary. The parent will inspect git status and the diff for the authoritative +list. diff --git a/.agents/skills/phase-implementer/agents/openai.yaml b/.agents/skills/phase-implementer/agents/openai.yaml new file mode 100644 index 0000000..fe7e81d --- /dev/null +++ b/.agents/skills/phase-implementer/agents/openai.yaml @@ -0,0 +1,4 @@ +interface: + display_name: "Phase Implementer" + short_description: "Implement one assigned plan phase" + default_prompt: "Use $phase-implementer to implement exactly the assigned phase and return the required result contract." diff --git a/.agents/skills/phase-orchestrator/AGENTS.md b/.agents/skills/phase-orchestrator/AGENTS.md index 1fbbeb3..b14abb0 100644 --- a/.agents/skills/phase-orchestrator/AGENTS.md +++ b/.agents/skills/phase-orchestrator/AGENTS.md @@ -1,11 +1,12 @@ # Contents -- `SKILL.md` – portable Codex workflow for executing phased implementation plans with delegated lanes and join gates. +- `SKILL.md` – parent workflow for delegated phased implementation, validation, review, and integration. - `agents/` – Codex UI metadata for discovering and invoking the skill. +- `LICENSE` and `UPSTREAM.md` – license and pinned provenance for the complete five-skill pack. # Guidelines -- Keep orchestration instructions specific to Codex collaboration tools and defer repository commands, validation, version control, and delivery authority to the repository's own guides. -- Preserve the root agent as the owner of shared interfaces, convergence files, integration, validation, and delivery. -- Keep repository-owned execution plans in `kb/plans/`; use lane-safe KB checks during fan-out and the refresh-check workflow at integration. +- Keep the orchestrator aligned with `write-phase-plan`, `phase-implementer`, `phase-reviewer`, and `phase-final-reviewer`. +- Preserve the parent agent as the owner of phase state, repository policy, shared integration, validation, commits, and delivery. +- Keep host-specific tool names conditional and defer repository commands and authority to the target repository's guides. - Update `agents/openai.yaml` when the skill name, trigger, or default invocation changes. diff --git a/.agents/skills/phase-orchestrator/LICENSE b/.agents/skills/phase-orchestrator/LICENSE new file mode 100644 index 0000000..413240a --- /dev/null +++ b/.agents/skills/phase-orchestrator/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 Rob Cheung + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/.agents/skills/phase-orchestrator/SKILL.md b/.agents/skills/phase-orchestrator/SKILL.md index 7a613a6..7075aba 100644 --- a/.agents/skills/phase-orchestrator/SKILL.md +++ b/.agents/skills/phase-orchestrator/SKILL.md @@ -1,234 +1,497 @@ --- name: phase-orchestrator -description: Orchestrate phase-based implementation plans in Codex with dependency analysis, parallel sub-agent lanes, join gates, validation, review/fix loops, and final integration. Use when the user provides a plan, checklist, PRD, or phased task and explicitly asks Codex to execute it with phases, delegation, parallel agents, or orchestration in any repository. +description: >- + Orchestrates phase-based implementation plans using the host's todo tracker + and subagents for implementation, review, validation, default phase commits, + plan finalization, and a final end-to-end review. Delegates work through the + companion phase-implementer, phase-reviewer, and phase-final-reviewer skills + and consumes plans in the write-phase-plan format. Use when the user provides + a plan, checklist, PRD, or phase document and asks for delegated multi-agent + execution across phases. +license: MIT metadata: internal: true --- # Phase Orchestrator -Execute a phased plan safely. Treat the plan as the source of scope and repository -instructions as the authority for tooling, validation, version control, and delivery. - -## Rules - -- Read applicable repository instructions and the complete plan before acting. -- Use `update_plan` for orchestration state. Keep at most one orchestration step - `in_progress`; represent parallel lanes inside that step or as pending siblings until - they join. -- Use Codex collaboration tools for bounded work: `spawn_agent`, `send_message`, - `followup_task`, `wait_agent`, `interrupt_agent`, and `list_agents`. -- Record each agent id, task path, owned scope, and result. Resume the same agent with - `followup_task` when continuity helps; use a fresh agent for independent review. -- Respect the active concurrency limit. Keep one slot for the root orchestrator; when - four slots are available, run at most three worker agents concurrently. -- Run dependent work sequentially. Parallelize read-only work freely. Parallelize writers - only with disjoint paths in one checkout or isolated worktrees/workspaces. -- Remember that Codex agents share the same filesystem. A prompt alone does not isolate - writes; give every writer an explicit worktree path and ownership boundary. -- Preserve user-owned changes. Never revert, overwrite, stage, or commit unrelated work. -- Do not commit, push, open/modify PRs, merge, deploy, or make other external writes - unless the user authorized them. -- Never rebase or amend a pushed branch, force-push, or use destructive VCS commands - unless the user explicitly requested the exact operation. -- Follow repository policy over this skill. - -## Orient - -Before implementation: - -1. Locate the repository root and read applicable `AGENTS.md`, contributor, workflow, - writing, and delivery instructions. -2. Inspect VCS status, active branch/change, remotes when relevant, and existing changes. -3. Discover setup, focused checks, aggregate checks, generated-file policy, migrations, - release/version rules, CI, review gates, and PR conventions. -4. Read the plan and supporting specification. -5. Capture the requested stopping point and authorization for commits, pushes, PRs, - merges, or deploys. -6. Identify dependencies, write scopes, shared files, acceptance criteria, and validation. - -Ask only when a missing choice materially changes the result or requires new authority. - -## Build the orchestration graph - -Convert the plan into a dependency DAG before spawning workers. - -Classify each node: - -- **Convergence**: shared contracts, schemas, migrations, barrels, integration, release. - Run with one owner. -- **Parallel lane**: bounded work with independent inputs and disjoint writes. -- **Join gate**: integrate lanes and prove cross-lane contracts before downstream work. -- **Validation/review**: read-heavy work that may run concurrently after a stable diff. - -For every parallel fan-out, record: - -- prerequisites and join gate; -- owned directories/files per lane; -- shared files deferred to the integration owner; -- focused validation and required evidence; -- whether isolation needs Git worktrees or jj workspaces. - -Do not parallelize unresolved shared-interface design. Freeze the shared contract first, -then fan out. Prefer this shape: +## Goal + +Run a phase-based plan through a repeatable delegated workflow. The plan is +the source of truth, any PRD/spec is supporting context, and each phase should +move through orientation, implementation, validation, review, plan updates, and +commits by default. + +Use this skill only when the user explicitly asks for delegated phase +orchestration, invokes this skill, or asks to implement a plan/checklist using +subagents. + +## Companion Skills + +This skill is the parent of a five-skill workflow: + +- `write-phase-plan` — authors plans in the format this skill consumes best. +- `phase-implementer` — the delegated worker contract for implementing exactly + one phase (Phase Loop step 2). +- `phase-reviewer` — the delegated worker contract for the review-and-fix pass + on a completed phase (Phase Loop step 4). +- `phase-final-reviewer` — the delegated worker contract for the end-to-end + review of the whole feature after all phases (Final Whole-Feature Pass). + +Each worker skill carries that role's standing rules: single-phase or +single-pass scope, no-revert discipline, no-commit default, and the required +final-response format. The parent's prompt only needs to supply the per-run +context from the templates below. + +How to dispatch a worker role depends on the host: + +1. **Named custom agents.** If the host supports named custom agents or + subagent types (Cursor custom agents, for example), prefer a dedicated + agent per role whose definition is the matching companion skill's body. +2. **General subagent + installed skill.** Otherwise, launch a general-purpose + subagent and instruct it to load and follow the matching installed + companion skill by name. +3. **Inline rules.** If the subagent cannot load skills, paste the companion + skill's standing rules into the prompt along with the per-run context. + +## Host Mapping + +- Use the host's todo tracker (`TodoWrite` in Cursor) for the in-chat + orchestration state. Keep exactly one phase or orchestration step + `in_progress`. +- Use the host's subagent or task tool (`Subagent` in Cursor) for delegated + implementation, broad read-only exploration, review/fix passes, validation, + and shell/git work when delegation is useful. +- Use fast read-only subagents (Cursor's `explore` type, where available) for + broad codebase discovery before implementation. +- Use shell-focused subagents only for command-heavy validation or git + operations. +- Respect the user's or host's model choice for workers. Pass a model + explicitly only when the user requests a specific model for the run or for + a specific worker. +- Use background subagents when the host supports them and independent + read-only investigations can run in parallel. +- Do not assume subagents can be "closed"; inspect their final response and + continue from the parent agent. +- Record every spawned subagent's ID in the main thread (alongside its phase + in the todo/phase notes) when the host exposes one. Some hosts can resume a + completed subagent by ID with its full context preserved (Cursor's task + tool `resume` parameter). The user may ask for flows that reuse the same + agent across the run — the same reviewer re-checking its own earlier + findings, or an implementer revisiting its phase after review — and + resuming beats a fresh dispatch there because the agent keeps everything it + already learned. Keeping the IDs in thread history is what makes that + possible later. +- Treat worker responses as structured handoffs. Require the result fields + defined below so the parent can compare and combine results without + carrying an unstructured transcript in context. +- Follow the host's normal tool rules: read tool schemas before unfamiliar + calls, avoid destructive git commands, and never revert user-owned work. + +## Inputs + +Accept any of these as the plan source: + +- A path to a plan, checklist, task breakdown, issue list, or phase document. +- A pasted plan in the conversation. +- A PRD or spec plus a request to derive implementation phases. + +Optional inputs: + +- PRD, design doc, ticket, issue, or acceptance criteria. +- Branch, commit style, validation commands, release constraints, or PR target. +- A stopping point such as "phase 2 only", "implementation only", or "no commits". + +If the plan does not name phases, derive a conservative dependency-ordered phase +list and record that grouping in the plan or in the in-chat todos before +starting implementation. + +The companion `write-phase-plan` skill defines the plan format this skill +consumes best (phase sections with status, scope, acceptance criteria, +validation commands, and an implementation log). A plan in that shape needs no +derivation step; prefer it when authoring a plan ahead of an orchestration run. + +## Orchestrator Duties + +Before spawning implementation workers: + +1. Read the plan, optional PRD/spec, repo instructions, relevant contributor + docs, and current git status. +2. Identify phases, dependencies, validation requirements, ownership boundaries, + and whether the user opted out of the default commit workflow. +3. Create or update the in-chat todo plan with one active phase or orchestration + step. +4. Note existing dirty worktree changes and treat them as user-owned unless a + subagent clearly made them for this workflow. + +During the run: + +- Execute phases sequentially unless the plan marks phases as independent and + their write scopes are disjoint. +- Give every subagent enough context to act safely: plan path, PRD/spec path, + phase scope, prior phase results, repo rules, validation commands, ownership + scope, dirty-worktree notes, and commit policy. +- Tell coding subagents they are not alone in the worktree, must not revert work + they did not make, and must adapt to existing or concurrent changes. +- If new information invalidates the plan, update the plan and downstream phase + items instead of silently following stale instructions. +- Keep the user updated at phase boundaries, before edits, during long + validation, and whenever a blocker or plan deviation appears. + +## Phase Topologies + +The default topology for a phase is one implementer, then validation, then one +reviewer. During orientation, pick a different topology when the phase's shape +calls for it: + +- **Batch migration** — one worker discovers the target items, parallel + implementers each own a disjoint batch, then aggregate validation and one + reviewer over the combined diff. For mechanical changes across many files. +- **Audit / sweep** — parallel read-only workers each inspect a slice, a + separate verifier confirms each finding against the code, and the parent + deduplicates and ranks before acting. For phases whose output is findings + rather than edits. +- **Fix-until-green** — run the failing check, dispatch a fix worker, re-run, + repeat. Stop when the check passes or two consecutive rounds make no + progress; then escalate to the user or update the plan instead of looping. +- **Competing drafts** — for a high-stakes design decision inside a phase, two + or three workers draft independently; the parent compares and adopts or + synthesizes one before implementation proceeds. + +Rules for every topology: parallel workers must have disjoint write scopes; +every loop needs an explicit stop condition (success, an attempt ceiling, or +no-progress detection); and results come back in the Worker Result Contract +shape so the parent can combine them without carrying transcripts. + +## Phase Loop + +Run this loop for each phase in dependency order. + +### 1. Orient The Phase + +- Re-read the phase section, acceptance criteria, and prior logs. +- Inspect git status and recent relevant commits. +- Choose the phase's topology (see Phase Topologies): the default single + implementer, or a fan-out/loop shape when the phase calls for one. +- Update the todo tracker before spawning workers. + +### 2. Implementation Worker + +Spawn a worker under the `phase-implementer` contract to implement only the +active phase. The worker edits files directly. The parent orchestrator owns +commits by default unless the user opted out or explicitly delegated commits +to a worker. + +After the worker returns: + +- Note its agent ID in the phase's todo/notes for possible resumption. +- Inspect its summary, changed paths, validation results, blockers, and risks. +- Inspect git status and a focused diff. +- If implementation is incomplete because assumptions changed, send a bounded + follow-up (resume the same worker by ID so it keeps its context) or update + the plan before continuing. + +### 3. Validation + +Run or delegate affected validation for the phase. Use the repo's documented +commands when available, and include tests, lint, typecheck, migrations, or +browser checks when relevant. + +If validation cannot run, record the exact command, blocker, and risk in the +phase notes or plan log. + +### 4. Review And Fix Worker + +Spawn a worker under the `phase-reviewer` contract after implementation and +initial validation. Note its agent ID alongside the phase. + +Build the review prompt from primary evidence first: the plan and acceptance +criteria, the actual diff or commit range, repo rules, and validation results. +Do not lead with the implementer's summary. Include implementer notes only as +supplemental context for the reviewer to consult after independently inspecting +the change. This avoids anchoring the review to what the implementer believed it +changed. + +The reviewer/fixer should: + +- Review the phase against the plan, PRD/spec, repo rules, security, tenancy/data + ownership, migrations, tests, and likely regressions. +- Patch concrete issues directly when bounded and low-risk. +- Leave review fixes uncommitted for the parent orchestrator to commit unless + the user opted out or explicitly delegated commits to the reviewer/fixer. +- Report no-op clearly if no changes are needed. +- Report larger design issues with the exact plan changes needed. + +### 5. Default Commit + +Commit each completed phase by default unless the user requested "no commits", +"implementation only", or another no-commit constraint. Prefer the parent +agent's normal commit workflow unless a dedicated shell subagent is clearly +useful. + +When committing: + +- Follow the host's git safety rules. +- Inspect git status, full staged/unstaged diff, and recent log first. +- Stage only files that belong to the active phase. +- Run repo-required pre-commit validation and affected tests. +- Fix validation failures only when the fix is clearly in phase scope. +- Create a focused commit, or report an explicit no-op if there are no phase + changes. -```text -contract phase - ├─ independent lane A - └─ independent lane B - ↓ join gate - ┌───────┼───────┐ -lane C lane D lane E - └───────┼───────┘ - final join -``` - -Update the plan document when orchestration changes are part of the user's request. - -## Prepare parallel writers - -Use the repository's documented isolation mechanism. For Git worktrees: - -1. Start from the intended feature base. -2. Create one `codex/` topic branch and worktree per concurrent writer. -3. Tell each agent its absolute worktree path and require every command to use it. -4. Keep shared barrels, manifests, lockfiles, generated indexes, docs, and version files - with the integration owner unless one lane explicitly owns them. -5. Integrate completed lane commits into one feature branch without rewriting pushed - history. -6. Prove intended commits are contained in the integration tip before cleanup. - -If writers operate in one checkout, allow only disjoint paths and tell agents that edits -are immediately visible to every worker. Stop the fan-out if overlapping edits appear. - -## Execute each phase - -### 1. Orient the phase - -- Re-read its criteria, prior results, current status, and owned paths. -- Confirm prerequisites and isolation. -- Mark the phase or fan-out orchestration step `in_progress`. - -### 2. Delegate bounded implementation - -Spawn workers only for concrete independent tasks. Include the plan path or relevant -excerpt, repository rules, acceptance criteria, worktree, ownership, validation, existing -changes, and commit policy. Do not assume workers infer parent-only context. - -Continue useful root work while agents run. Send concise commentary updates at least once -per minute during long operations. - -### 3. Inspect and validate - -For each worker result: - -- inspect its summary, status, diff, changed files, validation, deviations, and blockers; -- independently inspect the focused diff and repository status; -- run the smallest repository-documented checks that establish lane correctness; -- use `followup_task` for bounded corrections. - -Do not silently replace a blocked check with a weaker one. Record the command, blocker, -and risk. - -### 4. Join +### 6. Plan Finalization -At a join gate: - -1. Wait for every required lane. -2. Integrate all completed work into the feature tip. -3. Prove no intended lane commit or file remains outside it. -4. Resolve shared files once through the integration owner. -5. Run contract and cross-lane tests, then aggregate focused checks. -6. Freeze the next shared interface before another fan-out. - -Do not advance because each lane passes alone. The join gate proves composition. - -### 5. Review and fix - -After implementation and initial validation, spawn a fresh reviewer with the phase diff, -criteria, repository rules, and validation evidence. Ask it to patch bounded issues, avoid -commits unless authorized, and report a clear no-op when clean. Re-run affected checks. - -### 6. Finalize the phase +Update the plan or phase log for the active phase. Record: -- Done, Partial, or Blocked; -- behavior and changed areas; -- validation commands/results; -- review result; -- commit/change ids when authorized; -- deviations, downstream changes, risks, and manual checks. +- Phase status: Done, Partial, or Blocked. +- Implementation summary and changed behavior. +- Validation commands and results. +- Review outcome. +- Commit SHAs, if commits were created. +- Deviations from the original plan. +- Downstream changes, remaining risks, and manual checks not performed. + +Commit the plan/log update separately from implementation changes unless the +user opted out of commits. + +## Final Whole-Feature Pass + +After all requested phases are finalized: + +1. Run aggregate validation appropriate for the whole feature. +2. Spawn a worker under the `phase-final-reviewer` contract to inspect the + complete feature against the plan and PRD/spec. +3. If the final reviewer changed files, validate those fixes. +4. Commit final fixes or final plan/log updates unless the user opted out of + commits. +5. Give the user a concise final summary with phase status, validation, commit + SHAs if any, remaining manual gaps, and branch/worktree status. + +Give the final reviewer the plan, acceptance criteria, complete diff or commit +range, and aggregate validation before phase summaries. Phase summaries are +supplemental and should be read only after an independent pass over the primary +evidence. + +## Worktrees And Stacked PRs (Option For Complex Plans) + +For a plan with sequenced phases plus parallel tracks — especially when the +user's checkout is on their own branch, is behind the default branch, or +carries dirty user-owned work — run the orchestration in dedicated git +worktrees and land each phase as a PR in a stack, instead of committing to the +user's checkout. + +When to choose this mode: + +- The plan names foundations that later phases build on, so phases must land + as separate reviewable PRs in dependency order. +- Two or more tracks touch disjoint areas (for example API vs web) and can run + as concurrent implementation workers without colliding. +- The current checkout is not a safe base: behind origin, on a personal + branch, or dirty with user-owned edits. + +Setup: + +1. Choose worktree locations and branch names from the target repo's + contributor docs and the user's rules — conventions differ (some require a + specific in-repo directory, others forbid one). Only when no rule exists, + default to a sibling directory such as `../--work`. +2. Fetch and branch from `origin/`, not the local checkout: + `git worktree add origin/ --detach`. +3. Make the worktree runnable before spawning workers: copy gitignored env + files from the user's checkout, install dependencies, run the repo's + build-before-measure steps (built packages, generated clients). Workers + inherit a broken toolchain otherwise. +4. Create one additional worktree per concurrent track + (`git worktree add -b `) + so parallel workers never share a checkout. Point each worker at its own + worktree path in its prompt. +5. Remove temporary worktrees when done (`git worktree remove `), + and if the host can point its diff view at a worktree (Cursor's + `SetActiveBranch`), do so, so the IDE diff follows the work. + +Branching and stacking: + +- One branch per phase, cut from the previous phase's branch when the phase + depends on it: foundations first, then tracks stacked on the last foundation + they need. Parallel tracks branch from the same base, not from each other. +- Commit each phase on its branch (orchestrator owns commits), push with + `git push -u origin `, then open the PR with the `gh` CLI, setting + `--base` to the parent branch for stacked phases and to the default branch + for the stack root: + `gh pr create --title "type(scope): subject" --body "$(cat <<'EOF' ... EOF)" --base `. +- Record the PR number in the phase's todo item so the final summary can map + phases to PRs. +- A schema/migration phase ships as its own PR based on the default branch; + code that depends on it stacks on the migration branch (many repos require + this — check the repo's contributor docs). + +Keeping the stack healthy during the run: + +- Check CI on every open PR after pushes (`gh pr checks `); investigate + failures with `gh api .../actions/jobs//logs` before assuming a worker's + change caused them — a failure may predate the stack's base. +- If the default branch gains a fix the stack needs, merge it forward through + the stack in order (base branch first, then each child), using a temporary + worktree if the branches are checked out elsewhere. Never rebase or + force-push pushed branches. +- When an inner PR merges early, GitHub retargets its children automatically; + verify with `gh pr view --json baseRefName`. +- Follow the repo's stack-collapse rules before final review if it has them + (prove containment with `git merge-base --is-ancestor` before closing inner + PRs; the survivor merges, never closes). + +The final summary must report the stack shape: which PRs are open, their base +branches, merge order, CI state, and which worktrees were created or removed. + +## Prompt Templates + +Adapt these to the repo and phase. These templates are the per-invocation +context to hand each worker — the standing role rules (scope discipline, +no-commit default, response format) live in the companion skills, so the +prompt's job is the run-specific facts. If the worker runs as a named custom +agent built from the companion skill, the template alone is enough; if it runs +as a general subagent, prepend an instruction to load and follow the matching +companion skill, or paste that skill's standing rules above the template. +When resuming a prior worker by ID instead of dispatching fresh, send only +what changed since its last response; it retains the rest. + +### Worker Result Contract + +Every worker response must use these headings in this order: + +1. `Outcome` — concise result or explicit no-op. +2. `Changed files` — files the worker changed, not every file it inspected. +3. `Behavior or findings` — implemented behavior or review findings and fixes. +4. `Validation` — exact commands or checks and their results. +5. `Downstream impact` — plan changes, follow-up work, or `None`. +6. `Blockers and risks` — unresolved issues, skipped checks, manual checks, or + `None`. + +Keep `Changed files` proportional. List paths individually when the list is +short. When it would become a long, low-signal inventory, group paths by +module/directory, give counts, and name only high-signal or exceptional files. +Label a grouped list as a summary rather than exhaustive; the parent inspects +git status and the diff for the authoritative file list. + +### Implementation Worker (`phase-implementer`) -## Whole-feature pass +```text +You are implementing phase {phase_name} of this plan. -After requested phases complete: +Context: +- Plan: {plan_path_or_summary} +- PRD/spec: {prd_path_or_summary_or_none} +- Prior phase commits and notes: {prior_phase_summary} +- Repo instructions and validation requirements: {repo_rules_summary} +- Current dirty-worktree notes: {dirty_worktree_summary} -1. Integrate every lane into one feature tip or working tree. -2. Prove no worker output was omitted. -3. Run repository-appropriate aggregate validation. -4. Spawn a fresh final reviewer against the complete diff. -5. Validate final fixes. -6. Deliver only to the user's authorized stopping point. -7. Follow repository-specific PR, CI, readiness, merge, and deployment workflows. +Ownership: +- You own {owned_files_or_modules}. +- Other agents or the user may have changes in the worktree. Do not revert work + you did not make. Adapt to existing changes. -Respect partial stopping points. Do not implement or review future phases the user did not -request. +Task: +- Implement only phase {phase_name}. +- It is acceptable to deviate from the plan when the codebase shows a better + path, but document the reason and downstream impact. +- Commit policy: {commit_policy}. The parent orchestrator commits by default; + do not commit from this worker unless this explicitly delegates commit + authority to you. + +Validation: +- Run {affected_tests_or_checks} where practical. +- If a required check is not practical, explain why. + +Final response: +- Use the Worker Result Contract headings in order. +- In `Behavior or findings`, describe the behavior implemented. +``` -## Worker prompt +### Review And Fix Worker (`phase-reviewer`) ```text -Implement {phase_or_lane} in {absolute_worktree_path}. +Review and fix phase {phase_name}. Context: -- Plan: {plan_path_and_relevant_scope} -- Acceptance criteria: {criteria} -- Dependencies/prior results: {summary} -- Repository rules: {rules} -- Validation: {commands} -- Existing user-owned changes: {summary} - -Ownership: -- Own only {paths_or_modules}. -- Defer {shared_files} to the integration owner. -- Other agents may be working concurrently. Do not revert or overwrite their work. +- Plan: {plan_path_or_summary} +- PRD/spec: {prd_path_or_summary_or_none} +- Change under review: {commit_range_or_diff_scope} +- Validation evidence: {phase_validation_results} +- Repo rules: {repo_rules_summary} +- Commit policy: {commit_policy} +- Supplemental implementer notes: {phase_result} Task: -- Implement only this lane. -- Report evidence that invalidates the plan and its downstream impact. -- Commit policy: {policy}. Do not commit unless explicitly delegated. - -Return: -- Behavior and changed files. -- Validation and exact results. -- Deviations, blockers, risks, and integration notes. +- First inspect the plan, acceptance criteria, and actual change. Form an + independent assessment before reading the supplemental implementer notes. +- Review the phase against acceptance criteria, repo conventions, security, + tenancy/data ownership, migrations, and test coverage. +- Patch concrete issues directly when bounded and low-risk. +- Do not commit from this worker unless the commit policy explicitly delegates + commit authority to you. +- If no changes are needed, say so clearly. +- If the plan should change, describe the exact plan and downstream updates. + +Final response: +- Use the Worker Result Contract headings in order. +- In `Behavior or findings`, report findings fixed, the no-op result, and any + findings not fixed. ``` -## Review prompt +### Final Reviewer (`phase-final-reviewer`) ```text -Review and fix {scope} in {absolute_worktree_path}. +Review the entire feature after all requested phases. Context: -- Plan/criteria: {context} -- Diff scope: {diff} -- Repository rules: {rules} -- Validation so far: {results} -- Commit policy: {policy} - -Review correctness, criteria, repository conventions, security, data ownership, -migrations, tests, and integration boundaries. Patch concrete bounded issues. Do not -commit unless delegated. Report fixes or a clear no-op, validation, and residual risks. +- Plan: {plan_path} +- PRD/spec: {prd_path_or_none} +- Complete change: {commit_range_or_diff_scope} +- Final validation results so far: {validation_summary} +- Supplemental phase results: {all_phase_results} + +Task: +- First inspect the plan, acceptance criteria, and complete change. Form an + independent assessment before reading the supplemental phase results. +- Review end-to-end behavior against the plan and PRD/spec. +- Look for integration bugs, missing acceptance criteria, stale plan state, + validation gaps, unsafe data ownership, and regressions across phase + boundaries. +- Patch only concrete issues that are safe to fix now. +- Do not commit from this worker unless the commit policy explicitly delegates + commit authority to you. + +Final response: +- Use the Worker Result Contract headings in order. +- In `Behavior or findings`, report findings fixed, the no-op result, and any + findings not fixed. ``` -## Completion standard +## Plan Conventions + +Prefer a stable plan structure: + +- Phase status: Not started, In progress, Done, Partial, or Blocked. +- Implementation log entries with date, phase, summary, validation, review + result, commits if any, deviations, and remaining risks. +- Downstream changes called out where the original phase plan changed. +- Manual checks listed separately from automated checks. + +Do not let the plan become ceremonial. If implementation or review shows that a +task is obsolete, split, merged, or better solved differently, update the plan +and explain why. -Complete the run only when: +## Git And Validation Rules -- every requested phase has a terminal status; -- every intended worker result is integrated; -- join gates and aggregate checks have recorded results; -- review fixes are validated; -- no unauthorized external writes occurred; -- the final report states exact repository, branch/worktree, validation, and remaining - risk. +- Follow repo contributor instructions before every commit. +- Use non-interactive git commands. +- Stage intentionally and avoid unrelated dirty files. +- Never use destructive git commands unless the user explicitly requested them. +- Keep implementation, review fixes, plan finalization, and final feature fixes + distinct when committing. +- For multi-phase plans that should land as reviewable PRs rather than commits + on the user's checkout, use the worktree + stacked-PR mode above. +- If required validation cannot run, record the command, blocker, and risk in + both the subagent result and the plan log. diff --git a/.agents/skills/phase-orchestrator/UPSTREAM.md b/.agents/skills/phase-orchestrator/UPSTREAM.md new file mode 100644 index 0000000..7127a1e --- /dev/null +++ b/.agents/skills/phase-orchestrator/UPSTREAM.md @@ -0,0 +1,5 @@ +# Upstream + +This five-skill pack is adapted from [`kousun12/code-orchestrator`](https://github.com/kousun12/code-orchestrator) at commit `989e49ba7b0d8cb922010272abe6748dd68a4adb`. + +Local `AGENTS.md` files and `agents/openai.yaml` metadata integrate the upstream skills with this repository's agent conventions. The `SKILL.md` workflows retain the upstream behavior. diff --git a/.agents/skills/phase-orchestrator/agents/openai.yaml b/.agents/skills/phase-orchestrator/agents/openai.yaml index a19591f..51f00fe 100644 --- a/.agents/skills/phase-orchestrator/agents/openai.yaml +++ b/.agents/skills/phase-orchestrator/agents/openai.yaml @@ -1,4 +1,4 @@ interface: display_name: "Phase Orchestrator" - short_description: "Run phased plans with parallel agent lanes" - default_prompt: "Use $phase-orchestrator to execute this phased implementation plan safely." + short_description: "Execute plans with delegated phase workers" + default_prompt: "Use $phase-orchestrator to execute this phased implementation plan with independent implementation and review." diff --git a/.agents/skills/phase-reviewer/AGENTS.md b/.agents/skills/phase-reviewer/AGENTS.md new file mode 100644 index 0000000..bc7183f --- /dev/null +++ b/.agents/skills/phase-reviewer/AGENTS.md @@ -0,0 +1,11 @@ +# Contents + +- `SKILL.md` – independent review-and-fix contract for one implemented phase. +- `agents/` – Codex UI metadata for discovering and invoking the skill. + +# Guidelines + +- Keep this role independent from the phase implementer and bounded to the assigned phase. +- Preserve the fixed result contract, evidence requirements, and default prohibition on commits. +- Patch only concrete low-risk findings inside the delegated scope; return broader findings to the parent orchestrator. +- Update `agents/openai.yaml` when the skill name, trigger, or default invocation changes. diff --git a/.agents/skills/phase-reviewer/SKILL.md b/.agents/skills/phase-reviewer/SKILL.md new file mode 100644 index 0000000..bb3867c --- /dev/null +++ b/.agents/skills/phase-reviewer/SKILL.md @@ -0,0 +1,65 @@ +--- +name: phase-reviewer +description: >- + Reviews and fixes a just-implemented phase of a multi-phase plan during a + phase-orchestrator run. Use after a phase's implementation and initial + validation: checks the phase against the plan, PRD/spec, repo conventions, + security, tenancy/data ownership, migrations, and test coverage, and patches + bounded low-risk issues directly. Never commits unless commit authority is + explicitly delegated. Also usable as the definition of a named custom agent + on hosts that support them. +license: MIT +metadata: + internal: true +--- + +# Phase Reviewer + +You are the review-and-fix worker for one completed phase of a larger plan. +The parent orchestrator hands you the plan and acceptance criteria, the actual +diff or commit range, validation evidence, any PRD/spec, repo rules, and the +commit policy. It may also provide implementer notes as supplemental context. + +Inspect the plan, acceptance criteria, and actual change first. Form an +independent assessment before reading supplemental implementer notes. Treat +those notes as claims to check, not as the scope or conclusion of the review. + +## Review Scope + +Review the phase against: + +- The phase's acceptance criteria in the plan and PRD/spec. +- Repo conventions and contributor instructions for the touched areas. +- Security, tenancy/data ownership, and migration safety. +- Test coverage: does the change carry the tests the repo's standards require? +- Likely regressions in adjacent code the phase touched. + +## Rules + +1. Patch concrete issues directly when they are bounded and low-risk. Re-run + the affected validation on anything you change. +2. Leave your fixes uncommitted for the parent to commit. Only commit if the + prompt explicitly delegates commit authority to you. +3. If no changes are needed, report a clear no-op — do not invent findings. +4. If you find a design-level problem too large to patch safely, do not + half-fix it: describe the exact plan changes needed and stop. +5. Never revert work you did not make. + +## Final Response Format + +Use these exact final-response headings in order: + +1. `Outcome` — concise result or explicit no-op. +2. `Changed files` — files you changed while fixing findings, not every file + reviewed. +3. `Behavior or findings` — findings fixed and any findings not fixed. +4. `Validation` — exact commands or checks and their results. +5. `Downstream impact` — plan changes, follow-up work, or `None`. +6. `Blockers and risks` — unresolved issues, skipped checks, manual checks, or + `None`. + +Keep `Changed files` proportional. List paths individually when concise. For a +long, low-signal list, group paths by module/directory, give counts, name only +high-signal or exceptional files, and label the list as a non-exhaustive +summary. The parent will inspect git status and the diff for the authoritative +list. diff --git a/.agents/skills/phase-reviewer/agents/openai.yaml b/.agents/skills/phase-reviewer/agents/openai.yaml new file mode 100644 index 0000000..27fe7d8 --- /dev/null +++ b/.agents/skills/phase-reviewer/agents/openai.yaml @@ -0,0 +1,4 @@ +interface: + display_name: "Phase Reviewer" + short_description: "Review and fix one implemented phase" + default_prompt: "Use $phase-reviewer to independently review the assigned phase and fix bounded low-risk findings." diff --git a/.agents/skills/write-phase-plan/AGENTS.md b/.agents/skills/write-phase-plan/AGENTS.md new file mode 100644 index 0000000..0ccc06b --- /dev/null +++ b/.agents/skills/write-phase-plan/AGENTS.md @@ -0,0 +1,11 @@ +# Contents + +- `SKILL.md` – plan-authoring workflow for dependency-ordered phased execution. +- `agents/` – Codex UI metadata for discovering and invoking the skill. + +# Guidelines + +- Keep the plan format aligned with the companion `phase-orchestrator` contract. +- Require explicit scope, acceptance criteria, validation commands, dependencies, and status conventions for every phase. +- Keep examples portable and defer repository-specific commands and delivery policy to the target repository. +- Update `agents/openai.yaml` when the skill name, trigger, or default invocation changes. diff --git a/.agents/skills/write-phase-plan/SKILL.md b/.agents/skills/write-phase-plan/SKILL.md new file mode 100644 index 0000000..a73fe65 --- /dev/null +++ b/.agents/skills/write-phase-plan/SKILL.md @@ -0,0 +1,121 @@ +--- +name: write-phase-plan +description: >- + Writes or restructures an implementation plan in the format the + phase-orchestrator skill consumes: dependency-ordered phases with explicit + scope, acceptance criteria, validation commands, and status/log conventions. + Use when the user asks to write a plan for phase orchestration, prepare a + plan or PRD for delegated multi-agent implementation, or convert a spec, + checklist, or design doc into implementable phases. +license: MIT +metadata: + internal: true +--- + +# Write Phase Plan + +## Goal + +Produce a plan document that a phase-orchestrator run can execute without +re-deriving structure. Each phase must be implementable by a worker that has +no chat history: the phase section is the worker's entire brief, plus repo +rules and the code itself. + +The plan is the source of truth during the run. The orchestrator updates phase +status and appends log entries as it goes, so the document must be written to +absorb that. + +## Where The Plan Lives + +Follow the repo's convention for design docs (for example `plans//` in +repos that define one). One markdown file per plan. Link out to the PRD/spec +rather than duplicating it. + +## Document Structure + +```markdown +# + +## Overview +One or two paragraphs: what is being built and why. Link the PRD/spec. + +## Constraints +Repo-wide facts every phase needs: commit/PR policy, validation commands, +branch or worktree requirements, anything the orchestrator must not infer. + +## Phases +A short table or list: phase ID, name, depends-on, parallelizable-with. + +## Phase 1: +- **Status:** Not started +- **Depends on:** none | Phase N +- **Objective:** one sentence, the outcome not the activity. +- **Scope:** the files/modules this phase owns (its write scope). +- **Out of scope:** adjacent work this phase must not touch. +- **Approach:** implementation notes — key decisions already made, pointers + to the code the worker should read first, known landmines. +- **Acceptance criteria:** checkable statements (see below). +- **Validation:** exact commands to run, plus any manual checks. + +## Phase 2: +... + +## Implementation log +(Empty at authoring time. The orchestrator appends one entry per phase: +date, phase, summary, validation results, review outcome, commit SHAs, +deviations, remaining risks.) +``` + +## Sizing And Ordering Phases + +- One phase = one implementer worker session. If a phase's Approach section + needs subheadings to stay coherent, split it. +- Order by dependency, foundations first. A schema/migration phase is always + its own phase (and in many repos its own PR — record that in Constraints). +- Phases that can run in parallel must have disjoint write scopes. Declare + parallelizability explicitly in the phase list; the orchestrator will not + guess. +- If a phase exists only to set up a later phase, say which one, so the + orchestrator knows a deviation there propagates. + +## Writing For A Context-Free Worker + +The implementer sees the plan, the repo, and nothing else. So: + +- Use standalone spec language. No "as discussed", "still", "instead of the + old approach", or references to conversations that produced the plan. +- Name concrete things: file paths, function names, commands — not "the + relevant helper" or "the usual checks". +- State decisions as decisions. If something is genuinely unresolved, mark it + as an explicit open question and say who resolves it (the worker may decide + in-scope questions; the orchestrator escalates cross-cutting ones). +- Put shared context in Constraints once rather than repeating it per phase. + +## Acceptance Criteria + +Each criterion must be checkable by the reviewer from the diff and the running +code, without asking the author: + +- Good: "`POST /orgs/:id/invites` returns 403 for a non-admin member; covered + by a route test." +- Bad: "Invites are properly secured." + +Include the negative space: what must not change (existing behavior, public +contracts, performance characteristics) when regression there is a real risk. + +## Status And Log Conventions + +- Phase status vocabulary: Not started, In progress, Done, Partial, Blocked. +- The orchestrator owns status transitions and log entries during the run; + the author sets everything to Not started. +- Keep the Implementation log section present even when empty, so run updates + have a stable place to land. + +## Anti-Patterns + +- Phases split by activity (design/build/test) instead of by deliverable — + every phase should end with validated, committable work. +- Two phases that edit the same files marked as parallel. +- Acceptance criteria that restate the objective instead of testing it. +- A plan that embeds the whole PRD — link it and keep the plan operational. +- Hidden sequencing: prose that implies an order the phase list doesn't state. diff --git a/.agents/skills/write-phase-plan/agents/openai.yaml b/.agents/skills/write-phase-plan/agents/openai.yaml new file mode 100644 index 0000000..6a4a061 --- /dev/null +++ b/.agents/skills/write-phase-plan/agents/openai.yaml @@ -0,0 +1,4 @@ +interface: + display_name: "Write Phase Plan" + short_description: "Turn a spec into executable phases" + default_prompt: "Use $write-phase-plan to turn this request into a dependency-ordered implementation plan."