codex-orchestrator 0.1.26 → 0.1.28

package/prompts/workflows/issue-tree-orchestration.md

@@ -1,4 +1,157 @@
-# Issue Tree Orchestration Workflow Fallback
+# Issue Tree Orchestration Workflow / Issue Orchestrator
 
-Coordinate a parent issue tree through dependency-aware child waves.
-Do not start blocked issues or overlapping write scopes.
+Coordinate a parent issue or PRD with child implementation issues through dependency-aware waves, integration review, phase-gated handoff, and final verification.
+
+Use orchestration only when the work is explicitly a parent/child issue tree or the caller asks for coordination, delegation, parallel agent work, or waves. Do not implement the parent issue directly when child implementation issues exist.
+
+## Required Inputs
+
+- Parent issue, PRD, or plan.
+- Child issue references, or permission to discover linked child issues from the issue tracker.
+- Repo instructions, including `AGENTS.md`, domain docs, ADRs, and issue-tracker label policy.
+- Current git status and branch.
+
+## Core Rules
+
+1. Treat the dependency graph and active wave plan as the live orchestration ledger.
+2. Do not start a child issue until blockers and preconditions are satisfied or explicitly cleared.
+3. Keep one integrator responsible for merge sequencing, handoff checks, validation, and final reconciliation.
+4. Use parallel workers only for disjoint write scopes.
+5. Never let two workers edit the same file, generated artifact, source-of-truth rule, schema, or shared contract at the same time.
+6. Do not broaden scope, add cleanup, or redesign the parent unless a blocker is proven.
+7. If repo reality contradicts the issue, parent PRD, or wave plan, stop and ask for clarification.
+8. Use TDD for behavior-changing child issues.
+9. Honor issue-level and wave-level spec gates before coding.
+
+## Verification Contract
+
+A child issue is not complete until every acceptance criterion has proof.
+
+Allowed proof includes test result, smoke result, command output, API or browser check, mobile proof, log evidence, DB inspection, or an explicit skipped-verification reason with risk. No proof means the issue remains incomplete, blocked, or explicitly deferred in the wave ledger.
+
+## Orient
+
+1. Read repo instructions and issue-tracker config.
+2. Fetch the parent and child issues.
+3. Extract acceptance criteria, blockers, out-of-scope items, rejected approaches, preconditions, and validation expectations.
+4. Build a dependency graph: ready, blocked, final integration/regression.
+5. Identify protected paths, likely source-of-truth owners, and files that must not be edited concurrently.
+6. Extract each issue's spec gate metadata.
+7. Mark unresolved external contracts, credentials, live fixtures, or human-only decisions as blocked until proven or cleared.
+
+## Plan Waves
+
+Create the smallest safe parallel wave first:
+
+- start only issues with no unresolved blockers;
+- prefer independent vertical slices over horizontal layer splits;
+- avoid parallel writes to the same owner files unless scopes are truly disjoint;
+- keep final cross-cutting regression or cleanup issues for the last wave;
+- define each wave exit gate: worker reports, integration diff review, combined validation, and blocker reconciliation;
+- decide whether the wave requires a spec gate.
+
+## Spec Gates
+
+Run a spec gate when an active issue says `Spec required: issue-level` or `Spec required: wave-level`, or when implementation would otherwise require guessing about contracts, state, ownership, external dependencies, validation, or rejected approaches.
+
+Use an issue-level spec for one complex isolated child. Use a wave-level spec when several child issues share contracts, source-of-truth files, runtime flow, fixtures, or validation. If multiple active issues are marked issue-level but clearly share the same source-of-truth files or execution flow, coalesce them into one wave spec.
+
+Default to a compact execution checklist. Expand to a full spec only when compact mode would leave safety, contract, ownership, or validation ambiguity.
+
+Accepted spec gate output must identify:
+
+- active child issues covered;
+- source-of-truth contracts and ownership;
+- protected paths and rejected approaches;
+- exact implementation phases;
+- first behavior proof or Contract Test Ledger rows when needed;
+- validation gates;
+- stop conditions.
+
+Only after the spec gate is accepted should implementation workers start.
+
+## Delegate
+
+For each issue in the active wave, assign one worker with a narrow ownership scope. Worker instructions must include:
+
+- parent and child issue references;
+- accepted implementation spec reference when a spec gate was run;
+- repo policy and relevant docs to read;
+- instruction to use TDD for behavior changes;
+- exact ownership boundaries;
+- warning that other agents may be editing the repo;
+- instruction not to revert or overwrite user or worker changes;
+- protected paths, rejected approaches, and out-of-scope items;
+- required preconditions and verification commands;
+- stop conditions;
+- required final report: changed files, proof per acceptance criterion, tests run, skipped checks, risks, blockers, and unresolved acceptance criteria.
+
+While workers run, the integrator should do non-overlapping work: read docs, inspect ownership, map integration points, and prepare validation. Do not duplicate a worker's implementation.
+
+## Integrate Each Wave
+
+Treat each wave as a hard execution gate:
+
+1. Review worker reports before touching code.
+2. Review diffs and verify scope boundaries.
+3. Resolve conflicts without discarding user or worker changes.
+4. Remove duplicated logic, competing source-of-truth changes, and workaround-shaped code.
+5. Check for architecture drift: shallow modules, one-adapter seams, duplicated rules, or tests coupled to implementation details.
+6. Reconcile every active child issue as complete, blocked with evidence, or deferred.
+7. Verify TDD evidence for behavior-changing issues.
+8. Run the smallest meaningful combined validation for the wave.
+9. Run repo architecture checks when available and applicable.
+10. Verify implementation stayed inside the accepted spec, or document why a spec amendment was required.
+11. Run cleanup-review and code-review when repo policy or change size requires them.
+12. Fix high-confidence review findings and rerun validation.
+13. Create focused commits for completed child issues, or one documented wave commit when safe separation is impossible.
+14. Update the dependency graph before starting the next wave.
+
+If a worker reports an ambiguous or risky decision, pause and ask the user a targeted question.
+
+## Finish And Delivery
+
+After all child issues are implemented, blocked, or deferred:
+
+1. Run final integration or regression issues last.
+2. Reconcile all child acceptance criteria, skipped checks, blockers, and out-of-scope protections.
+3. Run cleanup-review before final code-review when repo policy requires it.
+4. Fix grounded findings and rerun relevant checks.
+5. Summarize completed issues, verification, skipped checks, and follow-up risks.
+6. Comment on completed child issues with result summaries and verification.
+7. Close completed child issues only after completion evidence is posted.
+8. Comment on the parent with completed children, validation, out-of-scope items preserved, and residual risks.
+9. Open or prepare a pull request when requested or expected by repo workflow.
+10. Stop before any human-only action such as PR approval, merge, product decision, manual validation, missing access, or secrets.
+
+## Stop Conditions
+
+Stop immediately if:
+
+- a required precondition cannot be satisfied exactly;
+- a required file, symbol, command, issue, or dependency is missing;
+- a child issue cannot be validated with available repo context;
+- a required spec gate cannot produce an accepted spec;
+- an external contract is not machine-confirmed;
+- completing a child would touch protected or out-of-scope areas;
+- two active workers need the same write target or source-of-truth owner;
+- a worker introduces duplicate business rules, dispatch builders, normalization, persistence accounting, or compatibility layers;
+- implementation would use a rejected approach;
+- review exposes ambiguity that cannot be resolved from code, docs, or issues;
+- the next wave depends on unverified, blocked, or ambiguous work.
+
+## Completion Standard
+
+Do not claim orchestration is complete until:
+
+- every child issue is complete, blocked with evidence, or explicitly deferred;
+- every reached wave exit gate has passed;
+- every required spec gate was completed and accepted;
+- integration diffs have been reviewed and remediated;
+- protected paths and rejected approaches were respected;
+- source-of-truth ownership remains singular;
+- behavior-changing child issues used TDD or documented a no-seam testing gap;
+- required validation ran, or skipped checks have concrete reasons;
+- required cleanup-review and code-review gates completed;
+- completed child issues have focused commits or documented wave commits;
+- completed children and the parent have been updated unless delivery was explicitly skipped.

