codex-orchestrator 2.0.11 → 2.0.12

package/internal-workflow/skills/spec-implementer/SKILL.md

@@ -1,133 +0,0 @@
----
-name: "spec-implementer"
-description: "Executes approved specs continuously with honest checklist updates, proportional validation, opt-in Git checkpoints, and required review/signoff."
----
-
-# Spec Implementer
-
-Execute one approved implementation spec continuously. Keep its checklist
-truthful and stop only at a real authority, evidence, safety, or explicit pause
-boundary. Do not redesign approved scope.
-
-Read before editing:
-
-- the complete approved spec and applicable repository instructions;
-- `references/review-loop.md` for approved-spec review ownership;
-- `../../docs/agents/contract-test-ledger.md` only when the spec contains
-  material contract invariants.
-
-## Modes
-
-The primary route remains `spec-implementer` whenever an approved spec is the
-execution authority. Do not report `implementation_size`, TDD, a Contract Test
-Ledger, or review as a replacement route; those are execution details inside
-this route.
-
-Compact and full specs use the same direct phase flow. `compact` describes
-document density, not implementation size or risk. Full mode adds only the
-concrete `Risk Controls`, stop conditions, validation, or coordination contract
-already present in the approved spec; it does not add review or reporting
-ceremony by itself.
-
-Use multiple agents only when the spec defines perfectly disjoint write scopes
-and one integrator. Otherwise execute single-agent.
-
-## Preflight
-
-1. Confirm `status`, `spec_mode`, `implementation_size`, `review_profile`,
-   repository count, authority, scope, and exclusions.
-2. Confirm first-phase targets, required services/env/data/fixtures, commands,
-   observable proof, protected paths, and rejected approaches.
-3. Stop if execution needs invented paths, symbols, contracts, commands, or
-   product decisions; if reality differs only in a bounded technical detail,
-   resolve it from repository evidence and record the adjustment.
-4. Keep an intermediate review checkpoint only when the spec explicitly names
-   a stable high-risk slice that later work will not invalidate. Move every
-   ordinary or unstable checkpoint to final review.
-5. Do not create `## Implementation Review State` yet.
-
-## Implementation
-
-For each phase:
-
-1. Re-read its scope and preconditions.
-2. For an applicable behavior slice, activate and read `$tdd` before the first
-   RED, then implement through that skill. A spec-provided failing command or
-   RED recorder does not replace loading the TDD contract.
-3. Update reached checklist and Contract Test Ledger items at natural
-   checkpoints; never save all updates for the end.
-4. Run the phase's targeted exit proof.
-5. Record a short `Blocked:` note for any item that cannot complete.
-6. Continue immediately when the exit proof passes and no stop condition
-   applies.
-
-Do not add cleanup, comments, helpers, abstractions, retries, flags, fallbacks,
-or compatibility paths outside the spec. A small implementation adjustment is
-allowed only when it preserves approved behavior and is supported by current
-repository evidence.
-
-## Git Checkpoints
-
-Default to no commits. `$spec-implementer` does not authorize Git writes.
-
-Use per-slice commits only when explicitly authorized and they materially help
-a disjoint multi-agent handoff, planned cross-session pause, or approved
-rollback boundary. Require a passed slice proof, stage only owned paths, follow
-`$commit`, and never push without separate authority. File/slice count and risk
-profile alone do not justify checkpoints.
-
-## Review And Validation
-
-Run targeted behavior tests and the smallest affected integration checks first.
-Use a full repository suite only when the spec or repository policy requires
-it, broad contract fan-out cannot be isolated, or the task is genuinely high.
-
-Run final `$code-review` only when the spec, repository policy, or
-`../../docs/agents/review-gates.md` applies. Ordinary medium work gets one
-`reviewer_standard` Full review on the settled diff. High gets two disjoint
-`reviewer_deep` lenses. Cleanup stays inside spec/standards review.
-
-Immediately before the first reviewer launch, create only the minimal
-`## Implementation Review State` required by `references/review-loop.md`.
-Reconcile a recorded live session before replacement after interruption.
-
-Repair compatible findings once and rerun affected validation. Coordinator
-verification closes ordinary medium/low behavior-preserving repairs. Use
-Closure only for critical/high, protected trust/data/concurrency/shared-contract
-impact, or invalidated mandatory coverage. Do not restart broad Full review
-unless the repair actually invalidated its coverage.
-
-## Stop Conditions
-
-Stop and report the exact blocker when:
-
-- a precondition, source contract, required proof, or protected path differs
-  materially from the approved spec;
-- exact execution requires a new product, scope, ownership, or risky trade-off
-  decision;
-- required validation or reviewer is unavailable and no approved substitute
-  exists;
-- multi-agent scopes overlap or integration ownership is missing;
-- an explicit user pause or halt condition is reached.
-
-Do not stop merely because the work is broad, review took time, or a medium/low
-finding required one repair.
-
-## Completion
-
-Complete only when reached checklist items are reconciled, affected proof and
-required review pass, protected paths and rejected approaches remain intact,
-and every unfinished item has a concrete status.
-
-For ordinary medium work report only:
-
-- behavior/contract implemented;
-- review result and repaired/open findings;
-- affected validation;
-- skipped checks and residual risk;
-- changed files and any authorized commits.
-
-For high, actual Closure, accepted risk, interrupted recovery, or multi-agent
-delivery, add the relevant invariants, reviewer coverage, defect IDs, session
-recovery, and handoff ownership. Do not create a separate report file unless
-the spec or the complexity of that exceptional handoff requires it.

