Skip to main content
skill CX Codex

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

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add objectivlabs/reposkillopt --skill repo-orchestration -a claude-code
Open on GitHub

What 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-code

2Manually: put the files in place

~/.claude/skills/repo-orchestration/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/repo-orchestration/

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

Similar skills

All skills for Agent setup: memory, context, orchestration →

From the same set3

Project sponsors

Companies that keep this analytics open