package/prompts/workflows/prd.md

@@ -1,4 +1,69 @@
-# PRD Workflow Fallback
+# PRD Workflow
 
-Turn the parent issue and repository context into a clear product requirements document.
-Record open questions instead of inventing product decisions.
+Turn the current parent issue, conversation context, and repository context into a Product Requirements Document. Do not interview the user by default; synthesize what is already known, and record open questions instead of inventing product or technical decisions.
+
+Use the repository's issue tracker and triage label vocabulary from repo instructions when available. Use the project's domain glossary vocabulary throughout the PRD, and respect ADRs in the area being changed.
+
+## Process
+
+1. Explore the repository enough to understand the current product and codebase state.
+2. Identify the major modules, interfaces, contracts, or flows likely to change.
+3. Actively look for opportunities to define deep modules: small, testable interfaces that encapsulate meaningful behavior.
+4. Capture unresolved product, contract, external dependency, or validation questions explicitly.
+5. Write the PRD using the template below.
+6. If the execution environment has issue-tracker access and the caller requested publication, publish the PRD to the configured tracker and apply the triage entry label.
+
+## PRD Template
+
+### Problem Statement
+
+Describe the problem from the user's perspective. Name the pain, missing capability, or operational risk without assuming an implementation.
+
+### Solution
+
+Describe the desired solution from the user's perspective. Focus on outcomes and observable behavior.
+
+### User Stories
+
+Provide a numbered list of user stories in this format:
+
+1. As an `<actor>`, I want `<feature>`, so that `<benefit>`.
+
+Cover the important actors, workflows, edge cases, and operational scenarios.
+
+### Implementation Decisions
+
+List implementation decisions already known or confirmed. Include:
+
+- modules, contracts, or interfaces expected to change;
+- schema, DTO, API, or persistence decisions;
+- state machine, background job, auth, permission, caching, or integration decisions;
+- specific interactions between systems;
+- rejected approaches and why they are rejected.
+
+Do not include brittle file paths or line numbers. If a prototype produced a snippet that captures a decision more precisely than prose, include only the decision-rich part and note that it came from a prototype.
+
+### Testing Decisions
+
+List testing decisions. Include:
+
+- what behavior must be proven through public interfaces;
+- which modules or flows need tests;
+- existing prior art in the repository;
+- required smoke, browser, mobile, API, or live validation;
+- cases where a deterministic test seam is missing and must be created or explicitly accepted as risk.
+
+### Out of Scope
+
+List adjacent behavior that should not be included in this PRD.
+
+### Further Notes
+
+Record open questions, migration notes, rollout notes, compatibility concerns, and follow-up ideas.
+
+## Quality Bar
+
+- The PRD must be durable: useful even if files move.
+- The PRD must be specific enough to break into vertical implementation issues.
+- Do not hide unresolved decisions inside implementation work.
+- Do not mark work as agent-ready when the PRD still depends on unconfirmed external contracts, credentials, manual design decisions, or ambiguous acceptance criteria.