package/internal-workflow/skills/spec-implementer/agents/openai.yaml

@@ -1,6 +0,0 @@
-interface:
-  display_name: "Spec Implementer"
-  short_description: "Execute approved specs with lean delivery"
-  default_prompt: "Use $spec-implementer to execute the approved spec continuously, default to no Git checkpoints, validate proportionately, and launch only stable required review gates."
-policy:
-  allow_implicit_invocation: true

package/internal-workflow/skills/spec-implementer/evals/evals.json

@@ -1,30 +0,0 @@
-{
-  "schema_version": 1,
-  "skill": "spec-implementer",
-  "cases": [
-    {
-      "id": "state-created-at-launch",
-      "prompt": "Execute an approved medium spec whose final review has not started yet.",
-      "expected": ["do not create review state during implementation", "persist minimal state immediately before reviewer launch"],
-      "forbidden": ["create per-slice review bookkeeping"]
-    },
-    {
-      "id": "medium-one-final-review",
-      "prompt": "Execute a normal medium spec with several vertical slices and no stable high-risk checkpoint.",
-      "expected": ["implement continuously", "run one final reviewer_standard on the settled diff"],
-      "forbidden": ["review after every slice", "run a full repository suite from file count"]
-    },
-    {
-      "id": "closure-stays-affected",
-      "prompt": "Final review finds one high defect in a shared schema and several ordinary low findings.",
-      "expected": ["repair once", "Closure verifies only the affected high-risk contract"],
-      "forbidden": ["restart all Full reviewers"]
-    },
-    {
-      "id": "resume-live-reviewer",
-      "prompt": "Resume after a reviewer poll timed out while the recorded session is still live.",
-      "expected": ["reconcile the existing session"],
-      "forbidden": ["mark it failed from timeout alone", "launch a duplicate reviewer"]
-    }
-  ]
-}

package/internal-workflow/skills/spec-implementer/references/review-loop.md

