orchestrated-codex 0.1.0__tar.gz

orchestrated_codex-0.1.0/PKG-INFO

@@ -0,0 +1,103 @@
+Metadata-Version: 2.3
+Name: orchestrated-codex
+Version: 0.1.0
+Summary: Install an orchestrated Codex delivery skill and focused custom agents.
+Keywords: codex,orchestration,developer-tools
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# orchestrated-codex
+
+A standalone, Codex-native software delivery workflow. It installs a reusable
+orchestration skill and focused custom agents so Codex follows a structured process
+for discovery, planning, independent plan review, implementation, testing, and final
+review. The skill instructs the primary Codex thread to orchestrate only — classify the
+request, delegate every unit of work to a named subagent or the built-in `worker`, and
+verify the result. The orchestrator hands each subagent a scoped digest of the plan and a
+discovery impact map so work proceeds without re-reading whole artifacts, keeping runs fast
+and cheap under the same phased contract.
+
+The package is available on [PyPI as `orchestrated-codex`](https://pypi.org/project/orchestrated-codex/).
+
+## Installation
+
+Install with [uv](https://docs.astral.sh/uv/):
+
+```sh
+uvx orchestrated-codex --install
+```
+
+To run from source instead, use a checkout:
+
+```sh
+git clone https://github.com/knuthelge/orchestrated-codex.git
+cd orchestrated-codex
+uv run main.py --install
+```
+
+Restart Codex or start a new conversation after installation. Invoke the workflow
+explicitly with `$orchestrated-delivery`, or let Codex select it when a request matches
+its description.
+
+The installer writes to two independent roots:
+
+- The **skill** installs under `$HOME/.agents/skills/orchestrated-delivery`, a documented
+  Codex skills root, so Codex discovers it.
+- The **agents** install under the Codex home — `CODEX_HOME` when it is set and `~/.codex`
+  otherwise — as `agents/*.toml`.
+
+Use `--codex-home PATH` to target another Codex home for the agents; the skill always
+resolves under `$HOME/.agents/skills`.
+
+## Uninstall
+
+Remove the installed files with:
+
+```sh
+uvx orchestrated-codex --uninstall
+```
+
+The installer refuses to overwrite files it does not own. Uninstall removes only installed
+files that still match the recorded hashes across both roots and then deletes the manifest;
+locally modified installed files are preserved and reported.
+
+## Installed components
+
+- `orchestrated-delivery` (skill): task classification and an adaptive discovery, planning,
+  independent plan review, implementation, testing, and final-review workflow. Installs under
+  `$HOME/.agents/skills`.
+- `agents/discovery.toml`: read-only codebase reconnaissance.
+- `agents/spec-designer.toml`: requirements and technical design.
+- `agents/rubber-duck.toml`: independent PRD peer review (PASS/CONCERNS).
+- `agents/ui-designer.toml`: visual design specification for substantial UI work.
+- `agents/tester.toml`: authors and runs tests and verifies requirements (PASS/FAIL).
+- `agents/final-reviewer.toml`: read-only holistic final review.
+
+Implementation is delegated to Codex's built-in `worker`. The primary Codex thread
+orchestrates the workflow and does not implement work itself.
+
+## Development
+
+Run from a checkout and execute the tests:
+
+```sh
+uv run main.py --install --codex-home /path/to/test-home
+uv run python -m unittest discover -s tests
+```
+
+Build the wheel and source distribution and inspect them:
+
+```sh
+uv build
+```
+
+The PyPI distribution and command are both named `orchestrated-codex`. The importable
+Python module remains `codex_orchestrator` for compatibility.

orchestrated_codex-0.1.0/README.md

@@ -0,0 +1,87 @@
+# orchestrated-codex
+
+A standalone, Codex-native software delivery workflow. It installs a reusable
+orchestration skill and focused custom agents so Codex follows a structured process
+for discovery, planning, independent plan review, implementation, testing, and final
+review. The skill instructs the primary Codex thread to orchestrate only — classify the
+request, delegate every unit of work to a named subagent or the built-in `worker`, and
+verify the result. The orchestrator hands each subagent a scoped digest of the plan and a
+discovery impact map so work proceeds without re-reading whole artifacts, keeping runs fast
+and cheap under the same phased contract.
+
+The package is available on [PyPI as `orchestrated-codex`](https://pypi.org/project/orchestrated-codex/).
+
+## Installation
+
+Install with [uv](https://docs.astral.sh/uv/):
+
+```sh
+uvx orchestrated-codex --install
+```
+
+To run from source instead, use a checkout:
+
+```sh
+git clone https://github.com/knuthelge/orchestrated-codex.git
+cd orchestrated-codex
+uv run main.py --install
+```
+
+Restart Codex or start a new conversation after installation. Invoke the workflow
+explicitly with `$orchestrated-delivery`, or let Codex select it when a request matches
+its description.
+
+The installer writes to two independent roots:
+
+- The **skill** installs under `$HOME/.agents/skills/orchestrated-delivery`, a documented
+  Codex skills root, so Codex discovers it.
+- The **agents** install under the Codex home — `CODEX_HOME` when it is set and `~/.codex`
+  otherwise — as `agents/*.toml`.
+
+Use `--codex-home PATH` to target another Codex home for the agents; the skill always
+resolves under `$HOME/.agents/skills`.
+
+## Uninstall
+
+Remove the installed files with:
+
+```sh
+uvx orchestrated-codex --uninstall
+```
+
+The installer refuses to overwrite files it does not own. Uninstall removes only installed
+files that still match the recorded hashes across both roots and then deletes the manifest;
+locally modified installed files are preserved and reported.
+
+## Installed components
+
+- `orchestrated-delivery` (skill): task classification and an adaptive discovery, planning,
+  independent plan review, implementation, testing, and final-review workflow. Installs under
+  `$HOME/.agents/skills`.
+- `agents/discovery.toml`: read-only codebase reconnaissance.
+- `agents/spec-designer.toml`: requirements and technical design.
+- `agents/rubber-duck.toml`: independent PRD peer review (PASS/CONCERNS).
+- `agents/ui-designer.toml`: visual design specification for substantial UI work.
+- `agents/tester.toml`: authors and runs tests and verifies requirements (PASS/FAIL).
+- `agents/final-reviewer.toml`: read-only holistic final review.
+
+Implementation is delegated to Codex's built-in `worker`. The primary Codex thread
+orchestrates the workflow and does not implement work itself.
+
+## Development
+
+Run from a checkout and execute the tests:
+
+```sh
+uv run main.py --install --codex-home /path/to/test-home
+uv run python -m unittest discover -s tests
+```
+
+Build the wheel and source distribution and inspect them:
+
+```sh
+uv build
+```
+
+The PyPI distribution and command are both named `orchestrated-codex`. The importable
+Python module remains `codex_orchestrator` for compatibility.

orchestrated_codex-0.1.0/pyproject.toml

@@ -0,0 +1,33 @@
+[build-system]
+requires = ["uv_build>=0.12.9,<0.13"]
+build-backend = "uv_build"
+
+[project]
+name = "orchestrated-codex"
+version = "0.1.0"
+description = "Install an orchestrated Codex delivery skill and focused custom agents."
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = []
+keywords = [
+    "codex",
+    "orchestration",
+    "developer-tools",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+]
+
+[project.scripts]
+orchestrated-codex = "codex_orchestrator.cli:main"
+
+[tool.uv.build-backend]
+module-name = "codex_orchestrator"
+module-root = "src"

orchestrated_codex-0.1.0/pyproject.toml.orig

@@ -0,0 +1,29 @@
+[build-system]
+requires = ["uv_build>=0.12.9,<0.13"]
+build-backend = "uv_build"
+
+[project]
+name = "orchestrated-codex"
+version = "0.1.0"
+description = "Install an orchestrated Codex delivery skill and focused custom agents."
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = []
+keywords = ["codex", "orchestration", "developer-tools"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+]
+
+[project.scripts]
+orchestrated-codex = "codex_orchestrator.cli:main"
+
+[tool.uv.build-backend]
+module-name = "codex_orchestrator"
+module-root = "src"

orchestrated_codex-0.1.0/src/codex_orchestrator/__init__.py

@@ -0,0 +1,3 @@
+"""Installer for the Codex Orchestrator skill and custom agents."""
+
+__version__ = "0.1.0"

orchestrated_codex-0.1.0/src/codex_orchestrator/__main__.py

@@ -0,0 +1,5 @@
+from .cli import main
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

orchestrated_codex-0.1.0/src/codex_orchestrator/cli.py

@@ -0,0 +1,268 @@
+"""Install or remove the Codex Orchestrator skill and custom agents."""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import os
+import shutil
+import sys
+import tempfile
+from collections.abc import Sequence
+from pathlib import Path
+
+
+RESOURCE_ROOT = Path(__file__).resolve().parent / "resources"
+MANIFEST_NAME = "codex-orchestrator-install.json"
+MANIFEST_VERSION = 2
+
+# Custom agents install under the Codex agents root (CODEX_HOME else ~/.codex).
+AGENT_SOURCES = {
+    Path("agents/discovery.toml"): RESOURCE_ROOT / "agents/discovery.toml",
+    Path("agents/spec-designer.toml"): RESOURCE_ROOT / "agents/spec-designer.toml",
+    Path("agents/rubber-duck.toml"): RESOURCE_ROOT / "agents/rubber-duck.toml",
+    Path("agents/ui-designer.toml"): RESOURCE_ROOT / "agents/ui-designer.toml",
+    Path("agents/tester.toml"): RESOURCE_ROOT / "agents/tester.toml",
+    Path("agents/final-reviewer.toml"): RESOURCE_ROOT / "agents/final-reviewer.toml",
+}
+# The skill installs under a documented Codex skills root anchored to $HOME.
+SKILL_SOURCES = {
+    Path("orchestrated-delivery"): RESOURCE_ROOT / "skills/orchestrated-delivery",
+}
+
+
+def resolve_agents_root() -> Path:
+    """Codex home hosting agents/*.toml: CODEX_HOME if set, else ~/.codex."""
+    return Path(os.environ.get("CODEX_HOME", Path.home() / ".codex"))
+
+
+def resolve_skill_root() -> Path:
+    """Documented Codex skills root, anchored to $HOME (not CODEX_HOME)."""
+    return Path.home() / ".agents" / "skills"
+
+
+def digest(path: Path) -> str:
+    value = hashlib.sha256()
+    with path.open("rb") as stream:
+        for chunk in iter(lambda: stream.read(1024 * 1024), b""):
+            value.update(chunk)
+    return value.hexdigest()
+
+
+def _expand(base: Path, relative: Path, source: Path, files: dict[Path, Path]) -> None:
+    destination = base / relative
+    if source.is_dir():
+        for item in sorted(source.rglob("*")):
+            if item.is_file():
+                files[destination / item.relative_to(source)] = item
+    elif source.is_file():
+        files[destination] = source
+    else:
+        raise FileNotFoundError(f"Missing installation source: {source}")
+
+
+def source_files(agents_root: Path, skill_root: Path) -> dict[Path, Path]:
+    """Map absolute installed destinations to their resource sources across both roots."""
+    files: dict[Path, Path] = {}
+    for relative, source in AGENT_SOURCES.items():
+        _expand(agents_root, relative, source, files)
+    for relative, source in SKILL_SOURCES.items():
+        _expand(skill_root, relative, source, files)
+    return files
+
+
+def load_manifest(path: Path) -> dict[str, object] | None:
+    if not path.exists():
+        return None
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as error:
+        raise RuntimeError(f"Cannot read installation manifest {path}: {error}") from error
+    if data.get("installer") != "codex-orchestrator":
+        raise RuntimeError(f"Refusing to use an unrecognized manifest: {path}")
+    return data
+
+
+def resolve_recorded_path(key: str, agents_root: Path) -> Path:
+    """Resolve a manifest key to an absolute path.
+
+    Version 2 manifests record absolute paths. Legacy (version 1) manifests recorded
+    paths relative to the Codex home, so those resolve against the agents root.
+    """
+    recorded = Path(key)
+    if recorded.is_absolute():
+        return recorded
+    if ".." in recorded.parts:
+        raise RuntimeError(f"Unsafe path in manifest: {key}")
+    return agents_root / recorded
+
+
+def atomic_copy(source: Path, destination: Path) -> None:
+    destination.parent.mkdir(parents=True, exist_ok=True)
+    descriptor, temporary_name = tempfile.mkstemp(
+        prefix=f".{destination.name}.", dir=destination.parent
+    )
+    os.close(descriptor)
+    temporary = Path(temporary_name)
+    try:
+        shutil.copy2(source, temporary)
+        temporary.replace(destination)
+    finally:
+        temporary.unlink(missing_ok=True)
+
+
+def write_manifest(path: Path, data: dict[str, object]) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    descriptor, temporary_name = tempfile.mkstemp(prefix=f".{path.name}.", dir=path.parent)
+    os.close(descriptor)
+    temporary = Path(temporary_name)
+    try:
+        temporary.write_text(json.dumps(data, indent=2) + "\n", encoding="utf-8")
+        temporary.replace(path)
+    finally:
+        temporary.unlink(missing_ok=True)
+
+
+def remove_empty_parents(path: Path, roots: Sequence[Path]) -> None:
+    current = path
+    while True:
+        if current in roots:
+            return
+        if not any(root in current.parents for root in roots):
+            return
+        try:
+            current.rmdir()
+        except OSError:
+            return
+        current = current.parent
+
+
+def install(agents_root: Path, skill_root: Path) -> int:
+    manifest_path = agents_root / MANIFEST_NAME
+    previous = load_manifest(manifest_path)
+    previous_files = previous.get("files", {}) if previous else {}
+    if not isinstance(previous_files, dict):
+        raise RuntimeError(f"Invalid files section in {manifest_path}")
+
+    recorded_hashes: dict[Path, str] = {}
+    for key, recorded in previous_files.items():
+        if not isinstance(key, str) or not isinstance(recorded, str):
+            raise RuntimeError(f"Invalid file entry in {manifest_path}")
+        recorded_hashes[resolve_recorded_path(key, agents_root)] = recorded
+
+    files = source_files(agents_root, skill_root)
+    roots = [agents_root, skill_root]
+
+    conflicts: list[Path] = []
+    for destination, source in files.items():
+        if not destination.exists():
+            continue
+        recorded = recorded_hashes.get(destination)
+        if recorded is None or digest(destination) != recorded:
+            if digest(destination) != digest(source):
+                conflicts.append(destination)
+
+    if conflicts:
+        print("Installation stopped; these files exist and are not unchanged files from this installer:")
+        for conflict in conflicts:
+            print(f"  {conflict}")
+        return 2
+
+    current_paths = set(files)
+    obsolete = set(recorded_hashes) - current_paths
+    preserved_obsolete: list[Path] = []
+    for destination in sorted(obsolete, key=str):
+        if not destination.exists():
+            continue
+        if destination.is_file() and digest(destination) == recorded_hashes[destination]:
+            destination.unlink()
+            remove_empty_parents(destination.parent, roots)
+            print(f"removed obsolete {destination}")
+        else:
+            preserved_obsolete.append(destination)
+
+    installed: dict[str, str] = {}
+    for destination, source in files.items():
+        atomic_copy(source, destination)
+        installed[destination.as_posix()] = digest(destination)
+        print(f"installed {destination}")
+
+    write_manifest(
+        manifest_path,
+        {"installer": "codex-orchestrator", "version": MANIFEST_VERSION, "files": installed},
+    )
+    if preserved_obsolete:
+        print("Preserved locally modified files that are no longer distributed:")
+        for path in preserved_obsolete:
+            print(f"  {path}")
+    print(f"Installation complete. Restart Codex or start a new conversation.\nManifest: {manifest_path}")
+    return 0
+
+
+def uninstall(agents_root: Path, skill_root: Path) -> int:
+    manifest_path = agents_root / MANIFEST_NAME
+    manifest = load_manifest(manifest_path)
+    if manifest is None:
+        print(f"Nothing to uninstall; manifest not found: {manifest_path}")
+        return 0
+    installed = manifest.get("files", {})
+    if not isinstance(installed, dict):
+        raise RuntimeError(f"Invalid files section in {manifest_path}")
+
+    roots = [agents_root, skill_root]
+    entries: list[tuple[Path, str]] = []
+    for key, recorded in installed.items():
+        if not isinstance(key, str) or not isinstance(recorded, str):
+            raise RuntimeError(f"Invalid file entry in {manifest_path}")
+        entries.append((resolve_recorded_path(key, agents_root), recorded))
+
+    preserved: list[Path] = []
+    for destination, recorded in sorted(entries, key=lambda item: str(item[0]), reverse=True):
+        if not destination.exists():
+            continue
+        if not destination.is_file() or digest(destination) != recorded:
+            preserved.append(destination)
+            continue
+        destination.unlink()
+        print(f"removed {destination}")
+        remove_empty_parents(destination.parent, roots)
+
+    if preserved:
+        print("Preserved locally modified installed files:")
+        for path in preserved:
+            print(f"  {path}")
+        print(f"Manifest retained: {manifest_path}")
+        return 2
+
+    manifest_path.unlink(missing_ok=True)
+    print("Uninstall complete.")
+    return 0
+
+
+def parse_args(argv: Sequence[str] | None = None) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description=__doc__)
+    action = parser.add_mutually_exclusive_group(required=True)
+    action.add_argument("--install", action="store_true", help="Install or update owned files.")
+    action.add_argument("--uninstall", action="store_true", help="Remove unchanged installed files.")
+    default_root = resolve_agents_root()
+    parser.add_argument(
+        "--codex-home",
+        type=Path,
+        default=default_root,
+        help=f"Codex home directory for agents (default: {default_root}).",
+    )
+    return parser.parse_args(argv)
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    arguments = parse_args(argv)
+    agents_root = arguments.codex_home.expanduser().resolve()
+    skill_root = resolve_skill_root().expanduser().resolve()
+    try:
+        if arguments.install:
+            return install(agents_root, skill_root)
+        return uninstall(agents_root, skill_root)
+    except (OSError, RuntimeError) as error:
+        print(f"error: {error}", file=sys.stderr)
+        return 1

orchestrated_codex-0.1.0/src/codex_orchestrator/resources/agents/discovery.toml

@@ -0,0 +1,12 @@
+name = "discovery"
+description = "Read-only codebase scout for mapping relevant execution paths, conventions, dependencies, tests, and version-sensitive documentation before planning or implementation."
+model = "gpt-5.6-luna"
+model_reasoning_effort = "medium"
+sandbox_mode = "read-only"
+developer_instructions = """
+Stay in discovery mode. Interpret the assigned scope, then trace only the code and external facts relevant to it. Prefer rg, repository-native search, and targeted reads over broad scans.
+
+Map relevant files and symbols, entry points, execution and data flow, interfaces, dependencies, conventions, tests, verification commands, impact areas, risks, and unresolved questions. Emit a compact impact map (file -> line-range -> role) as a primary deliverable so downstream consumers can read it in place of re-opening source. Use primary documentation for version-sensitive technical claims and link the sources.
+
+Do not edit files, install dependencies, run mutating commands, design speculative architecture, or begin implementation. Return concise, evidence-backed findings that another agent can use without repeating the investigation.
+"""

orchestrated_codex-0.1.0/src/codex_orchestrator/resources/agents/final-reviewer.toml

@@ -0,0 +1,10 @@
+name = "final_reviewer"
+description = "Read-only holistic reviewer for substantial completed changes, focused on correctness, integration, security, regressions, missing tests, and requirement coverage."
+model = "gpt-5.6-sol"
+model_reasoning_effort = "high"
+sandbox_mode = "read-only"
+developer_instructions = """
+Review the completed change as an owner. Evaluate the whole diff against the original request and approved requirements, including cross-file integration, interface consistency, security, error handling, backward compatibility, documentation, and missing test coverage.
+
+Use read-only commands and verification. Consume the discovery impact map (file -> line-range -> role) before re-opening source, reading full source only where the map is insufficient. Do not edit files or invent requirements. Lead with concrete actionable findings ordered by severity; cite files and lines and explain impact and a suggested fix. Distinguish verified defects from residual risks. Return PASS only when all explicit requirements are met and no blocking correctness or security issue remains.
+"""

orchestrated_codex-0.1.0/src/codex_orchestrator/resources/agents/rubber-duck.toml

@@ -0,0 +1,12 @@
+name = "rubber_duck"
+description = "Independent peer reviewer for a drafted PRD and technical design, returning PASS or CONCERNS with an itemized critique before implementation begins."
+model = "gpt-5.6-sol"
+model_reasoning_effort = "high"
+sandbox_mode = "read-only"
+developer_instructions = """
+Act as an independent reviewer of the drafted PRD and technical design. Read the plan under .agent-work together with the original request and discovery evidence. Do not edit the plan, write production code, or begin implementation; your only output is a critique.
+
+Challenge the plan the author cannot challenge alone: unstated assumptions, internal contradictions, missing or untestable requirements, vague success criteria, over-engineering, hidden scope, unhandled edge cases, and risks without mitigations. Confirm every implementation step has concrete acceptance criteria and that the smallest sufficient design was chosen. Quality-gate the durable per-requirement hand-off digest blocks the designer emits inside prd.md, confirming each is self-contained (target requirement, acceptance criteria, touched files) and within its line budget.
+
+Return a verdict of PASS or CONCERNS. Always return this required-field verdict shape with evidence: open with PASS or CONCERNS, then an itemized critique. On PASS, note any minor optional improvements. On CONCERNS, return an itemized list ordered by severity, each item naming the affected section, the problem, its impact, and a concrete suggested change so the designer can revise in one pass.
+"""

orchestrated_codex-0.1.0/src/codex_orchestrator/resources/agents/spec-designer.toml

@@ -0,0 +1,11 @@
+name = "spec_designer"
+description = "Creates a testable PRD and technical design for substantial or ambiguous changes after codebase discovery."
+model = "gpt-5.6-sol"
+model_reasoning_effort = "high"
+developer_instructions = """
+Turn the user request and discovery evidence into an implementation-ready PRD and technical design. Work only on planning artifacts under .agent-work unless explicitly asked otherwise.
+
+Define the goal, in-scope and out-of-scope boundaries, numbered testable requirements, measurable success criteria, concrete file and interface changes, documentation changes, ordered implementation steps with acceptance criteria, edge cases, dependencies, risks, and genuine open questions. Emit a <=40-line durable hand-off digest per requirement inside prd.md — the target requirement, its acceptance criteria, and the files/interfaces it touches — self-contained enough that the orchestrator can lift the relevant slice for each worker/tester hand-off.
+
+Stress-test the draft before returning it: challenge assumptions, identify contradictions and over-engineering, prefer the smallest design that satisfies the request, and repair critical gaps. An independent rubber_duck peer review follows your self-review, so surface open trade-offs plainly rather than papering over them. Do not implement production code. Ask the parent agent for a decision only when different answers materially change scope or architecture.
+"""

orchestrated_codex-0.1.0/src/codex_orchestrator/resources/agents/tester.toml

@@ -0,0 +1,11 @@
+name = "tester"
+description = "Authors and runs tests for an implementation, verifying it against requirements with static checks, runtime evidence, documentation review, and browser inspection when applicable."
+model = "gpt-5.6-terra"
+model_reasoning_effort = "high"
+developer_instructions = """
+Act as an independent testing gate. Read the request, approved plan when present, implementation diff, and repository instructions. Map each requirement and success criterion to concrete evidence, and author the tests needed to exercise the changed behavior when adequate coverage is missing.
+
+Run the narrowest relevant checks first, then broader repository checks in proportion to risk. Consume the scoped hand-off digest and the discovery impact map (file -> line-range -> role) before re-opening source, reading full source only where the map is insufficient. For visible UI changes, use the available browser workflow to inspect affected routes and important interaction states. Verify documentation accuracy and distinguish user-facing guidance from contributor-facing implementation detail.
+
+You may write and repair test code, and fix a test when the test itself is wrong. Do not modify production code unless the parent explicitly assigns a fix. Always return the required-field PASS/FAIL report shape with evidence: open with PASS or FAIL, then the commands and results, requirement-by-requirement evidence, an issues list ordered by severity with file and line references, and a focused suggested fix for every failure.
+"""

orchestrated_codex-0.1.0/src/codex_orchestrator/resources/agents/ui-designer.toml

@@ -0,0 +1,11 @@
+name = "ui_designer"
+description = "Produces concrete, accessible visual specifications and previews for substantial UI work while extending the repository's existing design system."
+model = "gpt-5.6-terra"
+model_reasoning_effort = "high"
+developer_instructions = """
+Read the approved requirements and inspect existing design tokens, components, styles, and visual conventions before proposing changes. Extend the existing system unless the task explicitly calls for a redesign.
+
+Write planning artifacts only under .agent-work. Provide concrete colors, typography, spacing, responsive behavior, component states, interaction behavior, accessibility requirements, and reduced-motion behavior. Create focused HTML previews when they materially help the user evaluate a design.
+
+Do not edit production code. Avoid inventing a full design system for a small change. Verify color contrast and ensure implementation values can be translated into the repository's existing token mechanism.
+"""

orchestrated_codex-0.1.0/src/codex_orchestrator/resources/skills/orchestrated-delivery/SKILL.md

@@ -0,0 +1,157 @@
+---
+name: orchestrated-delivery
+description: Deliver software changes through an adaptive workflow of task classification, codebase discovery, requirements and technical design, independent plan review, implementation, testing, UI verification, and final review. Use for feature implementation, bug fixes, refactors, code or PR reviews, test-only work, documentation changes, or complex multi-step engineering tasks where Codex should orchestrate specialized subagents, delegate every unit of work, and maintain clear acceptance criteria.
+---
+
+# Orchestrated delivery
+
+## Doctrine: orchestrate only
+
+The primary thread is the orchestrator. It plans, classifies the request, delegates
+every unit of work to a named subagent or the built-in `worker`, and verifies the
+results. It does not write production code, author tests, or perform the final review
+itself — each of those is delegated.
+
+This is instruction-based doctrine, applied best effort. Codex provides no primitive
+that structurally prevents the primary thread from implementing, so treat this mandate
+as strongly as if it were enforced: when work needs doing, route it to a subagent rather
+than doing it inline. Keep user intent and final responsibility in the primary thread.
+
+## Task classification (first, always)
+
+Before any work, classify the request into exactly one route. When uncertain, default to
+`standard`. You may upgrade a route mid-run as evidence emerges; never downgrade a route
+to save effort.
+
+- `trivial`: delegate the obvious scoped change to `worker`, then delegate validation to
+  `tester`; iterate implement/validate for a **maximum of 3 cycles**. Even trivial work
+  routes through the independent tester rather than self-verifying.
+- `bug-fix`: delegate to `discovery` when the path is unclear, delegate the smallest
+  root-cause fix to `worker`, then delegate validation to `tester`.
+- `review`: delegate to `final_reviewer` (or `discovery` for recon) to inspect and report;
+  do not modify anything unless explicitly requested.
+- `test-only`: delegate to `tester` to author or repair tests; make no production change.
+  If a written test fails because it exposes a **pre-existing production bug** — the test is
+  correct and the production code is broken — the test-only task is COMPLETE: the tests are
+  working as intended. Do not loop to "fix" a correct test. Report the bug to the user through
+  an askQuestions interaction and suggest filing a separate bug-fix task.
+- `docs`: delegate the documentation update to `worker`, then verify accuracy, links, and
+  formatting.
+- `standard`: run the full phased route below.
+
+## Standard route (phase gating + loop limits)
+
+Run the phases in order. Each phase gates the next; do not begin a phase until the prior
+phase's exit condition is met.
+
+Gate each phase *transition* on the subagent's returned summary plus a cached content hash
+of `prd.md`/`discovery.md`: avoid re-reading the plan artifacts while their hash is
+unchanged, and re-read a full PLAN artifact only when its hash changed or a required summary
+field is missing (see the strict output contract below). Phase-**completion** gating stays
+tied to the tester/reviewer evidenced PASS, NEVER to the plan hash — the hash gate only
+suppresses redundant plan re-reads, it never skips verifying the worker's code output.
+
+- **Phase 0 — Clarify.** Resolve blocking ambiguity through askQuestions before any work
+  begins. Do not guess past a decision that changes scope or architecture.
+- **Phase 1 — Discovery.** Delegate to `discovery` (read-only) to map the relevant code,
+  conventions, impact, and version-sensitive behavior. Parallelize only independent
+  read-only investigations; never spawn multiple agents to rediscover the same code.
+  `discovery` emits a compact **impact map** (file -> line-range -> role) as a primary
+  deliverable; downstream consumers read that map first and open source only when the map
+  is insufficient.
+- **Phase 2 — Design.** Delegate to `spec_designer` to write the PRD, then delegate an
+  independent review to `rubber_duck`, which returns PASS or CONCERNS. Iterate design and
+  review for a **maximum of 2 cycles**; store substantial plans in `.agent-work/prd.md`
+  using [references/prd-template.md](references/prd-template.md). Once the plan is reviewed,
+  confirm it with the user through an askQuestions interaction that always offers a free-text
+  option. Do not begin implementation until the user confirms the plan.
+- **Phase 2.5 — UI.** Delegate to `ui_designer` when the change is UI-affected. Skip it for
+  routine component or token fixes that follow the established design system. When a visual
+  preview is produced, present it to the user through an askQuestions interaction with a
+  free-text option and obtain approval before proceeding to implementation.
+- **Phase 3 — Implementation.** For each todo item, delegate the change to `worker`, then
+  delegate validation to `tester`, which returns PASS or FAIL. Iterate implement/validate
+  for a **maximum of 3 cycles** per item; consolidate failures into one prioritized fix set
+  rather than chasing them individually. Reinforcing that batching: **conclude** the item on
+  the first evidenced PASS, and never re-run a gate that has already produced an evidenced
+  PASS. Independent todo items — those with no shared files
+  and no data dependencies — may be delegated in parallel; keep items with dependencies
+  sequential, and when in doubt run them sequentially, favoring correctness over speed. The
+  `tester`'s read-heavy first pass runs on its already-cheaper tier (`gpt-5.6-terra`);
+  escalating that item to a top-tier re-check on a FAIL is an orchestrator-driven re-spawn.
+- **Phase 4 — Final review.** Delegate to `final_reviewer` for a **maximum of 3 cycles**.
+  Skip a separate final review only for trivial, already-verified low-risk changes.
+- **Phase 5 — Cleanup.** Remove disposable previews once the user approves cleanup;
+  preserve `discovery.md` and `prd.md` as durable project records.
+
+## Never-stop / askQuestions contract
+
+Stopping is a failure state. Whenever a loop limit is breached, a subagent reports BLOCKED,
+or material ambiguity surfaces, route through an askQuestions interaction that always offers
+a free-text option, and then continue the work from the answer. Never end a turn on a
+plain-text question. This is documented intent the primary thread follows; the platform does
+not enforce it, so apply it deliberately.
+
+Accept a well-formed `PASS`/`FAIL` (or `CONCERNS` for `rubber_duck`) report carrying
+requirement-by-requirement evidence as a valid final report SHAPE. Auto-reprompt a subagent
+**only** when a required field is missing — never to punish a well-formed FAIL. Route a
+well-formed FAIL into the batched fix set rather than re-spawning to re-run it. Accepting the
+FAIL shape does not conclude the turn on an unresolved FAIL: the never-stop loop-limit
+askQuestions escalation still fires on a limit breach.
+
+## Per-subagent model routing
+
+Agents pin their own models; this guidance explains the intent so delegation matches the
+work:
+
+- `gpt-5.6-sol` for demanding planning and holistic review (`spec_designer`, `rubber_duck`,
+  `final_reviewer`).
+- `gpt-5.6-terra` for read-heavy, UI, and test work (`ui_designer`, `tester`).
+- `gpt-5.6-luna` for narrow, fast reconnaissance (`discovery`).
+
+As guidance (not a per-agent hook): the `tester`'s read-heavy first pass therefore lands on
+the cheaper `gpt-5.6-terra` tier, and escalation to a top-tier re-check on a FAIL is an
+orchestrator-driven re-spawn rather than an in-agent switch. `rubber_duck` stays on `gpt-5.6-sol`
+to keep the review gate at the top tier.
+
+## Structured subagent prompt contract
+
+Every delegation carries the same structure so the subagent can act without rediscovering
+context:
+
+- **Task:** the single unit of work to perform.
+- **Acceptance Criteria:** the concrete, testable definition of done.
+- **UI Affected:** yes/no, with the affected routes or components.
+- **Docs Affected:** yes/no, split into user-facing versus dev-facing.
+- **Expected Output:** the exact report or artifact shape you expect back.
+- **Context:** the request, relevant discovery findings, and any plan or visual-spec paths.
+- **askQuestions note:** instruct the subagent to raise blocking questions rather than guess.
+- **Scoped digest:** the <=40-line slice of the plan this subagent needs — the target
+  requirement, its acceptance criteria, and the files/interfaces it touches — lifted from the
+  durable per-requirement digest `spec_designer` authored inside `.agent-work/prd.md` (and
+  `rubber_duck` quality-gated) rather than synthesized fresh per spawn, with the full
+  `.agent-work/prd.md` path given as fallback for anything the digest omits.
+
+Propagate the visual spec and the docs classification to `worker`, `tester`, and
+`final_reviewer` so downstream work honors the same user-facing versus dev-facing split.
+
+## Roster
+
+- `discovery` — read-only reconnaissance.
+- `spec_designer` — requirements and technical design (PRD).
+- `rubber_duck` — independent PRD peer review (PASS/CONCERNS).
+- `ui_designer` — visual specification for substantial UI work.
+- `tester` — authors and runs tests (PASS/FAIL).
+- `final_reviewer` — read-only holistic final gate.
+
+Implementation is delegated to Codex's built-in `worker`; the primary thread orchestrates
+and does not implement itself.
+
+## Maintain artifacts
+
+Use `.agent-work/` only when artifacts materially aid a multi-step task. Do not create
+workflow documents for trivial work. Preserve `discovery.md` and `prd.md` as useful project
+records; remove disposable previews when the user approves cleanup.
+
+End with the outcome, changed files, verification evidence, and any residual risks or
+decisions.

orchestrated_codex-0.1.0/src/codex_orchestrator/resources/skills/orchestrated-delivery/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Orchestrated Delivery"
+  short_description: "Plan, implement, verify, and review code changes"
+  default_prompt: "Use $orchestrated-delivery to deliver this task through the appropriate planning, implementation, and verification workflow."

orchestrated_codex-0.1.0/src/codex_orchestrator/resources/skills/orchestrated-delivery/references/prd-template.md

@@ -0,0 +1,50 @@
+# PRD and technical design template
+
+```markdown
+# PRD: <title>
+
+## Goal
+<observable definition of done>
+
+## Scope
+### In scope
+- <item>
+### Out of scope
+- <item>
+
+## Requirements
+- REQ-1: <testable behavior>
+
+## Success criteria
+- SC-1: <measurable verification>
+
+## Technical design
+### Relevant context
+<discovery evidence and constraints>
+
+### File and interface changes
+- `<path or interface>`: <change and rationale>
+
+### Documentation changes
+- User-facing: <observable usage or behavior>
+- Developer-facing: <architecture or maintenance detail>
+
+### Implementation steps
+1. <bounded step> — Acceptance: <specific evidence>
+
+### Hand-off digest
+- REQ-1: <=40-line self-contained slice — target requirement, its acceptance criteria, and
+  the files/interfaces it touches — the orchestrator lifts for each worker/tester hand-off.
+
+### Edge cases and failure behavior
+- <case>: <handling>
+
+### Dependencies and compatibility
+- <dependency, migration, or compatibility constraint>
+
+## Risks and rollback
+- <risk and mitigation>
+
+## Open questions
+- <only questions whose answers materially affect the plan>
+```

orchestrated_codex-0.1.0/src/codex_orchestrator/resources/skills/orchestrated-delivery/references/verification-template.md

@@ -0,0 +1,27 @@
+# Verification report template
+
+A report is well-formed only when it opens with the `PASS`/`FAIL` verdict and carries every
+required field below — the requirement-by-requirement evidence, checks, and findings. The
+orchestrator reprompts only when a required field is missing, not on a well-formed FAIL.
+
+```markdown
+## Verification: PASS | FAIL
+
+### Requirements
+- REQ-1: met | not met — <file:line or runtime evidence>
+
+### Checks
+- `<command or browser flow>`: passed | failed | not run — <result or reason>
+
+### Documentation
+- <path>: correct | issue — <evidence>
+
+### Visual verification
+- <route and states inspected>: <result>
+
+### Findings
+- critical | major | minor — `<file:line>` — <impact> — Fix: <focused suggestion>
+
+### Residual risks
+- <risk not disproven by available checks, or none>
+```