diff --git a/.agents/skills/AGENTS.md b/.agents/skills/AGENTS.md new file mode 100644 index 0000000..83e6cf5 --- /dev/null +++ b/.agents/skills/AGENTS.md @@ -0,0 +1,15 @@ +# Contents + +- `write-phase-plan/` – dependency-ordered plan authoring with explicit scope, acceptance criteria, validation, and status. +- `phase-orchestrator/` – parent workflow for delegated phased execution, integration, and delivery. +- `phase-implementer/` – bounded implementation worker for one assigned phase. +- `phase-reviewer/` – independent review-and-fix worker for one completed phase. +- `phase-final-reviewer/` – end-to-end reviewer for the completed multi-phase feature. + +# Guidelines + +- Keep the five skills installed and reviewed as one interoperable pack. +- Keep every skill self-contained with `SKILL.md`, its closest `AGENTS.md`, matching `agents/openai.yaml`, and only the resources it needs. +- Preserve the pinned upstream provenance and MIT license under `phase-orchestrator/`. +- Keep trigger descriptions portable and defer repository commands, validation, version control, and delivery policy to the repository's own guides. +- Keep product-specific operating skills outside this reusable baseline. 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..1d75e04 --- /dev/null +++ b/.agents/skills/phase-final-reviewer/SKILL.md @@ -0,0 +1,66 @@ +--- +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 +--- + +# 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..857b836 --- /dev/null +++ b/.agents/skills/phase-implementer/SKILL.md @@ -0,0 +1,57 @@ +--- +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 +--- + +# 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 new file mode 100644 index 0000000..b14abb0 --- /dev/null +++ b/.agents/skills/phase-orchestrator/AGENTS.md @@ -0,0 +1,12 @@ +# Contents + +- `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 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 new file mode 100644 index 0000000..85a71a8 --- /dev/null +++ b/.agents/skills/phase-orchestrator/SKILL.md @@ -0,0 +1,495 @@ +--- +name: phase-orchestrator +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 +--- + +# Phase Orchestrator + +## 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. + +### 6. Plan Finalization + +Update the plan or phase log for the active phase. + +Record: + +- 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`) + +```text +You are implementing phase {phase_name} of this plan. + +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} + +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. + +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. +``` + +### Review And Fix Worker (`phase-reviewer`) + +```text +Review and fix phase {phase_name}. + +Context: +- 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: +- 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. +``` + +### Final Reviewer (`phase-final-reviewer`) + +```text +Review the entire feature after all requested phases. + +Context: +- 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. +``` + +## 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. + +## Git And Validation Rules + +- 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 new file mode 100644 index 0000000..51f00fe --- /dev/null +++ b/.agents/skills/phase-orchestrator/agents/openai.yaml @@ -0,0 +1,4 @@ +interface: + display_name: "Phase Orchestrator" + 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..6576c60 --- /dev/null +++ b/.agents/skills/phase-reviewer/SKILL.md @@ -0,0 +1,63 @@ +--- +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 +--- + +# 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..9cfcbf7 --- /dev/null +++ b/.agents/skills/write-phase-plan/SKILL.md @@ -0,0 +1,119 @@ +--- +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 +--- + +# 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." diff --git a/AGENTS.md b/AGENTS.md index 31904cf..1c66e54 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -5,6 +5,7 @@ - `spec/` – versioned human and machine-readable ontology, wire, storage, sync, embedding, and migration contracts. - `skills/oh/` – installable Agent Skill for operating Oh from a coding-agent workflow. - `site/` – the public Next.js website for `https://oh.computer`, deployed from the existing Hraness Vercel project. +- `.agents/skills/` – portable plan authoring, phased execution, implementation, and independent review workflows. - `.github/` – public contribution templates, read-only branch validation, dependency updates, and post-publication release verification. - `README.md`, `CONTRIBUTING.md`, `SECURITY.md`, and `LICENSE` – public usage, project policy, threat model, and terms. - `package.json`, `tsconfig.json`, and `bun.lock` – package identity, exported surfaces, and frozen Bun toolchain.