@@ -1,100 +0,0 @@
-# Approved Spec Implementation Review Loop
-
-This reference owns review orchestration for `$spec-implementer`. Read it only
-when executing an approved implementation spec. Shared Full/Closure and defect
-mechanics live in `../../../docs/agents/review-protocol.md`.
-
-Direct work and deterministic issue delivery use normal TDD and review gates;
-they must not create Implementation Review State.
-
-## Authority
-
-Only an approved implementation spec may own `## Implementation Review State`.
-PRDs, tickets, architecture notes, and chat summaries are not review-state
-owners. A substantive spec change returns through artifact review before
-implementation continues.
-
-Use the spec's `review_profile`; if absent, infer it from current evidence:
-
-- `simple`: narrow change with direct proof;
-- `medium`: default for ordinary implementation;
-- `high`: material failure consequence (financial side effect,
-  unauthorized/cross-owner behavior, durable corruption, or materially false
-  production result) plus an uncertainty amplifier (concurrency or event
-  ordering, delayed/background callbacks, retry/idempotency/recovery,
-  ownership transitions, or shared state across consumers).
-
-Implementation evidence may raise but never lower the approved profile.
-Recheck the settled diff immediately before the first reviewer launch and
-persist any required raise before launching reviewers.
-
-## Default Review Shape
-
-Implement continuously through vertical slices. Validate each affected behavior
-and run one final review on the settled diff when the gate applies.
-
-- `simple`: one `reviewer_fast` when review is required.
-- `medium`: one `reviewer_standard`, one bounded final Full, no intermediate
-  checkpoint by default.
-- `high`: two parallel `reviewer_deep` Full reviews with disjoint correctness
-  and spec/standards lenses.
-
-Add an intermediate checkpoint only when the approved spec explicitly names a
-stable high-risk slice whose review will remain valid after later work. Do not
-review unstable intermediate diffs or create per-slice review cycles.
-
-Cleanup stays inside the spec/standards lens. A concrete simplification risk may
-amplify that lens; size and profile labels alone do not create another gate.
-
-## Minimal Durable State
-
-Do not create review state during preflight or implementation. Immediately
-before the first actual reviewer launch, persist:
-
-- profile, authority path, settled target revision, and assigned lenses;
-- launch ID, reviewer/session handle, lineage, and `pending | completed | failed`;
-- returned findings, repair revision, affected validation, and Closure need.
-
-Write `pending` before launch and reconcile that session before replacing it
-after interruption or resume. A usable result becomes `completed`; an explicit
-failure becomes `failed`. A poll timeout while the session remains live is not
-a failure and does not authorize duplicate review.
-
-Record extended lineage/session history only for `high`, a real intermediate
-checkpoint, actual Closure, accepted risk, or interrupted recovery. Normal
-medium execution does not keep epochs, pass thresholds, activation counters, or
-per-slice handoff bookkeeping.
-
-## Findings And Closure
-
-Root aggregates findings, repairs compatible defects once, and reruns only
-affected validation. Coordinator verification closes ordinary medium/low
-behavior-preserving findings after confirming the repair matches the failure.
-
-Use shared-protocol Closure only for critical/high defects, protected
-trust/data/concurrency/shared API impact, or invalidated mandatory coverage.
-Closure stays with the affected reviewer lineage and repaired targets. Start a
-new Full only when the repair invalidated mandatory-lens coverage.
-
-Do not repeat review without a material change in target, evidence, repair, or
-source decision. Stop and surface the actual decision or evidence blocker when
-no progress is possible.
-
-## Completion
-
-Run gates in this order:
-
-1. affected behavior and integration validation;
-2. applicable final code review;
-3. Closure only when triggered;
-4. repository architecture/build/smoke gates required by policy or the spec;
-5. delivery actions explicitly authorized by the user or workflow.
-
-Return `Approved` only for the final settled revision when mandatory lenses and
-validation are complete and shared protocol state is clear. `Waived` records
-skipped coverage but is not approval. `Blocked` requires a concrete authority,
-evidence, reviewer, or convergence blocker—not elapsed time or review count.
-
-For normal medium work report only profile, review result, repaired/open
-findings, affected validation, skipped checks, and residual risk. Add extended
-session/defect accounting only when the exceptional state above exists.

package/internal-workflow/skills/triage/AGENT-BRIEF.md

