codex-orchestrator 2.0.2 → 2.0.3

package/internal-workflow/skills/implementation-spec-review/SKILL.md

@@ -0,0 +1,211 @@
+---
+name: "implementation-spec-review"
+description: "Review compact or full implementation specs for deterministic executability, proportional scope, validation coverage, safety, and zero-guess execution before coding starts."
+---
+
+# Implementation Spec Review
+
+Review an implementation spec before execution begins. The spec is an execution contract for a downstream coding agent. Your job is to decide whether it can be executed safely without guessing, not whether the product idea is good.
+
+Use `../../docs/agents/confidence-rubric.md` when classifying blockers, execution risks, and optional improvements. High-confidence blockers need direct evidence from the spec, repo, issue, or trusted contract. Medium-confidence risks must name the one unresolved assumption. Low-confidence concerns are questions or verification gaps, not blockers.
+
+Use `../../docs/agents/contract-test-ledger.md` when reviewing behavior-changing specs with contract risk.
+
+This skill reviews three independent classifications from
+`implementation-spec-maker`: document shape (`spec_mode`), delivery shape
+(`implementation_size`), and consequence/uncertainty (`review_profile`). It
+also checks the declared `expected_repositories`. Never infer one dimension
+from another.
+
+It supports both document shapes:
+
+- **Compact specs:** dense single-agent specs whose exact scope, risk controls, and proof fit clearly. Compact does not mean small; a coherent medium/large or high-risk implementation may stay compact when ownership, sequencing, and validation remain deterministic. They do not need source-of-truth tables, file matrices, multi-agent contracts, or long halt sections unless a concrete ambiguity calls for them.
+- **Full specs:** lean contracts used when compact mode cannot express concrete coordination, contract, ownership, sequencing, or validation ambiguity safely.
+
+Do not punish a compact spec for omitting full-mode ceremony. Do not punish a full spec for using short risk-control bullets instead of large tables when the ownership and safety rules are still unambiguous. Do reject any spec, compact or full, that requires invention, hides risk, or cannot prove the intended behavior.
+
+When used inside the spec-making loop, return blockers and author questions clearly so the parent agent can relay them. Do not contact the user directly. Do not rewrite the spec unless explicitly asked.
+When already running as the assigned `reviewer_fast`, `reviewer_standard`, or
+`reviewer_deep` child, review inline and never spawn a grandchild. Otherwise,
+root must launch the reviewer selected by the shared review profile and must not
+self-review inline.
+
+## Review Posture
+
+- Be strict about determinism and safety.
+- Be proportional about format and ceremony.
+- Prefer concrete defects with repair instructions over broad commentary, but in Full Mode return every visible evidence-backed blocker and execution risk in the assigned lenses as one batch.
+- Treat false precision as a first-class defect: exact-looking claims must be grounded in source material, repo evidence, or trusted external sources.
+- Separate hard blockers from execution risks and optional improvements.
+- If the spec can be fixed by one sentence, name that sentence-level fix instead of expanding the spec.
+
+### Scope Conservation
+
+A review repair must not broaden approved product or operational scope. Prefer
+deleting or narrowing an unsafe proposal before adding a mechanism. Feature
+flags, telemetry systems, dashboards, rollout machinery, compatibility paths,
+and generic fallbacks are scope expansion unless the source requires them or a
+concrete evidenced failure path makes them necessary. Keep optional
+improvements optional; do not convert them into mandatory spec work.
+
+## Artifact Review Protocol
+
+Act as the implementation-spec Adapter for
+`../../docs/agents/artifact-review-loop.md`. The prompt assigns mode and lenses.
+Return actual coverage, reuse supplied IDs, and label new candidates
+`NEW-<LENS>-NN`; do not implement another review flow or lifecycle here.
+
+When invoked directly outside a maker Module, default to `Full` mode, cover all
+mandatory spec lenses, use no ledger unless one is supplied, and return only the
+single Adapter verdict. Do not claim a Module outcome or closure state.
+
+## Size-Aware Rules
+
+### Compact Specs
+
+Approve a compact spec when it has:
+
+- exact enough targets, commands, preconditions, and validation for the current task
+- numbered phases or a clear single phase
+- a simple progress/reconciliation rule
+- explicit blockers or `None`
+- observable behavior proof
+- no unresolved placeholders, pseudo-paths, or alternative commands
+
+Do not require these unless the task risk demands them:
+
+- source-of-truth map
+- file modification matrix
+- long halt checklist
+- defect closure section
+- multi-agent handoff contract
+- mandatory dedicated review at every phase
+
+### Lean Full Specs
+
+Treat these as signals to check whether compact mode leaves a concrete
+ambiguity; none selects full mode by itself:
+
+- multi-agent execution
+- persistence, migrations, schemas, DTOs, API contracts, or external contracts
+- auth, secrets, permissions, payments, caching, concurrency, background jobs, shared state, or destructive operations
+- changes across several runtime surfaces
+- one ticket with multi-agent coordination requirements
+- revision of an existing checklist with completed history
+
+For these specs, the expected shape is:
+
+- a short `Risk Controls` section naming only applicable ownership, safety, contract, concurrency/state, and forbidden-scope rules
+- phase steps with exact targets and validation
+- `Write Scope Summary` only when phases alone do not make the write set obvious, or when there is multi-agent work, broad runtime change, generated artifacts, or 5+ runtime files
+- task-specific `Halt Conditions` only when the compact stop rule is insufficient
+- `Integrator Coordination Contract` only for multi-agent execution
+
+Missing ownership, write-scope, validation, safety, or handoff details are defects. Missing tables are not defects when the lean sections are unambiguous.
+
+## Mandatory Review Lenses
+
+Across a Module full-review wave, cover all of these lenses according to the
+policy assignment, scaled to artifact risk; each reviewer owns only its
+assigned primary lenses. A standalone direct review covers all lenses:
+
+- **Determinism:** exact paths, symbols, commands, payloads, fixtures, and target behavior where execution depends on them.
+- **Evidence:** exact-looking claims are supported by source material, repo context, docs, issues, or external contract proof.
+- **Preconditions:** required services, env vars, fixtures, data state, feature flags, and prerequisites are explicit or intentionally `None`.
+- **Sequencing:** phases are ordered safely and have exit checks.
+- **Scope:** approved scope, out of scope, protected paths, and rejected approaches are clear enough to prevent drift.
+- **Contract Test Ledger:** contract-heavy behavior changes map ordering, precedence, threading, runtime contract, retry/idempotency, determinism, evidence, partial failure, and cardinality risks to first tests/proofs.
+- **Review Checkpoints and Focus:** high-risk specs use an early `$code-review` checkpoint only when the first risky slice becomes stable before later work. Otherwise the spec assigns concrete `Review Focus` lenses, targeted recipes, and bug classes to the final parallel review wave.
+- **Final Handoff Requirements:** medium/high-risk specs require a compact final response packet covering contract implemented, risky checkpoints, invariants proved, review findings/fixes, validation, skipped checks, residual risks, and files by role.
+- **Minimum solution and reuse:** the spec states a direct `Minimum Solution`, records `Added Complexity: None` or ties every added mechanism to a concrete invariant/failure, and removes anything that passes the deletion challenge. Prefer the fewest necessary concepts, owners, states, and integration points; line or file count is not decisive.
+- **Deep-module fit:** using the `$codebase-design` lens, new Modules or Seams pass the deletion test, avoid one-adapter abstraction, and test through the Module Interface.
+- **Risk Controls:** full specs include only applicable risk controls, and each control is specific enough to guide execution.
+- **Ownership:** source-of-truth ownership is explicit when behavior/data can drift across layers. A short `Source of Truth` bullet is enough when there is only one material owner.
+- **Validation:** checks prove observable behavior, not just compilation.
+- **Safety:** auth, secrets, credentials, destructive operations, persistence, concurrency, retries, and shared state have explicit constraints when touched.
+- **Multi-agent handoff:** if multi-agent, write scopes are disjoint and one integrator owns merge order and final reconciliation.
+- **Revision integrity:** if revising, still-valid completed items are preserved and stale completed items are reopened with a note.
+- **Completion clarity:** another agent could know when to stop, what passed, and what remains blocked.
+
+## What To Reject Immediately
+
+- The spec asks the executor to guess file names, symbol names, DTOs, schema details, API contracts, fixtures, or behavior.
+- The spec contains unresolved placeholders, pseudo-paths, example rows, bracket instructions, or alternative commands presented as executable.
+- The validation cannot prove the intended behavior.
+- The spec changes a contract-heavy behavior but has no Contract Test Ledger, or the ledger lists invariants without a first RED test/proof or a concrete blocked reason.
+- A high-risk spec neither defines a stable early checkpoint nor assigns the risky slice's concrete review focus to the final parallel wave.
+- A medium/high-risk spec has no final handoff requirement, leaving the user to manually reconstruct contract proof, review status, skipped checks, or residual risk from the diff.
+- Code changes are planned, the repo has an architecture check, and the spec omits it without a reason.
+- Exact-looking paths, commands, or symbols are not grounded in evidence and would force the executor to trust invented precision.
+- A multi-agent topology has overlapping write scopes, unclear integration ownership, or no merge/handoff contract.
+- A full spec touches a real safety/contract/state risk but has no applicable `Risk Controls` entry.
+- The spec says or implies the executor should continue despite a mismatch instead of stopping.
+- Security-sensitive or destructive work lacks explicit safe sources, guards, or stop-before-damage constraints.
+- The spec requires an added mechanism outside approved scope, or safe execution would depend on inventing that mechanism's need or contract.
+
+## Common Defects
+
+- Vague instructions like “update logic”, “handle edge cases”, “refactor if needed”, or “reuse existing code where possible” without exact targets.
+- Validation that checks only lint/build and misses the behavior changed by the spec.
+- A contract-heavy spec covers only a happy path and omits ordering, precedence, retry/idempotency, persistence/evidence, serialization, deterministic ordering, or cardinality invariants that are material to the touched flow.
+- A high-risk spec defers all review to the final diff even though the first risky state/contract slice becomes stable, is independently reviewable, and will not be invalidated by lower-risk work.
+- A medium/high-risk spec updates checklists and review gates but does not say what proof summary the executor must give the user at completion.
+- Required env vars, fixtures, payloads, services, or app state are absent.
+- Acceptance criteria are subjective, non-observable, or not tied to proof.
+- Ticket specs lose issue-only requirements such as `Implementation preparation`, `External contracts`, `Verification`, `Blocked by`, live prerequisites, or rejected approaches, or absorb sibling-ticket scope.
+- Evidence sections repeat a file inventory instead of proving determinism.
+- `Minimum Solution` is a slogan rather than a direct path, `Added Complexity` is absent or vague, or a smaller evidence-backed path satisfies the same approved behavior, invariants, and proof.
+- Full specs add large tables where 2-4 exact `Risk Controls` bullets would be clearer.
+- Full specs include generic halt checklists instead of task-specific stop conditions.
+- Full specs spread one rule across multiple files without a declared owner.
+- Compact specs expand into a large document without added safety value.
+
+## Defect Taxonomy
+
+- **Blocker:** The spec is unsafe or impossible to execute as written.
+- **Execution Risk:** The spec is executable but likely to cause drift, rework, or inconsistent implementation.
+- **Improvement:** The spec is usable, and the suggestion would materially sharpen it.
+
+Report blockers first. Mention improvements only when they matter.
+
+## Decision Rules
+
+- **Approved:** Deterministic, bounded, proportionate, and executable without guesswork.
+- **Needs Work:** Directionally usable but has ambiguities, missing proof, weak validation, or scope/control gaps.
+- **Rejected:** Unsafe to execute because it depends on invention, broad interpretation, overlapping ownership, missing validation, or missing safety controls.
+
+Scores:
+
+- `0`: missing or unsafe
+- `1`: partially specified or weakly proven
+- `2`: explicit and well-grounded
+
+## Output Format
+
+Always answer in Russian, keeping technical terms in English where appropriate. Use this exact structure:
+
+1. `Вердикт: Approved / Needs Work / Rejected` plus one sentence with the main reason.
+2. `Режим и покрытие: Full / Closure` with assigned lenses and evidence actually checked.
+3. `Оценка` with short scores `Determinism / Evidence / Validation / Safety` on a 0-2 scale.
+4. `Что уже исполнимо` with 2-4 bullets about what is concrete and safe.
+5. `Критические дефекты спецификации` with concrete blockers, ambiguity points, and failure mechanics. Quote the exact vague phrase, missing step, or unsafe instruction when justifying a defect. If there are no blockers, say `Нет`.
+6. `Defect Records` with the supplied stable ID or `NEW-<LENS>-NN`, class, confidence, invariant, failure, evidence, repair, affected sections, and status. If there are no defects, say `Нет`.
+7. `Что исправить перед исполнением` with exact changes needed in the spec. If nothing is needed, say `Ничего`.
+8. `Жесткие уточняющие вопросы` with 3-5 specific questions only if the spec cannot become deterministic without answers. If none, say `Нет`.
+
+Keep the output short, severe, and execution-oriented.
+
+## Anti-Overengineering Heuristic
+
+- If a compact direct flow is enough, flag unnecessary full-mode ceremony as an improvement or execution risk.
+- Run the whole-solution deletion challenge: if a mechanism can be removed while preserving every approved behavior, material invariant, and proof, require its removal. Do not remove a necessary mechanism merely because it adds a file, type, schema object, or boundary.
+- If a lean full spec gives exact risk controls without tables, do not ask for tables unless prose leaves ambiguity.
+- If a full spec has enough phase-level targets, do not ask for `Write Scope Summary` unless the write set or ownership is hard to audit.
+- If a full spec introduces an indirect flow where a direct one satisfies all constraints, treat that as a defect.
+- If a new abstraction exists only for cleanliness or future flexibility, return `Needs Work` and require its removal. Treat it as a blocker only when execution would be unsafe, broaden approved scope, or require invention.
+- Treat missing or unsupported `Minimum Solution` / `Added Complexity` evidence as `Needs Work`; escalate to `Rejected` only when the added mechanism is unsafe, unapproved scope, or requires invention.
+- If the review can make the spec safer by deleting ceremony rather than adding it, say so.
+
+## Tone
+
+Be direct, strict, and operational. No fluff, no architecture theater.

