repo-orchestration — Claude Code skill: what it does, how to install
repo-orchestration — a skill for Claude Code that drafts to-be designs and implementation task plans. Activates when you ask to design a target state or decompose a technical goal.
Apache-2.0 431 installs ★ 8 updated 2026-07-24
npx skills add objectivlabs/reposkillopt --skill repo-orchestration -a claude-codeWhat repo-orchestration does
The skill generates architecture decision records (ADRs), a target-state design document, and a machine-readable task ledger. Every ADR evaluates two or more distinct alternatives with trade-offs. The design document traces proposed modifications directly to existing repository components using exact file and line references.
Running this skill requires existing as-is artifacts (Architecture View and Change-Impact Analysis) alongside a stated goal. It stores the generated plan in .reposkillopt/plan/task-ledger.md as an acyclic dependency graph with strict topological ordering.
Artifacts must pass the check_adr and check_task_ledger deterministic validation gates. The skill solely produces plan artifacts and stops; it does not write application code or run implementations.
What it helps with
- formalize target architecture decisions in traceable ADRs
- create a design document mapped directly to current repository code
- split large technical goals into standalone acceptance-tested tasks
- build an acyclic task dependency graph with topological ordering
Example prompts for the agent
- Design the target state for migrating our database to PostgreSQL
- Produce an implementation plan and task ledger for the auth refactor
- Decompose the caching integration goal into independent tasks with ADRs
How to install repo-orchestration
1Skills CLI (Vercel)
npx skills add objectivlabs/reposkillopt --skill repo-orchestration -a claude-code2Manually: put the files in place
~/.claude/skills/repo-orchestration/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/repo-orchestration/
1Skills CLI (Vercel)
npx skills add objectivlabs/reposkillopt --skill repo-orchestration -a codex2Manually: put the files in place
.agents/skills/repo-orchestration/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add objectivlabs/reposkillopt --skill repo-orchestration -a cursor2Manually: put the files in place
.cursor/skills/repo-orchestration/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install objectivlabs/reposkillopt skills/repo-orchestration2Manually: put the files in place
.github/skills/repo-orchestration/SKILL.md1Skills CLI (Vercel)
npx skills add objectivlabs/reposkillopt --skill repo-orchestration -a gemini-cli2Platform CLI
gemini skills install https://github.com/objectivlabs/reposkillopt --path skills/repo-orchestrationManually: put the files in place
.devin/skills/repo-orchestration/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add objectivlabs/reposkillopt --skill repo-orchestration -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about repo-orchestration
How to install repo-orchestration in Claude Code?
Run npx skills add objectivlabs/reposkillopt --skill repo-orchestration -a claude-code in your terminal.
What does repo-orchestration do?
It creates grounded ADRs, a design document linked to current code, and a structured task ledger with topological ordering.
What is required to run repo-orchestration?
It requires as-is architecture artifacts (Architecture View and Change-Impact Analysis) plus a defined goal before execution.
Source text
SKILL.md · Apache-2.0
--- name: repo-orchestration description: Evidence-grounded to-be design (ADRs + design doc) and an implementation orchestration plan (a machine-readable task ledger). Activates when the user asks to design a target state, plan the work, or produce a task plan for a goal. version: 0.1.0 --- # RepoSkillOpt — To-Be Design & Implementation Orchestration (Canonical Skill) ## Purpose This skill consumes the **as-is artifacts** (Architecture View + Change-Impact Analysis) and a stated **goal**, and produces (a) a reviewable target-state design — **ADRs** + a concise **Design Doc** grounded in the as-is evidence — and (b) an **implementation orchestration plan**: a machine-readable **Task Ledger** decomposed into small, independent, individually acceptance-tested sub-tasks with declared dependencies and a topological order. The plan is an **artifact, not an executor** — any orchestrator can drive it; this skill never executes the implementation. Vendor-neutral: no dependency on any particular coding-agent runtime. ## Trigger Conditions Activate when the user asks to **design a target state / to-be**, **plan the work / decompose into tasks**, or **produce an implementation plan for goal X** — or recognizable equivalents. Do **not** activate for unrelated requests, and do **not** execute the resulting plan. ## Prerequisite The as-is artifacts (Architecture View, Change-Impact Analysis) and a stated goal. If the as-is is missing, point the user to the as-is architecture skill first; do not design against an ungrounded picture of the current system. ## Operating Principles - **Ground the design in the as-is.** Every design claim is traceable to as-is evidence (`file:line` via the cited as-is artifacts). Mark inference as `**[inference]**`, unknowns as `**[unknown]**`. - **Decide explicitly.** Contested choices become ADRs that weigh ≥2 options — no silent defaults. - **Plan, don't execute.** The Task Ledger is a portable artifact; this skill writes it and stops. - **Independent, acceptance-tested tasks.** Each sub-task is small enough to be executed and reviewer-verified on its own, with declared dependencies; if a task isn't independently acceptance-testable, split it. - **Repository facts stay repository-scoped.** Only candidate-for-generic patterns enter convergence. ## Workflow (a) **Read the as-is artifacts + the goal.** Identify constraints and the affected blast-radius. (b) **ADRs** (`.reposkillopt/decisions/ADR-NNN-<slug>.md`, per `templates/adr.md`): one decision each — Context, **Options considered (≥2, pros/cons)**, Decision, Consequences. A goal that conflicts with an as-is constraint is recorded as an ADR trade-off, not papered over. (c) **Design Doc** (`.reposkillopt/design/design-doc.md`, per `templates/design-doc.md`): Goal, Target-state overview, **How it maps onto the as-is** (each change tied to the current component/flow it touches, cited), Risks & trade-offs (link the ADRs), Out of scope. (d) **Task Ledger** (`.reposkillopt/plan/task-ledger.md`, per `templates/task-ledger.md`): the work as a table — `id | goal | acceptance | depends_on` — each task independent + individually acceptance-tested, dependencies declared, the dependency graph **acyclic**, and the front-matter `topological_order` listing every id with each dependency before its dependent. (e) **Deterministic gate.** The artifacts MUST pass the deterministic checks (`check_adr`, `check_task_ledger`): ≥2 options per ADR; every task has a goal + acceptance; deps exist; graph acyclic; topological order valid. ## Output Discipline Same R10 labels and citation forms as the as-is skill; design claims cite the as-is artifacts they rest on. Trivial recitations need no label. ## Human Feedback Loop Corrections to a decision or to the task decomposition are recorded as **Feedback Items** (`templates/human-feedback.md`) under `.reposkillopt/feedback/` and applied to the artifact in place. ## Skill Convergence Loop Recurrent **candidate-for-generic** feedback (≥3 related items) becomes a **Skill Edit Proposal** (`templates/skill-edit-proposal.md`), accepted **only** after the validation gate (`rubric/validation-gate.md`): regenerate artifacts for a disjoint held-out set with **no per-dimension rubric regression** (see `rubric/tobe-orchestration-rubric.md`) and deterministic checks still passing. Nothing is silently promoted; acceptance bumps the version + CHANGELOG and is mirrored into the four adapters.
© objectivlabs · Apache-2.0 · objectivlabs/reposkillopt