coding-orchestration
Orchestrate software-engineering work inside Git repositories with the user's global Codex agents. Use for coding analysis, implementation, debugging, refactors, reviews, tests, UI or design work, security checks, performance work, and releases. Apply to every non-trivial coding task in a Git repo; keep trivial one-step work on the parent agent. Do not use for non-code conversations or folders that are not software repositories.
- License 许可
- MIT
- 最近更新
- 2026-11-14
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- coding-orchestration
- description
- Orchestrate software-engineering work inside Git repositories with the user's global Codex agents. Use for coding analysis, implementation, debugging, refactors, reviews, tests, UI or design work, security checks, performance work, and releases. Apply to every non-trivial coding task in a Git repo; keep trivial one-step work on the parent agent. Do not use for non-code conversations or folders that are not software repositories.
02 资源文件 2
- 参考文档agents/openai.yaml216 B
- 脚本scripts/validate_agents.py4.9 KB
03 SKILL.md 正文
Coding Orchestration
Keep the parent agent responsible for integration. A tiny change stays on the parent unless delegation is demonstrably faster. Its target is functional evidence within five minutes; ten minutes is an exceptional ceiling that requires a written reason. If it crosses ten minutes, stop and audit the process instead of adding gates.
Decide whether to delegate
- Confirm the task is software work inside a Git repository.
- Read applicable
AGENTS.mdfiles and required repo skills before delegating. - Keep the task on the parent when it is a trivial read, one-step command, tiny localized edit, or quick answer.
- Delegate when at least one condition holds:
- two or more independent discovery or verification lanes exist;
- the task crosses packages, apps, services, or specialties;
- noisy searches, logs, tests, or browser evidence would pollute the parent context;
- an independent correctness, security, performance, or release review materially reduces risk.
- Keep one writer and no ticket worktrees by default. When the user explicitly
invokes
work-multiple, let that separate skill own lane planning, worktrees, integration, and measurement.
Subagents cost additional tokens. Never spawn agents merely to restate the prompt or duplicate the same search.
Lock the terminal slice
Before delegating or editing, state the smallest executable slice that advances the requested end state:
- a binary done condition;
- exact ownership and scope;
- the focused checks needed during work;
- the single final gate needed before handoff;
- any preview, production, merge, or human-review stop boundary.
Freeze adjacent improvements. If work reaches roughly twice its expected duration or token budget, waiting dominates the run, or a lane produces no useful evidence, stop expanding the slice and audit the process before continuing.
Route by role
Use the global custom agent from ${CODEX_HOME:-$HOME/.codex}/agents whose name matches the job:
| Agent | Assign when |
|---|---|
code_mapper |
Locate code paths, ownership, repo rules, tests, and commands. |
docs_researcher |
Verify version-sensitive framework or API behavior from primary sources. |
qa_planner |
Translate changed surfaces into the smallest sufficient verification matrix. |
test_runner |
Run focused checks and summarize failures without editing product code. |
mechanical_worker |
Execute large, explicit, low-ambiguity edits or migrations. |
fast_implementer |
Execute exact bounded packets with Luna High for rapid, stable writes. |
implementer |
Make a scoped general code change after ownership is clear. |
backend_specialist |
Own backend, schema, auth, migration, or data-contract implementation. |
browser_qa |
Reproduce and verify user-visible behavior with browser tooling. |
performance_auditor |
Inspect rendering, bundle, query, or runtime performance risks. |
ui_designer |
Design or implement user-facing UI where visual judgment is central. |
visual_reviewer |
Independently inspect design quality and rendered UI evidence. |
architecture_planner |
Resolve ambiguous, cross-cutting, or high-risk technical design. |
reviewer |
Independently review correctness, regressions, and missing tests. |
security_reviewer |
Review trust boundaries, auth, permissions, secrets, and data exposure. |
release_manager |
Evaluate and execute an authorized repo release path and smoke checks. |
The custom agent TOML files are the single source of truth for model and reasoning settings. Do not copy model maps into repositories.
Execute in bounded waves
Choose only the lanes the task needs:
- Discovery: run
code_mapper,docs_researcher, orqa_plannerin parallel when their scopes are independent. - Decision: have the parent integrate evidence; use
architecture_planneronly when judgment remains genuinely hard. - Implementation: default to one writer. Use Luna High
fast_implementerfirst for exact bounded packets, Sol Mediumimplementerorbackend_specialistwhen judgment is required, or Sol Extra Highui_designerfor visual craft, with explicit file or package ownership. - Verification: run focused tests and browser checks independently when useful.
- Review: add only the risk-specific reviewer needed, then let the parent integrate findings and finish repo gates.
The parent owns conflicts, final integration, and the requested end state.
Reuse a suitable existing agent for follow-up work instead of spawning a fresh copy. Re-run only a failed or materially changed lane.
Keep prompts lean
When spawning a named custom agent, set agent_type to its exact name and set fork_turns="none". Full-history forks intentionally inherit the parent role, model, and reasoning effort, so they must not be used for Luna or Terra delegation. Include the required task-local context in the delegated prompt instead.
Every delegated prompt must include:
- one concrete objective;
- exact scope or ownership boundaries;
- expected absolute Git worktree path and branch;
- relevant repo instructions or paths to read;
- whether edits are allowed;
- the evidence or output format to return;
- conditions that require escalation to the parent.
Pass task-local context, not the full conversation. Ask for concise summaries with file references instead of raw logs.
Escalate by evidence
Start with the cheapest agent adequate for the bounded job. Escalate only when its output is incomplete, contradictory, repeatedly failing, or reaches a high-risk decision outside its mandate.
Use this progression and include the actual route in the final evidence:
- Luna High for exact bounded implementation packets, focused test execution, and explicit mechanical edits; Luna Extra High for discovery, docs, and QA planning.
- Terra Max only for browser QA, where its computer-use performance justifies the middle tier.
- Sol Medium only for implementation or review that needs that judgment; do
not route precise bounded implementation to Sol when
fast_implementerapplies. - Sol High for independent visual review.
- Sol Extra High for architecture, security, and UI design. Never lower these protected judgment roles.
Judge the returned work, not the price tier. Re-run only the failed lane; do not restart the whole workflow.
Fast model labels are candidates, not routing proof. Use only model IDs exposed by the installed Codex catalog. fast_implementer uses Luna High as the incident-driven stable route after Spark caused repeated ownership and instruction-following failures. Keep the mapping provisional until same-packet measurements establish wall time, focused-check pass rate, correction cost, and service-tier cost.
Minimize orchestration overhead
- Do useful parent work while agents, tests, or CI run; do not actively poll.
- Store the run identifier and check once when the result can unblock a decision. Wait only when it is the last blocker.
- Run the smallest check that proves the acceptance criterion. A full suite is forbidden by default and may run only when the user explicitly requests it for that run. Do not infer that authorization from change size, ticket count, a release label, or a generic "verify everything" convention.
- Run UI acceptance only when UI changed and the observable risk justifies it. A label, copy, icon, or obvious style-only change without behavior risk skips browser QA. Interaction, navigation, mutation, responsive behavior, meaningful regression, or a critical flow gets one direct acceptance flow.
- Report what every cited check actually proved. Never present total tests, destinations, routes, or surfaces as quality evidence without mapping them to acceptance criteria.
- Inspect the real command, log, route, or runtime behavior behind a green label. A named check is not evidence that it exercised the intended surface.
- Prefer one coherent implementation wave and one integrated review over repeated global reviews after every small change.
- Record each delegated lane's role, agent, harness, resolved model, reasoning,
session id, event id, and runtime metadata source. Copying the selected model
from the plan is not evidence. Missing, self-reported, or
inheritmodel evidence is unresolved.
Preserve safety and repo policy
- Delegation never expands authorization.
- A writer must verify the expected absolute worktree, Git root, and branch before its first read or edit, and must reject patch targets outside that root.
- If a writer reports or exhibits a path mismatch, interrupt it before moving, restoring, or integrating any diff.
- Apply the repo's branch, test, review, deploy, and approval policy.
- Keep spawned depth at one; workers must not create further workers.
- Stop or close completed agents so thread capacity is available.
- Do not treat generated plans as proof; verify the real repository and runtime state.
- Route design decisions and UI craft to
ui_designerat Sol Extra High. Usevisual_reviewerat Sol High for independent rendered-quality review; escalate unresolved design judgment back toui_designer. - For Codex roster changes, run
python3 scripts/validate_agents.pyfrom this skill directory. - For cross-harness workflow changes, run
python3 ~/.agents/scripts/validate-development-system.py --repos-root <projects-directory>.
04 同仓库更多 Skills
working-backwards
Define a software feature through PRFAQ and staged documents when the user requests working backwards before coding.
flow-implement
Implement a requested software change through verification, corrections, and its authorized delivery endpoint.
development-steward
Run the scheduled, read-only weekly maintenance review for the six explicitly opted-in repositories and prepare one concise private report for Check-in.
grill-with-docs
Run one recoverable interview for functional, visual, or mixed software grills; reuse equivalent answers and offer the shared HTML questionnaire.
global-agent-guardrails
Install, audit, test, or update the Development System's global destructive-command guard for Codex, Claude Code and T3 Code. Use when configuring agent safety hooks or investigating whether dangerous shell operations are blocked.
impeccable
Design or refine frontend UI using project context and a focused design playbook; also handles visual critique and polish.