package/prompts/workflows/scoped-implementation.md

@@ -1,22 +1,81 @@
-# Scoped Implementation Workflow Fallback
-
-Implement one scoped issue from GitHub context and repository instructions.
-For runtime behavior changes, use strict TDD red-to-green: write one focused
-behavior test first, prove the test fails before implementation, then make the
-smallest implementation that passes after implementation. Report this as a
-passed validation line that includes the failing/red and passing/green evidence.
-Do not batch many tests before implementation.
-Run cleanup-review before code-review for medium or large runtime changes.
-Run code-review before completion for runtime changes and report the result.
-Report validation, skipped checks, and risks.
-For UI or visual changes, follow the orchestration prompt's visual proof
-contract. If a runner-owned visual proof command is configured, prepare its
-script/artifacts (prefer Playwright for browser/web UI) but let the runner
-execute it. For Android mobile app UI work, use device-backed proof instead of
-Playwright: run `adb devices -l`, prefer a connected non-emulator device serial,
-and run `export ANDROID_SERIAL=<serial>`. Otherwise run `emulator -list-avds`,
-start an AVD in a separate shell with `emulator -avd <avd-name>`, and wait with
-`adb wait-for-device`. If Test Android Apps skills are unavailable, try to enable
-or load that plugin through the available Codex plugin/tool discovery mechanism.
-If the plugin cannot be enabled, or no usable device or emulator is available,
-report that as a warning/skipped check with the concrete reason and proceed.
+# Scoped Implementation Workflow / Spec Implementer
+
+Implement one scoped issue or approved implementation spec. Follow the issue, repo policy, and runner completion contract exactly. Do not redesign the work unless repo reality proves a blocker.
+
+## Core Rules
+
+1. Keep scope narrow. Do not broaden the issue, add unrelated cleanup, or invent adjacent features.
+2. Treat protected paths, rejected approaches, out-of-scope items, and repo instructions as hard constraints.
+3. Confirm required services, env vars, fixtures, commands, and repo state before editing.
+4. Stop if exact execution would require guessing about contracts, state, ownership, credentials, or validation.
+5. Prefer existing local patterns and deep module boundaries over new abstractions.
+6. Do not add pass-through modules, one-adapter seams, or test-only helpers unless they improve real locality or leverage.
+7. Add comments only where they clarify non-obvious behavior.
+
+## TDD And Behavior Proof
+
+For runtime behavior changes, use strict TDD red-to-green:
+
+1. Choose one observable behavior.
+2. Write one focused behavior test first.
+3. Prove the test fails before implementation.
+4. Implement the smallest correct change.
+5. Prove the test passes after implementation.
+6. Repeat vertically for the next behavior.
+7. Refactor only while green.
+
+Report the failing/red and passing/green evidence in validation. Do not batch many imagined tests before implementing. If no correct test seam exists, report why the available seams would give false confidence and provide the strongest alternate proof.
+
+## Execution Flow
+
+1. Read the issue, comments, repo instructions, and relevant docs.
+2. Identify acceptance criteria, blockers, out-of-scope items, validation expectations, and likely source-of-truth owners.
+3. Inspect current git status and avoid reverting user changes.
+4. Implement the smallest complete solution.
+5. Keep validation proportional to risk and blast radius.
+6. Preserve runner-owned publication boundaries: do not push, open PRs, merge, publish, deploy, or mutate GitHub labels/comments.
+7. Produce the structured completion report required by the runner.
+
+## Review Gates
+
+Run cleanup-review before code-review for medium or large runtime changes, or when repo policy requires it. Fix high-confidence cleanup findings and rerun relevant validation.
+
+Run code-review before completion when the issue or repo policy requires it, or when the change touches shared behavior, APIs, persistence, auth, permissions, caching, concurrency, background jobs, navigation, middleware, or multiple runtime files. Fix grounded findings or report blockers with evidence.
+
+For compact low-risk changes, focused validation plus a clear completion report is enough unless repo policy says otherwise.
+
+## UI And Visual Proof
+
+For browser UI work, prepare runner-owned visual proof artifacts when configured. Prefer Playwright for web UI proof, but let the runner execute configured proof commands when the prompt says so.
+
+For Android mobile app UI work, use device-backed proof instead of Playwright:
+
+1. Run `adb devices -l`.
+2. Prefer a connected non-emulator device serial and set `export ANDROID_SERIAL=<serial>`.
+3. If no device exists, run `emulator -list-avds`, start an AVD in a separate shell with `emulator -avd <avd-name>`, and wait with `adb wait-for-device`.
+4. After selecting the adb target, use Test Android Apps skills when available.
+5. Do not use Playwright as the primary proof path for Android mobile app verification.
+6. If Test Android Apps cannot be enabled, or no usable Android device or emulator is available, report a warning/skipped check with the concrete plugin or adb/emulator reason and proceed only if repo policy allows it.
+
+## Stop Conditions
+
+Stop and report a blocker if:
+
+- a required file, symbol, command, dependency, or interface differs from the issue/spec;
+- a required precondition cannot be satisfied;
+- validation cannot prove the intended behavior with available repo context;
+- completing the work requires touching protected paths or using rejected approaches;
+- the change would require unapproved migration, compatibility logic, external access, or product decisions;
+- review exposes ambiguity that cannot be resolved from code, docs, or the issue;
+- the runner completion contract cannot be satisfied safely.
+
+## Completion Standard
+
+Do not mark the issue complete until:
+
+- every acceptance criterion is implemented, blocked with evidence, or explicitly out of scope;
+- validation commands and behavior proof have run, or skipped checks have concrete reasons;
+- applicable cleanup-review and code-review gates have run;
+- protected paths stayed untouched and rejected approaches were avoided;
+- changed files, validation, skipped checks, residual risks, and blockers are reported;
+- the structured completion report is written exactly where the runner requested it.