package/internal-workflow/skills/implementation-spec-review/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "Implementation Spec Review"
+  short_description: "Review one implementation spec"
+  default_prompt: "Review the supplied spec through the assigned package-owned operation and return its exact JSON report."
+policy:
+  allow_implicit_invocation: false

package/internal-workflow/skills/research/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: research
+description: Research material external API, SDK, specification, service, or source-code questions using primary sources and save one cited repository artifact. Use for requested durable/delegated research or multi-source contract uncertainty; not for narrow lookups, repo-only work, bug reproduction, or specialized docs tasks.
+---
+
+# Research
+
+Resolve one external question into reusable evidence for downstream coding work.
+The invoked skill authorizes one `researcher_standard` child; root owns source
+verification, artifact integration, user communication, and later decisions.
+
+## Route Proportionately
+
+- Read local evidence first: manifests, lockfiles, installed source, tests,
+  configs, ADRs, and repository docs.
+- Keep one narrow documentation lookup inline unless the user explicitly requests delegation or a durable artifact. When the lookup stays inline, use the owning specialized docs skill or tool and answer in chat without creating an artifact.
+- Invoke this workflow when the user requests delegated reading or a saved research result, or when a material decision needs multi-source comparison, freshness checking, or external contract synthesis.
+- Use repo exploration or bug-diagnosis skills when the owning evidence is local
+  code or runtime behavior. Research may supply one external contract input but
+  never owns bug reproduction or implementation.
+
+## Build The Research Capsule
+
+Before delegation, record:
+
+- the exact question and decision it must unblock;
+- relevant verified local context;
+- in-scope and excluded products, versions, environments, and claims;
+- allowed primary-source types and required freshness;
+- the repository output path.
+
+Use the repository's existing research-note convention. If none exists, choose
+`docs/research/YYYY-MM-DD/HHMM-<slug>.md`.
+
+## Delegate One Bounded Question
+
+Launch one fresh `researcher_standard` child with the Research Capsule and no
+inherited conclusions. The child is read-only and must return:
+
+1. a short answer;
+2. a claim-to-source ledger for every material fact;
+3. source version or publication/update date when available;
+4. conflicts, uncertainty, and missing evidence;
+5. clearly labelled inferences for the repository decision.
+
+While it reads, continue only independent local work. Do not make or implement
+the blocked decision before the research returns. If the named role is
+unavailable, perform the same bounded workflow inline and report the fallback;
+do not substitute an unrelated code explorer or reviewer.
+
+## Source Standard
+
+Prefer the source that owns the claim:
+
+1. official documentation or specifications;
+2. first-party source code, changelogs, release notes, or issue trackers;
+3. first-party APIs or published schemas.
+
+Use secondary material only to discover primary sources or to expose a disputed
+interpretation. Never promote it to authority when an owning source exists.
+Cite the exact page or repository location that supports each material claim.
+Separate sourced fact from inference, and state when current behavior cannot be
+confirmed.
+
+Use specialized source adapters when applicable: for example, `$openai-docs`
+for OpenAI products, Context7 for precise package documentation, and site
+parsers for extraction. Their output still must satisfy this source standard.
+
+## Verify And Save
+
+Root must open and verify every source behind a claim that changes architecture,
+scope, implementation, security, cost, or compatibility. Repair unsupported or
+overstated claims, then save exactly one Markdown artifact:
+
+```markdown
+# <Research question>
+
+## Decision To Unblock
+<decision and relevant local context>
+
+## Short Answer
+<concise answer>
+
+## Findings
+| Claim | Primary Source | Version / Date | Confidence |
+| --- | --- | --- | --- |
+| ... | ... | ... | ... |
+
+## Repository Implications
+<clearly labelled inferences and affected plans/specs/tickets>
+
+## Conflicts And Unknowns
+<conflicting sources, stale evidence, and unresolved questions>
+```
+
+Do not include credentials, private tokens, or copied secrets. Link or cite
+sources instead of reproducing long copyrighted passages.
+
+## Downstream Contract
+
+- Return the saved path and the decision it now supports.
+- Let plans, PRDs, tickets, and implementation specs cite the artifact as their
+  external Evidence Map instead of repeating the research.
+- Re-read only claims invalidated by changed versions, dates, contracts, or
+  source conflicts.
+- Treat the artifact as evidence, not implementation authority. Behavior-changing
+  work still follows the normal TDD, implementation, and review routes.

