codex-orchestrator 0.1.26 → 0.1.27

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.