@@ -1,192 +0,0 @@
-# Writing Agent Briefs
-
-An agent brief is a structured comment posted when a raw incoming issue moves
-to `ready-for-agent` through `$triage`. It is the authoritative specification
-for that AFK issue; the original body and discussion remain context.
-
-Do not post this comment for tickets generated by `$to-tickets`. Their approved
-issue body is already the authoritative execution brief and they bypass triage.
-
-## Principles
-
-### Durability over precision
-
-The issue may sit in `ready-for-agent` for days or weeks. The codebase will change in the meantime. Write the brief so it stays useful even as files are renamed, moved, or refactored.
-
-- **Do** describe interfaces, types, and behavioral contracts
-- **Do** name specific types, function signatures, or config shapes that the agent should look for or modify
-- **Don't** reference file paths — they go stale
-- **Don't** reference line numbers
-- **Don't** assume the current implementation structure will remain the same
-
-### Behavioral, not procedural
-
-Describe **what** the system should do, not **how** to implement it. The agent will explore the codebase fresh and make its own implementation decisions.
-
-- **Good:** "The `SkillConfig` type should accept an optional `schedule` field of type `CronExpression`"
-- **Bad:** "Open src/types/skill.ts and add a schedule field on line 42"
-- **Good:** "When a user runs `$triage` with no arguments, they should see a summary of issues needing attention"
-- **Bad:** "Add a switch statement in the main handler function"
-
-### Complete acceptance criteria
-
-The agent needs to know when it's done. Every agent brief must have concrete, testable acceptance criteria. Each criterion should be independently verifiable.
-
-- **Good:** "Running `gh issue list --label needs-triage` returns issues that have been through initial classification"
-- **Bad:** "Triage should work correctly"
-
-### Explicit scope boundaries
-
-State what is out of scope. This prevents the agent from gold-plating or making assumptions about adjacent features.
-
-### Proportional execution metadata
-
-Preserve an existing spec gate, verification contract, and material risk notes
-without turning the brief into an implementation spec. Omit those conditional
-fields when they are not material. High review risk changes proof depth, not
-brief length or solution breadth.
-
-## Template
-
-```markdown
-## Agent Brief
-
-**Category:** bug / enhancement
-**Summary:** one-line description of what needs to happen
-
-**Current behavior:**
-Describe what happens now. For bugs, this is the broken behavior.
-For enhancements, this is the status quo the feature builds on.
-
-**Desired behavior:**
-Describe what should happen after the agent's work is complete.
-Be specific about edge cases and error conditions.
-
-**Key interfaces:**
-- `TypeName` — what needs to change and why
-- `functionName()` return type — what it currently returns vs what it should return
-- Config shape — any new configuration options needed
-
-**Acceptance criteria:**
-- [ ] Specific, testable criterion 1
-- [ ] Specific, testable criterion 2
-- [ ] Specific, testable criterion 3
-
-**Implementation preparation:**
-- direct / compact spec / standard spec
-- Reason or accepted implementation spec reference
-
-**Verification:**
-- Behavior proof expected from the implementing agent
-- Required automated or live check, or `Not specified`
-
-**Risk / Review:**
-- Omit when no material risk exists
-- Otherwise: primary risk, main invariant, review focus, and final handoff expectation
-
-**Out of scope:**
-- Thing that should NOT be changed or addressed in this issue
-- Adjacent feature that might seem related but is separate
-```
-
-## Examples
-
-### Good agent brief (bug)
-
-```markdown
-## Agent Brief
-
-**Category:** bug
-**Summary:** Skill description truncation drops mid-word, producing broken output
-
-**Current behavior:**
-When a skill description exceeds 1024 characters, it is truncated at exactly
-1024 characters regardless of word boundaries. This produces descriptions
-that end mid-word (e.g. "Use when the user wants to confi").
-
-**Desired behavior:**
-Truncation should break at the last word boundary before 1024 characters
-and append "..." to indicate truncation.
-
-**Key interfaces:**
-- The `SkillMetadata` type's `description` field — no type change needed,
-  but the validation/processing logic that populates it needs to respect
-  word boundaries
-- Any function that reads SKILL.md frontmatter and extracts the description
-
-**Acceptance criteria:**
-- [ ] Descriptions under 1024 chars are unchanged
-- [ ] Descriptions over 1024 chars are truncated at the last word boundary
-      before 1024 chars
-- [ ] Truncated descriptions end with "..."
-- [ ] The total length including "..." does not exceed 1024 chars
-
-**Out of scope:**
-- Changing the 1024 char limit itself
-- Multi-line description support
-```
-
-### Good agent brief (enhancement)
-
-```markdown
-## Agent Brief
-
-**Category:** enhancement
-**Summary:** Add `.out-of-scope/` directory support for tracking rejected feature requests
-
-**Current behavior:**
-When a feature request is rejected, the issue is closed with a `wontfix` label
-and a comment. There is no persistent record of the decision or reasoning.
-Future similar requests require the maintainer to recall or search for the
-prior discussion.
-
-**Desired behavior:**
-Rejected feature requests should be documented in `.out-of-scope/<concept>.md`
-files that capture the decision, reasoning, and links to all issues that
-requested the feature. When triaging new issues, these files should be
-checked for matches.
-
-**Key interfaces:**
-- Markdown file format in `.out-of-scope/` — each file should have a
-  `# Concept Name` heading, a `**Decision:**` line, a `**Reason:**` line,
-  and a `**Prior requests:**` list with issue links
-- The triage workflow should read all `.out-of-scope/*.md` files early
-  and match incoming issues against them by concept similarity
-
-**Acceptance criteria:**
-- [ ] Closing a feature as wontfix creates/updates a file in `.out-of-scope/`
-- [ ] The file includes the decision, reasoning, and link to the closed issue
-- [ ] If a matching `.out-of-scope/` file already exists, the new issue is
-      appended to its "Prior requests" list rather than creating a duplicate
-- [ ] During triage, existing `.out-of-scope/` files are checked and surfaced
-      when a new issue matches a prior rejection
-
-**Out of scope:**
-- Automated matching (human confirms the match)
-- Reopening previously rejected features
-- Bug reports (only enhancement rejections go to `.out-of-scope/`)
-```
-
-### Bad agent brief
-
-```markdown
-## Agent Brief
-
-**Summary:** Fix the triage bug
-
-**What to do:**
-The triage thing is broken. Look at the main file and fix it.
-The function around line 150 has the issue.
-
-**Files to change:**
-- src/triage/handler.ts (line 150)
-- src/types.ts (line 42)
-```
-
-This is bad because:
-- No category
-- Vague description ("the triage thing is broken")
-- References file paths and line numbers that will go stale
-- No acceptance criteria
-- No scope boundaries
-- No description of current vs desired behavior

package/internal-workflow/skills/triage/OUT-OF-SCOPE.md

@@ -1,101 +0,0 @@
-# Out-of-Scope Knowledge Base
-
-The `.out-of-scope/` directory in a repo stores persistent records of rejected feature requests. It serves two purposes:
-
-1. **Institutional memory** — why a feature was rejected, so the reasoning isn't lost when the issue is closed
-2. **Deduplication** — when a new issue comes in that matches a prior rejection, the skill can surface the previous decision instead of re-litigating it
-
-## Directory structure
-
-```
-.out-of-scope/
-├── dark-mode.md
-├── plugin-system.md
-└── graphql-api.md
-```
-
-One file per **concept**, not per issue. Multiple issues requesting the same thing are grouped under one file.
-
-## File format
-
-The file should be written in a relaxed, readable style — more like a short design document than a database entry. Use paragraphs, code samples, and examples to make the reasoning clear and useful to someone encountering it for the first time.
-
-```markdown
-# Dark Mode
-
-This project does not support dark mode or user-facing theming.
-
-## Why this is out of scope
-
-The rendering pipeline assumes a single color palette defined in
-`ThemeConfig`. Supporting multiple themes would require:
-
-- A theme context provider wrapping the entire component tree
-- Per-component theme-aware style resolution
-- A persistence layer for user theme preferences
-
-This is a significant architectural change that doesn't align with the
-project's focus on content authoring. Theming is a concern for downstream
-consumers who embed or redistribute the output.
-
-```ts
-// The current ThemeConfig interface is not designed for runtime switching:
-interface ThemeConfig {
-  colors: ColorPalette; // single palette, resolved at build time
-  fonts: FontStack;
-}
-```
-
-## Prior requests
-
-- #42 — "Add dark mode support"
-- #87 — "Night theme for accessibility"
-- #134 — "Dark theme option"
-```
-
-### Naming the file
-
-Use a short, descriptive kebab-case name for the concept: `dark-mode.md`, `plugin-system.md`, `graphql-api.md`. The name should be recognizable enough that someone browsing the directory understands what was rejected without opening the file.
-
-### Writing the reason
-
-The reason should be substantive — not "we don't want this" but why. Good reasons reference:
-
-- Project scope or philosophy ("This project focuses on X; theming is a downstream concern")
-- Technical constraints ("Supporting this would require Y, which conflicts with our Z architecture")
-- Strategic decisions ("We chose to use A instead of B because...")
-
-The reason should be durable. Avoid referencing temporary circumstances ("we're too busy right now") — those aren't real rejections, they're deferrals.
-
-## When to check `.out-of-scope/`
-
-During triage (Step 1: Gather context), read all files in `.out-of-scope/`. When evaluating a new issue:
-
-- Check if the request matches an existing out-of-scope concept
-- Matching is by concept similarity, not keyword — "night theme" matches `dark-mode.md`
-- If there's a match, surface it to the maintainer: "This is similar to `.out-of-scope/dark-mode.md` — we rejected this before because [reason]. Do you still feel the same way?"
-
-The maintainer may:
-
-- **Confirm** — the new issue gets added to the existing file's "Prior requests" list, then closed
-- **Reconsider** — the out-of-scope file gets deleted or updated, and the issue proceeds through normal triage
-- **Disagree** — the issues are related but distinct, proceed with normal triage
-
-## When to write to `.out-of-scope/`
-
-Only when an **enhancement** (not a bug) is rejected as `wontfix`. The flow:
-
-1. Maintainer decides a feature request is out of scope
-2. Check if a matching `.out-of-scope/` file already exists
-3. If yes: append the new issue to the "Prior requests" list
-4. If no: create a new file with the concept name, decision, reason, and first prior request
-5. Post a comment on the issue explaining the decision and mentioning the `.out-of-scope/` file
-6. Close the issue with the `wontfix` label
-
-## Updating or removing out-of-scope files
-
-If the maintainer changes their mind about a previously rejected concept:
-
-- Delete the `.out-of-scope/` file
-- The skill does not need to reopen old issues — they're historical records
-- The new issue that triggered the reconsideration proceeds through normal triage