package/internal-workflow/skills/research/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "Research"
+  short_description: "Research from high-trust primary sources"
+  default_prompt: "Use $research to investigate this external question and save a cited repository artifact."
+policy:
+  allow_implicit_invocation: true

package/internal-workflow/skills/small-task-implementer/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: small-task-implementer
+description: Implement small low-risk coding tasks with narrow edits and targeted validation. Use for tiny fixes, UI/copy changes, config/build corrections, simple tests, or one-module changes that do not need plans, specs, orchestration, or heavy review.
+---
+
+# Small Task Implementer
+
+Use this skill for fast, bounded implementation when creating a PRD and approved ticket-delivery flow would be disproportionate.
+
+## Fit Gate
+
+Proceed only when all are true:
+
+- The requested behavior is clear or can be inferred from local code/tests without a product decision.
+- The change is expected to touch one small area or a few tightly related files.
+- There is a narrow validation path: targeted test, lint/typecheck, build check, UI proof, or direct command.
+- The task does not require a new plan, PRD, issue breakdown, implementation spec, migration, rollout, or multi-agent orchestration.
+
+Escalate instead of implementing when the task touches:
+
+- state transitions, queues, retries, idempotency, background jobs, persistence, migrations, schemas, DTO/API contracts, auth, permissions, payments, caching, or shared cross-module behavior;
+- multi-service, multi-repo, multi-agent, production/live-data, or external-contract work;
+- unclear product intent, ambiguous scope, no credible validation path, or likely broad refactoring.
+
+Escalation rule:
+
+- Escalate into the single canonical delivery flow: optional `$grilling` for unresolved product decisions, then `$spec-to-tickets` for the reviewed Approval Packet, then `$tickets-orchestrator` for approved ticket delivery.
+- For one risky behavior or technical contract, prefer one approved ticket and mark `compact spec` or `standard spec` only when the ticket plus repository evidence cannot remove execution ambiguity.
+- For several tickets sharing one unresolved contract or validation path, make the contract-defining ticket block its consumers; merge tickets that cannot be specified or verified independently instead of creating a wave-level implementation spec.
+- Escalate if the bug requires Bugfix Quality Gate analysis across multiple paths, states, async events, persistence, auth, cache, retries, workers, or contracts.
+
+## Workflow
+
+1. Inspect local context just enough to confirm fit.
+   - Read repo instructions and the smallest relevant code/test files.
+   - Check `git status --short` before editing.
+   - Preserve unrelated dirty work.
+
+2. Write a compact contract in the working update or internal task notes:
+
+```text
+Behavior:
+Scope boundary:
+Validation:
+```
+
+3. Implement the smallest complete change.
+   - Prefer existing patterns and owner modules.
+   - Avoid unrelated refactors, abstractions, cleanup, and compatibility paths.
+   - Before adding a helper, module, layer, or seam, apply the deletion test; keep it only if it improves current locality or leverage.
+   - Do not add pass-through modules, one-adapter seams, or tests coupled to Implementation details; escalate if no natural public test seam exists.
+   - Add or update a focused test only when behavior risk justifies it and the repo has a natural seam.
+   - For pure copy/docs/config changes, do not invent tests; run the cheapest relevant syntax/lint/check instead.
+
+4. Run targeted validation.
+   - Use the narrowest meaningful command first.
+   - If validation is unavailable or too expensive, state the concrete reason and residual risk.
+   - Do not run full CI unless local policy or the changed surface makes it necessary.
+
+5. Stop and escalate if implementation reveals hidden risk.
+   - Examples: shared contract drift, duplicate source of truth, missing test seam, broad file spread, concurrency, persistence, or product ambiguity.
+   - Leave a short explanation of what was discovered and which heavier flow should take over.
+
+## Output
+
+Final response must stay compact:
+
+```text
+Small Task Result
+
+Changed:
+- ...
+
+Proof:
+- ...
+
+Skipped:
+- none / ...
+
+Risk:
+- low / reason
+```
+
+If escalated, use:
+
+```text
+Escalated
+
+Reason:
+- ...
+
+Recommended flow:
+- Canonical ticket delivery / direct small task
+
+Evidence:
+- ...
+```