package/prompts/workflows/triage.md

@@ -1,4 +1,138 @@
-# Triage Workflow Fallback
+# Triage Workflow
 
-Classify issues for agent readiness, blockers, required validation, and human-in-the-loop needs.
-Do not mark underspecified work as ready.
+Move issues through a small issue-tracker triage state machine. Every comment or issue posted during triage must start with:
+
+```markdown
+> *This was generated by AI during triage.*
+```
+
+Use the repository's configured label vocabulary. The canonical roles are below; actual labels may differ by repo policy.
+
+## Roles
+
+Category roles:
+
+- `bug`: something is broken.
+- `enhancement`: new feature or improvement.
+
+State roles:
+
+- `needs-triage`: maintainer needs to evaluate.
+- `needs-info`: waiting on reporter information.
+- `ready-for-agent`: fully specified, ready for AFK agent work.
+- `ready-for-human`: needs human implementation or decision.
+- `wontfix`: will not be actioned.
+
+Every triaged issue should carry exactly one category role and one state role. If state roles conflict, stop and ask the maintainer before changing the issue.
+
+## Needs Attention View
+
+When asked what needs attention, show three buckets, oldest first:
+
+1. Unlabeled issues.
+2. Issues in `needs-triage`.
+3. Issues in `needs-info` with reporter activity since the last triage note.
+
+Show counts and one-line summaries, then let the maintainer choose.
+
+## Triage A Specific Issue
+
+1. Gather context: read the full issue body, comments, labels, reporter, and dates.
+2. Parse prior triage notes to avoid re-asking answered questions.
+3. Explore relevant repo context using domain glossary terms and ADRs.
+4. Read `.out-of-scope/*.md` if present and surface matching prior rejections.
+5. Recommend a category and state with reasoning and a short codebase summary.
+6. For bugs, attempt reproduction before final recommendation: trace code, run focused tests or commands, and report successful repro, failed repro, or insufficient detail.
+7. If the issue needs fleshing out, run a grilling or clarification pass before marking it ready.
+8. Apply the outcome only after the requested action is clear.
+
+## Outcomes
+
+- `ready-for-agent`: post an Agent Brief comment and apply the mapped role.
+- `ready-for-human`: post an Agent Brief-style comment that explains why human work is required.
+- `needs-info`: post triage notes with established facts and specific reporter questions.
+- `wontfix` bug: post a polite explanation and close.
+- `wontfix` enhancement: create or update `.out-of-scope/<concept>.md`, link it from a comment, then close.
+- `needs-triage`: apply the role; comment only if useful.
+
+## Agent Brief
+
+An Agent Brief is the durable contract an AFK agent will work from. The original issue and discussion are context; the brief is the current specification.
+
+Write briefs that are durable, behavioral, complete, and scoped. Avoid file paths and line numbers. Name interfaces, types, commands, contracts, config shapes, and observable behavior when useful.
+
+Template:
+
+```markdown
+## Agent Brief
+
+**Category:** bug / enhancement
+**Summary:** one-line description
+
+**Current behavior:**
+Describe what happens now.
+
+**Desired behavior:**
+Describe what should happen, including edge cases and error conditions.
+
+**Key interfaces:**
+- Interface or contract name - what needs to change and why
+- Config shape or command - expected behavior
+
+**Acceptance criteria:**
+- [ ] Specific, testable criterion
+- [ ] Specific, testable criterion
+- [ ] Specific, testable criterion
+
+**Out of scope:**
+- Adjacent thing not included
+- Risky interpretation not allowed
+```
+
+## Needs-Info Template
+
+```markdown
+## Triage Notes
+
+**What we've established so far:**
+
+- fact 1
+- fact 2
+
+**What we still need from you (@reporter):**
+
+- specific question 1
+- specific question 2
+```
+
+Capture resolved facts under "established so far" so the work is not lost. Questions must be specific and actionable.
+
+## Out-Of-Scope Knowledge Base
+
+The `.out-of-scope/` directory stores durable records of rejected enhancement requests. One file should represent one concept, not one issue.
+
+File shape:
+
+```markdown
+# Concept Name
+
+## Why this is out of scope
+
+Durable reason, including project scope, architectural constraints, or strategic decision.
+
+## Prior requests
+
+- #123 - Request title
+```
+
+During triage, check existing out-of-scope records by concept similarity. If a new issue matches a prior rejection, surface it and ask whether the maintainer wants to confirm, reconsider, or proceed as distinct.
+
+Only write `.out-of-scope/` records for rejected enhancements, not bugs.
+
+## Quick State Override
+
+If the maintainer explicitly says to move an issue to a state, trust them. Confirm the exact label/comment/close action, then apply it. If moving to `ready-for-agent` without a grilling session, ask whether they want an Agent Brief written.
+
+## Spec Gate Policy
+
+Triage does not create implementation specs. When an issue has a `Spec gate` section, preserve it in the Agent Brief and do not expand it into a file-by-file implementation plan.