mcpField
R
repo-orchestration

repo-orchestration

github.com/objectivlabsDevelopment9237 installsUpdated 19w ago
Repository

About repo-orchestration

A skill for planning a target state and implementation from existing architecture artifacts. It produces evidence-grounded ADRs, a design document, and independently testable tasks, but does not execute the plan.

Key features

  1. 01Design target state from current-state evidence
  2. 02ADRs documenting trade-offs and decisions
  3. 03Design document generation
  4. 04Breakdown into independently testable tasks
  5. 05Dependency and topological-order checks

Use cases

  1. 01Planning a target system architecture
  2. 02Recording contested design choices
  3. 03Decomposing implementation goals into tasks
  4. 04Checking dependencies in a task plan

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/objectivlabs/reposkillopt --skill repo-orchestration

After installing, type/repo-orchestrationin Claude Code to confirm it loaded.

Bundled filesCHANGELOG.md

Details

From the project README

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.

Comments

Markdown supported