package/internal-workflow/skills/small-task-implementer/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "Small Task Implementer"
+  short_description: "Fast bounded low-risk code changes"
+  default_prompt: "Use $small-task-implementer to make this small low-risk change with targeted validation."
+policy:
+  allow_implicit_invocation: true

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

@@ -0,0 +1,197 @@
+---
+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 an approved implementation spec. Your job is to carry out the chosen spec, keep its checklist honest, and stop at the right boundaries. Do not redesign the work unless the spec or repo reality proves a blocker.
+
+This skill is standalone by default: it executes only an approved spec that the
+user has chosen to run. `$tickets-orchestrator` may invoke it inline at root for
+an accepted compact or standard ticket spec inside user-authorized orchestration;
+that does not authorize unrelated specs or broader delivery scope.
+
+When a spec contains a Contract Test Ledger, treat it as part of the execution contract. The shared reference is `../../docs/agents/contract-test-ledger.md`.
+
+All implementation review checkpoints and final review gates use
+`../../docs/agents/implementation-review-loop.md` as their caller-facing owner.
+This skill must not create a per-slice review flow or retry loop.
+
+## Spec Modes
+
+- **Compact specs:** execute directly as one continuous implementation flow with lightweight phase checkpoints. `compact` describes document density, not implementation size or risk. Use review/signoff gates only when the spec, repo policy, or change risk requires them.
+- **Full specs:** execute the same phase flow, but treat `Risk Controls`, task-specific `Halt Conditions`, and validation proof as hard constraints. Do not invent extra process just because the spec is full.
+- **Multi-agent specs:** follow the integrator contract exactly. If write scopes are not perfectly disjoint, stop before spawning workers.
+
+## Core Rules
+
+1. Follow the spec literally. Do not broaden scope, add cleanup, or re-plan unless a blocker is proven.
+2. Treat the spec checklist as the execution ledger.
+3. Update checklist items during implementation. For compact specs, update at natural checkpoints and phase exits. For full specs, or when the spec says so, update completed leaf items immediately.
+4. Do not save all checklist updates only for the final response.
+5. Re-read the current phase before moving on and reconcile already-completed unchecked items.
+6. If a step is blocked, leave it unchecked and record one short `Blocked:` note with the concrete reason.
+7. Treat Preconditions as hard blockers. Do not start a phase until they are satisfied, explicitly not applicable, or blocked.
+8. If the saved spec contains unresolved template text, placeholders, alternative commands, or pseudo-paths, stop and escalate.
+9. Honor Protected Paths and Rejected Approaches exactly as written.
+10. Apply the `$codebase-design` lens only when ownership or a public Module Interface or Seam changes. For any new private helper, run the deletion test and keep it only if it improves locality or leverage, without activating architecture workflow.
+11. Do not add pass-through modules, one-adapter seams, or test-only helpers unless the spec explicitly approves them.
+12. Add comments/docblocks only where the spec explicitly requires them.
+
+## Before Editing
+
+- Read the complete frontmatter before announcing execution strategy. Confirm the spec path, status, `spec_mode`, `implementation_size`, `review_profile`, and `expected_repositories`; infer a missing classification from evidence without rewriting the approved design.
+- Identify whether it is compact, full, or multi-agent. Do not call a compact spec full or equate compact with small.
+- Check required services, env vars, fixtures, repo state, and prerequisite issues.
+- Confirm the first phase targets exist as described.
+- Confirm validation commands are executable or explicitly not applicable.
+- If the spec has a Contract Test Ledger, confirm each reached invariant has a first test/proof or a concrete blocked reason before implementation.
+- If the spec has `Review Checkpoints` or `Review Focus`, keep only checkpoints whose target becomes stable before later slices. If later work will touch the same files, owners, or contracts, fold that coverage into the final parallel review instead of reviewing an unstable slice.
+- Resolve the implementation review profile and plan mandatory final coverage before launching any reviewer. Do not manufacture an early checkpoint merely because the profile is high.
+- Do not write `## Implementation Review State` during ordinary preflight or implementation. Immediately before the first actual reviewer launch, persist the short Review Plan and pending launch required by the Module; then update it after every usable reviewer result, repair batch, closure, waiver, or terminal outcome.
+- If the spec has `Final Handoff Requirements`, treat them as the final response contract. For medium/high-risk specs without explicit requirements, prepare the standard Final Risk Handoff anyway.
+- For full specs, read `Risk Controls` before editing and translate each applicable control into a concrete execution constraint.
+- Use `Write Scope Summary` when present as an audit aid. If it is absent, rely on phase targets unless the write set is ambiguous.
+- Stop if exact execution would require guessing.
+
+## Git Checkpoints
+
+Default to `none` and begin implementation without checkpoint ceremony. Mention the strategy once only when it materially affects delivery. Invoking `$spec-implementer` does not by itself authorize commits.
+
+Choose `per-slice` only when commits are explicitly authorized by the user or approved spec, slice diffs are truly isolated, and checkpoints materially improve recovery or handoff safety. Valid reasons are:
+
+- a multi-agent merge/handoff boundary
+- an explicitly planned pause or continuation in another session
+- a destructive or rollback boundary whose isolated commit is part of the approved safety plan
+
+Use `none` for ordinary single-agent execution, including compact/high specs, overlapping slices, and continuous work in one session. Slice count, file count, or review profile alone never justifies commits.
+
+At each checkpoint:
+
+- require a passed exit gate and applicable slice review, then reconcile and include tracked checklist/ledger updates
+- inspect the full diff, stage only slice-owned paths or hunks, follow `$commit` safety rules, and verify the hash
+- treat the applicable slice review as the pre-commit gate; final review still runs at the end
+
+If isolation later becomes unsafe, skip and record the reason. Never commit RED state, failed validation, unresolved findings, discovery-only work, or a partial slice. Never amend a checkpoint commit; put later fixes in a new commit. Never push unless explicitly requested. Report the strategy and slice-to-commit mapping, or the reason no checkpoints were created.
+
+## Phase Workflow
+
+For every phase:
+
+- Confirm phase dependencies and preconditions.
+- Execute only the steps assigned to that phase.
+- Update the spec checklist according to its mode.
+- Update any reached Contract Test Ledger rows as planned -> red -> green, or blocked with the missing seam/proof.
+- Run the phase exit gate.
+- If a `Review Checkpoint` applies after this phase, execute it through the
+  Module only when the target is settled and later slices do not invalidate its
+  files/contracts. Otherwise record that its lenses moved to final coverage and
+  continue without launching an unstable review.
+- Reconcile unchecked items for the current phase.
+- Re-check applicable `Risk Controls` before leaving the phase.
+- Check whether the phase introduced shallow modules, duplicated source-of-truth logic, or tests coupled to implementation details; fix only when inside approved scope, otherwise report it.
+- Run the repo architecture check when available, applicable, and required by the spec or repo policy.
+- If `per-slice` applies and this phase completes an implementation slice, create and verify its checkpoint commit before continuing.
+- Continue to the next phase only when the exit gate passes and no stop condition applies.
+- If the phase exit gate says `User Pause: Required`, stop and wait for the user's explicit command.
+
+## Review And Signoff
+
+Do not run a dedicated review subagent after every phase by default. Do run one at explicit `Review Checkpoints`; these are risk gates, not optional status updates.
+
+Before every reviewer launch, apply the Module's launch and reconciliation
+rules to the persisted `## Implementation Review State`; do not restate or
+replace those rules in this skill.
+
+Require final `$code-review` coverage when any of these apply:
+
+- the spec explicitly requires it
+- the repo policy requires it
+- the change is medium or large
+- the change touches multiple runtime files or shared behavior
+- the change touches API contracts, DTOs, schemas, persistence, auth, permissions, payments, caching, concurrency, background jobs, or shared state
+
+When `$code-review` is required for a checkpoint or final gate, keep orchestration at root so `$code-review` can launch the profile-selected reviewer topology. Invoking `$spec-implementer` authorizes that review; if the required role is unavailable, report the gate as unavailable/blocked instead of self-certifying it.
+
+Use one final `$code-review` wave after the implementation and validation settle.
+For `simple` and `medium`, one reviewer covers both lenses. For `high`, launch
+the correctness and spec/standards reviewers in parallel; the spec/standards
+lens includes bounded cleanup. Run separate `$cleanup-review` only when the
+user, approved source, or repo policy names a concrete evidenced reason that
+cannot fit that lens; size or risk labels alone are insufficient. Integrate safe
+fixes and rerun relevant validation before continuing.
+Before launching a fresh final reviewer, reconcile the settled revision against
+the Review Plan. Stop when an approved Full or Closure already covers every
+mandatory final lens; otherwise run `$code-review` only for the uncovered
+lenses. A `cleanup-only` result never substitutes for correctness or
+spec/standards coverage.
+
+For compact low-risk specs, final validation plus checklist reconciliation is enough unless the spec says otherwise.
+
+Treat review feedback as mandatory remediation when it is grounded in code or the spec. If review reveals ambiguity that cannot be resolved from the spec, code, or docs, pause and ask the user.
+
+Apply the Module's convergence and stop rules after every usable result and
+before every new launch.
+
+## Multi-Agent Execution
+
+- Use multiple agents only when the spec has explicit disjoint write scopes.
+- Keep one integrator responsible for merge sequencing, handoff checks, final validation, and checklist reconciliation.
+- Respect exclusive write scopes, handoff artifacts, forbidden overlap, and merge order exactly as written.
+- Never let two agents edit the same file, generated artifact, schema, source-of-truth rule, or shared contract at the same time.
+- If the spec lacks a clear integrator contract, execute single-agent or stop and ask for clarification.
+
+## Stop Conditions
+
+Stop immediately and escalate if:
+
+- a required precondition cannot be satisfied exactly
+- a required file, symbol, command, dependency, or interface differs from the spec
+- the saved spec contains unresolved template text or alternative commands
+- completing the task would require touching a Protected Path or using a Rejected Approach
+- validation cannot prove the intended behavior with available repo context
+- implementation would require unapproved scope, abstraction, migration, compatibility logic, or cleanup
+- a `Risk Controls` rule would be violated or is contradicted by repo reality
+- review exposes a real ambiguity that would require guessing
+- a user pause is required and the user has not explicitly said to proceed
+
+## Completion Standard
+
+Do not mark the task complete until:
+
+- completed checklist items are checked off according to the spec mode
+- every remaining unchecked item is blocked, intentionally unfinished, not applicable, or halted by an explicit stop condition
+- every reached phase exit gate has passed
+- applicable `Risk Controls` remained satisfied
+- reached Contract Test Ledger rows are green or explicitly blocked with evidence
+- validation commands and behavior proof have run, or skipped checks have a concrete reason
+- required review/signoff gates have run and grounded findings are fixed or blocked with evidence
+- the whole-spec Review Plan, review-pass history, and stable defect lifecycle remain
+  consistent with `implementation-review-loop.md`
+- protected paths remained untouched and rejected approaches were not used
+- required comments/docblocks were added only where the spec demanded them
+- the chosen Git checkpoint strategy was followed, and every created or skipped checkpoint was recorded
+- final user handoff is allowed by the spec
+
+## Final Risk Handoff
+
+For medium/high-risk specs, the final chat response must include a compact `Final Risk Handoff` block. Do not make the user ask for this separately, and do not replace it with a generic summary.
+
+Include:
+
+- **Contract implemented:** the one behavior/contract delivered, in user-facing terms.
+- **High-risk checkpoints:** each required checkpoint, review result, fixed findings, and any stop/continue decision.
+- **Main invariants proved:** the key Contract Test Ledger rows or equivalent proofs and their status.
+- **Code-review findings:** high/critical findings fixed, remaining medium/low findings, or `none`.
+- **Fixes after review:** concrete fixes made because of cleanup/code review, or `none`.
+- **Validation:** exact commands/proofs that passed.
+- **Skipped checks:** skipped or blocked checks with concrete reasons.
+- **Residual risks:** accepted remaining risks or `none`.
+- **Checkpoint commits:** slice-to-commit mapping or `none`; do not narrate hypothetical checkpoints that were never authorized or attempted.
+- **Implementation reviews:** profile, total review passes, Full/Closure count,
+  mandatory coverage, verified defect IDs, accepted-risk IDs with authority and
+  reason, and open defect IDs.
+- **Files by role:** state owner, orchestration, side effects, UI/projection, tests, docs/copy, as applicable.
+
+Only create a separate report file when the spec requires it or the work is broad enough that chat would lose important evidence, such as multi-agent execution, multiple review passes with findings, skipped live checks, production validation, or handoff to another person. Otherwise keep the spec checklist/ledger as the durable artifact and the final response as the concise decision packet.

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

@@ -0,0 +1,6 @@
+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