py-agent-orchestra 0.1.1__tar.gz

py_agent_orchestra-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alex Sokolsky
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

py_agent_orchestra-0.1.1/MANIFEST.in

@@ -0,0 +1 @@
+recursive-include tests *.py

py_agent_orchestra-0.1.1/PKG-INFO

@@ -0,0 +1,231 @@
+Metadata-Version: 2.4
+Name: py-agent-orchestra
+Version: 0.1.1
+Summary: A lightweight local workflow orchestrator for development and review agents.
+Author: Alex Sokolsky
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/asokolsky/agent-orchestra
+Project-URL: Documentation, https://github.com/asokolsky/agent-orchestra/tree/main/docs
+Project-URL: Issues, https://github.com/asokolsky/agent-orchestra/issues
+Project-URL: Repository, https://github.com/asokolsky/agent-orchestra
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Typing :: Typed
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pydantic<3,>=2.12
+Dynamic: license-file
+
+# agent-orchestra
+
+Agents are good.  Collaborating agents are even better.
+Claude has
+[sub-agents](https://code.claude.com/docs/en/sub-agents)
+and OpenAI has
+[subagents](https://learn.chatgpt.com/docs/agent-configuration/subagents).
+But... How about combining the agents from different vendors?
+
+[`agent-orchestra`](docs/cli.md) is a local CLI for coordinating coding agents.
+Each agent gets a role and an assigned Git worktree. Workflow state and review
+artifacts stay outside that worktree.
+
+What do you get after the agents finish? An approval tied to one exact diff,
+schema-validated responses, and evidence you can inspect later.
+
+Use an isolated linked worktree for development and an exact-head detached
+worktree for remote review.
+
+## Problem We Are Trying to Solve
+
+Coding agents can implement and review changes, but coordinating several agent
+task attempts is still largely manual.
+
+Agent-orchestra intends to be a thin coordination layer offering improved agent productivity.
+
+## Concepts
+
+See [Roles, runtimes, adapters, and capabilities](docs/concepts.md) for the
+canonical definitions. See the [CLI reference](docs/cli.md) for every command,
+option, default, output, and exit behavior.
+
+Agent Orchestra distinguishes source-code reviewers and source-code developers,
+which exchange diff-bound findings, from issue reviewers and issue creators,
+which exchange readiness feedback about issue prose. The shorter persisted role
+values `reviewer` and `developer` refer to the source-code roles unless an
+`issue_review` job supplies the scenario context.
+
+## Toolchain
+
+The project targets Python 3.14 and requires Git 2.36 or newer for
+NUL-delimited worktree metadata. `mise` installs `uv` and provides the routine
+project tasks. `uv` manages the virtual environment and dependencies, runs the
+Python tools, and builds the source and wheel distributions. Ruff provides
+formatting and linting, mypy checks types, and pytest runs the test suite.
+
+## Installation
+
+Agent Orchestra currently requires Python 3.14. Install the published CLI with
+[`uv`](https://docs.astral.sh/uv/guides/tools/):
+
+```shell
+uv tool install py-agent-orchestra
+agent-orchestra --version
+```
+
+[`pipx`](https://pipx.pypa.io/) is an equivalent option:
+
+```shell
+pipx install py-agent-orchestra
+```
+
+The PyPI project is named `py-agent-orchestra`; it installs the
+`agent-orchestra` command. Then install the bundled developer and reviewer
+skills for Codex and Claude Code:
+
+```shell
+agent-orchestra skills install \
+  --skill agent-orchestra-developer \
+  --skill agent-orchestra-reviewer
+```
+
+The [primer](docs/primer.md) continues from here. If you want to change Agent
+Orchestra itself, use the source-checkout steps under [Development](#development).
+
+Provider diagnostics, built-in runtime arguments, and canonical evidence names
+are declared in versioned TOML files under
+`src/agent_orchestra/manifest/`. These files ship in both distribution formats
+and are validated before the CLI handles a command. See
+[Packaged knowledge manifests](docs/design.md#packaged-knowledge-manifests) for
+the schema, compatibility rules, and stable failure codes.
+
+## Supported scenarios
+
+- The implemented [local development and review workflow](docs/workflows.md#local-development-and-review)
+  captures an existing uncommitted diff as a job, dispatches an independent
+  source-code reviewer, sends structured findings to a source-code developer
+  for remediation, and
+  repeats review against each new diff digest. Codex and Claude Code can be
+  selected independently for either role. Interrupted and validation-required
+  jobs can resume from durable task and attempt evidence. Approval stops at the
+  commit-authorization boundary; committing and publishing remain separate
+  user-authorized actions.
+- The implemented [issue-refinement workflow](docs/workflows.md#issue-refinement)
+  captures a GitHub or GitLab issue and reviews its immutable source digest
+  before development
+  begins. An issue reviewer checks that its problem statement, scope, constraints,
+  risks, and acceptance criteria are clear and testable, then communicates
+  actionable feedback to the issue creator. The issue can be revised and reviewed
+  again until it is ready for implementation. Codex and Claude Code receive the
+  same provider-neutral request. Review is read-only; the generated feedback
+  can be posted only through a separate explicitly authorized command.
+- The implemented [`audit`](docs/cli.md#audit) view reconstructs ordered state,
+  tasks, attempts, canonical message summaries, and provider actions for either
+  workflow. Optional local verification checks the finalized evidence index and
+  hashes without reading process-stream contents or contacting a provider.
+- The implemented [`stats`](docs/cli.md#stats) report summarizes review verdicts,
+  job standing, and finding dispositions across a rolling time window while
+  identifying jobs whose history is unavailable.
+- The implemented [settings and retention commands](docs/cli.md#global-settings)
+  provide XDG-aware storage defaults, effective-value inspection, and a
+  dry-run-first policy for expiring terminal job evidence. Database cleanup and
+  unmatched-directory cleanup require separate explicit options.
+- The designed [remote pull-request review workflow](docs/workflows.md#remote-pull-request-review)
+  starts from a pull-request URL and reviews one exact remote head. Remote
+  pull-request enqueueing and provider-side review actions are not implemented.
+
+The [design and message contract](docs/design.md) defines the shared protocol
+and the [CLI reference](docs/cli.md) documents the implemented commands.
+
+## Using it
+
+The [primer](docs/primer.md) takes you from an unreviewed change to a review you
+can act on: installing the role skills, capturing a diff, running the review, and
+reading the result.
+
+The [documentation index](docs/README.md) says what every other document is for.
+
+## Current scope
+
+The current implementation provides:
+
+- typed job, review, and finding models;
+- an explicit, validated state machine;
+- SQLite job storage with transition history and optimistic updates;
+- an interface for agent adapters with timeouts;
+- digest capture for tracked and untracked local changes;
+- Markdown review rendering;
+- commands to initialize state, enqueue local changes from one repo or a
+  directory of repos, and inspect jobs and tasks;
+- commands to capture GitHub and GitLab issues and run digest-bound,
+  provider-neutral readiness reviews;
+- XDG-aware persistent settings plus dry-run-first evidence retention with
+  auditable expiry markers and fail-closed orphan handling;
+- a Python-native installer for Codex and Claude Code skills;
+- versioned developer and reviewer skills under `skills/`;
+- built-in Codex and Claude Code adapters for developer and reviewer roles,
+  selected independently, plus a custom one-review command escape hatch;
+- a bounded remediation loop with strict messages, finding dispositions,
+  digest progress checks, role-specific timeouts, resumable interruptions and
+  blocked handoffs, and iteration exhaustion;
+- adapter-neutral attempt records separating requested and effective model
+  provenance, plus read-only process stream viewing through tasks.
+
+The source-code roles are documented separately:
+
+- [Source-code developer role](docs/role-developer.md)
+- [Source-code reviewer role](docs/role-reviewer.md)
+- [Issue reviewer role](docs/role-issue-reviewer.md)
+- [Issue creator responsibility](docs/role-issue-creator.md)
+
+Installation and invocation examples are in the
+[primer](docs/primer.md).
+
+Every review and remediation request, result, artifact, attempt
+configuration, process log, and terminal failure is persisted outside the
+worktree. Recoverable jobs continue with the same job ID through the
+[`resume` command](docs/cli.md#resume); terminal replacements can retain lineage
+through [`enqueue-local --supersedes`](docs/cli.md#enqueue-local). Initial
+clean-worktree development, worktree creation, leases, and remote pull-request
+operations remain subsequent increments. Issue-review feedback can be posted to
+GitHub or GitLab only through the explicit `post-issue-feedback --authorize`
+boundary.
+
+## Development
+
+Install the toolchain, synchronize the development dependencies, and run the
+standard gates:
+
+```shell
+mise install
+uv sync --group dev
+mise run format
+mise run lint
+mise run mypy
+mise run tests
+mise run build
+mise run verify-dist
+git diff --check
+```
+
+Continuous integration runs the same gates on every push and pull request,
+substituting `mise run format-check` for `mise run format` so a branch is
+verified rather than rewritten. Run `mise run format-check` locally to see what
+CI will see.
+
+Authenticated runtime checks are deliberately separate from the ordinary test
+suite. After installing the corresponding role skills, run
+`mise run test-live-claude` or `mise run test-live-codex`; see
+[Opt-in live runtime verification](docs/cli.md#opt-in-live-runtime-verification)
+for prerequisites, cost, isolation, and failure semantics.
+
+`mise run tests` distributes the suite across one worker per available CPU,
+which takes it from about a minute to about fifteen seconds. Parallel workers
+interleave their output, so use `mise run tests-serial` when reading a single
+failure: it runs everything in one verbose process. Both tasks run the same
+tests and must both pass.

py_agent_orchestra-0.1.1/README.md

@@ -0,0 +1,207 @@
+# agent-orchestra
+
+Agents are good.  Collaborating agents are even better.
+Claude has
+[sub-agents](https://code.claude.com/docs/en/sub-agents)
+and OpenAI has
+[subagents](https://learn.chatgpt.com/docs/agent-configuration/subagents).
+But... How about combining the agents from different vendors?
+
+[`agent-orchestra`](docs/cli.md) is a local CLI for coordinating coding agents.
+Each agent gets a role and an assigned Git worktree. Workflow state and review
+artifacts stay outside that worktree.
+
+What do you get after the agents finish? An approval tied to one exact diff,
+schema-validated responses, and evidence you can inspect later.
+
+Use an isolated linked worktree for development and an exact-head detached
+worktree for remote review.
+
+## Problem We Are Trying to Solve
+
+Coding agents can implement and review changes, but coordinating several agent
+task attempts is still largely manual.
+
+Agent-orchestra intends to be a thin coordination layer offering improved agent productivity.
+
+## Concepts
+
+See [Roles, runtimes, adapters, and capabilities](docs/concepts.md) for the
+canonical definitions. See the [CLI reference](docs/cli.md) for every command,
+option, default, output, and exit behavior.
+
+Agent Orchestra distinguishes source-code reviewers and source-code developers,
+which exchange diff-bound findings, from issue reviewers and issue creators,
+which exchange readiness feedback about issue prose. The shorter persisted role
+values `reviewer` and `developer` refer to the source-code roles unless an
+`issue_review` job supplies the scenario context.
+
+## Toolchain
+
+The project targets Python 3.14 and requires Git 2.36 or newer for
+NUL-delimited worktree metadata. `mise` installs `uv` and provides the routine
+project tasks. `uv` manages the virtual environment and dependencies, runs the
+Python tools, and builds the source and wheel distributions. Ruff provides
+formatting and linting, mypy checks types, and pytest runs the test suite.
+
+## Installation
+
+Agent Orchestra currently requires Python 3.14. Install the published CLI with
+[`uv`](https://docs.astral.sh/uv/guides/tools/):
+
+```shell
+uv tool install py-agent-orchestra
+agent-orchestra --version
+```
+
+[`pipx`](https://pipx.pypa.io/) is an equivalent option:
+
+```shell
+pipx install py-agent-orchestra
+```
+
+The PyPI project is named `py-agent-orchestra`; it installs the
+`agent-orchestra` command. Then install the bundled developer and reviewer
+skills for Codex and Claude Code:
+
+```shell
+agent-orchestra skills install \
+  --skill agent-orchestra-developer \
+  --skill agent-orchestra-reviewer
+```
+
+The [primer](docs/primer.md) continues from here. If you want to change Agent
+Orchestra itself, use the source-checkout steps under [Development](#development).
+
+Provider diagnostics, built-in runtime arguments, and canonical evidence names
+are declared in versioned TOML files under
+`src/agent_orchestra/manifest/`. These files ship in both distribution formats
+and are validated before the CLI handles a command. See
+[Packaged knowledge manifests](docs/design.md#packaged-knowledge-manifests) for
+the schema, compatibility rules, and stable failure codes.
+
+## Supported scenarios
+
+- The implemented [local development and review workflow](docs/workflows.md#local-development-and-review)
+  captures an existing uncommitted diff as a job, dispatches an independent
+  source-code reviewer, sends structured findings to a source-code developer
+  for remediation, and
+  repeats review against each new diff digest. Codex and Claude Code can be
+  selected independently for either role. Interrupted and validation-required
+  jobs can resume from durable task and attempt evidence. Approval stops at the
+  commit-authorization boundary; committing and publishing remain separate
+  user-authorized actions.
+- The implemented [issue-refinement workflow](docs/workflows.md#issue-refinement)
+  captures a GitHub or GitLab issue and reviews its immutable source digest
+  before development
+  begins. An issue reviewer checks that its problem statement, scope, constraints,
+  risks, and acceptance criteria are clear and testable, then communicates
+  actionable feedback to the issue creator. The issue can be revised and reviewed
+  again until it is ready for implementation. Codex and Claude Code receive the
+  same provider-neutral request. Review is read-only; the generated feedback
+  can be posted only through a separate explicitly authorized command.
+- The implemented [`audit`](docs/cli.md#audit) view reconstructs ordered state,
+  tasks, attempts, canonical message summaries, and provider actions for either
+  workflow. Optional local verification checks the finalized evidence index and
+  hashes without reading process-stream contents or contacting a provider.
+- The implemented [`stats`](docs/cli.md#stats) report summarizes review verdicts,
+  job standing, and finding dispositions across a rolling time window while
+  identifying jobs whose history is unavailable.
+- The implemented [settings and retention commands](docs/cli.md#global-settings)
+  provide XDG-aware storage defaults, effective-value inspection, and a
+  dry-run-first policy for expiring terminal job evidence. Database cleanup and
+  unmatched-directory cleanup require separate explicit options.
+- The designed [remote pull-request review workflow](docs/workflows.md#remote-pull-request-review)
+  starts from a pull-request URL and reviews one exact remote head. Remote
+  pull-request enqueueing and provider-side review actions are not implemented.
+
+The [design and message contract](docs/design.md) defines the shared protocol
+and the [CLI reference](docs/cli.md) documents the implemented commands.
+
+## Using it
+
+The [primer](docs/primer.md) takes you from an unreviewed change to a review you
+can act on: installing the role skills, capturing a diff, running the review, and
+reading the result.
+
+The [documentation index](docs/README.md) says what every other document is for.
+
+## Current scope
+
+The current implementation provides:
+
+- typed job, review, and finding models;
+- an explicit, validated state machine;
+- SQLite job storage with transition history and optimistic updates;
+- an interface for agent adapters with timeouts;
+- digest capture for tracked and untracked local changes;
+- Markdown review rendering;
+- commands to initialize state, enqueue local changes from one repo or a
+  directory of repos, and inspect jobs and tasks;
+- commands to capture GitHub and GitLab issues and run digest-bound,
+  provider-neutral readiness reviews;
+- XDG-aware persistent settings plus dry-run-first evidence retention with
+  auditable expiry markers and fail-closed orphan handling;
+- a Python-native installer for Codex and Claude Code skills;
+- versioned developer and reviewer skills under `skills/`;
+- built-in Codex and Claude Code adapters for developer and reviewer roles,
+  selected independently, plus a custom one-review command escape hatch;
+- a bounded remediation loop with strict messages, finding dispositions,
+  digest progress checks, role-specific timeouts, resumable interruptions and
+  blocked handoffs, and iteration exhaustion;
+- adapter-neutral attempt records separating requested and effective model
+  provenance, plus read-only process stream viewing through tasks.
+
+The source-code roles are documented separately:
+
+- [Source-code developer role](docs/role-developer.md)
+- [Source-code reviewer role](docs/role-reviewer.md)
+- [Issue reviewer role](docs/role-issue-reviewer.md)
+- [Issue creator responsibility](docs/role-issue-creator.md)
+
+Installation and invocation examples are in the
+[primer](docs/primer.md).
+
+Every review and remediation request, result, artifact, attempt
+configuration, process log, and terminal failure is persisted outside the
+worktree. Recoverable jobs continue with the same job ID through the
+[`resume` command](docs/cli.md#resume); terminal replacements can retain lineage
+through [`enqueue-local --supersedes`](docs/cli.md#enqueue-local). Initial
+clean-worktree development, worktree creation, leases, and remote pull-request
+operations remain subsequent increments. Issue-review feedback can be posted to
+GitHub or GitLab only through the explicit `post-issue-feedback --authorize`
+boundary.
+
+## Development
+
+Install the toolchain, synchronize the development dependencies, and run the
+standard gates:
+
+```shell
+mise install
+uv sync --group dev
+mise run format
+mise run lint
+mise run mypy
+mise run tests
+mise run build
+mise run verify-dist
+git diff --check
+```
+
+Continuous integration runs the same gates on every push and pull request,
+substituting `mise run format-check` for `mise run format` so a branch is
+verified rather than rewritten. Run `mise run format-check` locally to see what
+CI will see.
+
+Authenticated runtime checks are deliberately separate from the ordinary test
+suite. After installing the corresponding role skills, run
+`mise run test-live-claude` or `mise run test-live-codex`; see
+[Opt-in live runtime verification](docs/cli.md#opt-in-live-runtime-verification)
+for prerequisites, cost, isolation, and failure semantics.
+
+`mise run tests` distributes the suite across one worker per available CPU,
+which takes it from about a minute to about fifteen seconds. Parallel workers
+interleave their output, so use `mise run tests-serial` when reading a single
+failure: it runs everything in one verbose process. Both tasks run the same
+tests and must both pass.

py_agent_orchestra-0.1.1/pyproject.toml

@@ -0,0 +1,108 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "py-agent-orchestra"
+version = "0.1.1"
+description = "A lightweight local workflow orchestrator for development and review agents."
+readme = "README.md"
+requires-python = ">=3.14"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Alex Sokolsky" }]
+dependencies = ["pydantic>=2.12,<3"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Software Development :: Quality Assurance",
+    "Typing :: Typed",
+]
+
+[project.urls]
+Homepage = "https://github.com/asokolsky/agent-orchestra"
+Documentation = "https://github.com/asokolsky/agent-orchestra/tree/main/docs"
+Issues = "https://github.com/asokolsky/agent-orchestra/issues"
+Repository = "https://github.com/asokolsky/agent-orchestra"
+
+[project.scripts]
+agent-orchestra = "agent_orchestra.cli:main"
+agent-orchestra-codex-reviewer = "agent_orchestra.adapter.codex:main"
+agent-orchestra-claude-code-reviewer = "agent_orchestra.adapter.claude_code:main"
+agent-orchestra-codex-developer = "agent_orchestra.adapter.codex:developer_main"
+agent-orchestra-claude-code-developer = "agent_orchestra.adapter.claude_code:developer_main"
+
+[dependency-groups]
+# uv sync --group dev
+dev = [
+    "mypy>=1.16.1",
+    "pytest>=8.4",
+    "pytest-xdist>=3.6",
+    "ruff>=0.12.1",
+]
+
+[tool.uv]
+default-groups = ["dev"]
+
+[tool.setuptools]
+package-dir = { "" = "src" }
+packages = ["agent_orchestra", "agent_orchestra.adapter"]
+include-package-data = false
+
+[tool.setuptools.package-data]
+agent_orchestra = ["py.typed", "manifest/*.toml"]
+
+[tool.setuptools.data-files]
+"share/agent-orchestra/skills/agent-orchestra-developer" = [
+    "skills/agent-orchestra-developer/SKILL.md",
+    "skills/agent-orchestra-developer/SKILL-meta.md",
+]
+"share/agent-orchestra/skills/agent-orchestra-reviewer" = [
+    "skills/agent-orchestra-reviewer/SKILL.md",
+    "skills/agent-orchestra-reviewer/SKILL-meta.md",
+]
+
+[tool.pytest.ini_options]
+addopts = "-q"
+testpaths = ["tests"]
+norecursedirs = ["tests/data"]
+markers = [
+    "live_claude: opt-in tests that invoke an installed authenticated Claude CLI",
+    "live_codex: opt-in tests that invoke an installed authenticated Codex CLI",
+]
+
+[tool.ruff]
+line-length = 88
+extend-exclude = ["tests/data/live_runtime"]
+
+[tool.ruff.lint]
+select = ["ALL"]
+ignore = [
+    "A001","A002","ANN401","ARG001",
+    "B006","B011","BLE001",
+    "C901","COM812","CPY001",
+    "D100","D101","D102","D103","D104","D107","D200","D202","D203","D205","D212","D400","D401","D415",
+    "E501","EM102","ERA001",
+    "FBT001",
+    "G004",
+    "Q000","Q003",
+    "N801","N803","N806",
+    "PT009","PT015","PT027","PLR0915","PLR1711","PLR0912","PLR0913","PLR2004","PLW0603",
+    "RET505","RET507","RUF022",
+    "S101","S603","SIM114","SLF001",
+    "T201",
+    "TRY003","TRY300"
+]
+
+[tool.ruff.format]
+quote-style = "single"
+
+[tool.mypy]
+strict = true
+warn_return_any = true
+warn_unused_configs = true
+exclude = ["^tests/data/live_runtime/"]

py_agent_orchestra-0.1.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

py_agent_orchestra-0.1.1/skills/agent-orchestra-developer/SKILL-meta.md

@@ -0,0 +1,58 @@
+---
+title: "Agent Orchestra Developer Meta"
+purpose: "Meta documentation for the agent-orchestra-developer skill."
+audience:
+  - developers
+  - agent-authors
+tags:
+  - skill-meta
+  - agent-orchestra-developer
+authors:
+  - "asokolsky@gmail.com"
+created-at: "2026-09-02T14:31:12+0200"
+updated-at: "2026-09-08T09:15:00+0200"
+---
+
+# Agent Orchestra Developer Meta
+
+Meta documentation for the
+[agent-orchestra-developer skill](./SKILL.md).
+
+## Relationship To Existing Standards
+
+- The skill follows the Agent Skills specification for its directory and
+  `SKILL.md` frontmatter.
+- The same `SKILL.md` is portable to OpenAI Codex and Anthropic Claude Code;
+  neither runtime receives a divergent role contract.
+- Version and source metadata, dependency documentation, and this companion
+  file follow the conventions established by the DLI SOT skill-authoring
+  workflow.
+- Worktree safety and action authorization remain subject to the instructions
+  of the repo being changed and the agent runtime executing the skill.
+
+## Dependencies
+
+No external skills are required. The workflow uses the Git CLI already required
+by agent-orchestra.
+
+| Dependency | Source | Install |
+|---|---|---|
+| `git` | [Git](https://git-scm.com/) | `brew install git` |
+
+Git provides worktree status and diff evidence to the developer. If Git is
+unavailable or the assigned path is not a Git worktree, return `blocked` without
+editing files.
+
+## Departures And Rationale
+
+The SOT companion-document convention uses SOT-specific link syntax. This repo
+uses standard Markdown links because it is not rendered by the SOT documentation
+toolchain. Product-specific UI metadata is omitted because Anthropic has no
+counterpart to `agents/openai.yaml`, and a shared Agent Skills source prevents
+the two runtimes from drifting. No other departures are intended.
+
+## Update Cadence
+
+Review this skill whenever the developer request/result contract, CLI schema,
+workflow states, lifecycle authorization rules, or upstream Agent Skills
+specification changes. Otherwise, review it annually.