repo-control-suite-kit 0.4.0

Agent-first repository control-plane suite

Repo Control Suite Kit

A control plane for repositories that take AI-assisted change seriously.

---

Most AI coding setups optimize for generation speed: drop a guidance file in your repo, point an agent at it, ship. That works fine — until someone asks "what changed, why, and can we roll it back?"

rctl is a small CLI that installs a durable control plane into any repository. It gives agents and humans a shared place to find plans, evidence, validation results, and rollback notes — so the next session doesn't start from zero.

The idea

AI agents are good at writing code. They're terrible at remembering what they did, why they did it, and whether it actually worked. Your chat history shouldn't be the source of truth for that — your repository should.

rctl treats the repo as the single source of truth for the entire change lifecycle:

Plan → Implement → Verify → Score → Archive

One canonical set of skills and guidance lives under rctl/. It gets projected into whatever agent surfaces you use — Claude Code, Cursor, Windsurf, Codex — without duplication, without drift.

Features

• 8 CLI commands covering the full lifecycle: init, update, validate, score, enforce, status, next, gc
• 16 reusable skills — structured agent workflows with defined triggers, steps, success criteria, and failure patterns (not prompt snippets)
• 4 agent adapters — one canonical source, projected to Codex, Claude Code, Cursor, and Windsurf native surfaces
• 5-layer validation — structure, discovery, operational, freshness, and enforcement checks
• Honest readiness scoring — because "files exist" and "repo is actually ready" are different things
• Durable change records — plans, execution status, evidence, and rollback notes that survive across sessions
• Conservative updates — hash-tracked manifests, explicit conflict files, no silent overwrites
• Profile-based governance — scale controls from minimal to full without rewriting anything

Installation

Prerequisites

• Python 3.10 or later

Install

pip install repo-control-suite-kit

For development:

git clone https://github.com/liqiongyu/repo-control-suite-kit.git
cd repo-control-suite-kit
pip install -e .

Quick start

Three commands to go from nothing to a validated control plane:

# Install the control plane with your preferred agents
rctl init . --agents claude,cursor --profile core

# Verify that everything is wired correctly
rctl validate . --smoke

# See how ready the repo actually is (not just "did files get created")
rctl score .

Your repo now has a rctl/ directory with skills, schemas, zone configs, and a command registry — all projected into the agent surfaces you selected.

To refresh after changing skills, profiles, or adapter mappings:

rctl update .

Commands

Command	What it does
rctl init <repo>	Install or refresh the control plane
rctl update <repo>	Refresh managed files without silent clobbering
rctl validate <repo>	Run 5-layer structure, discovery, and enforcement checks
rctl score <repo>	Compute readiness with honest gating notes
rctl enforce <repo>	Run zone-level enforceable constraints
rctl status <repo>	Show active change lifecycle or list all active changes
rctl next <repo> <id>	Suggest — and optionally apply — the next lifecycle step
rctl gc <repo>	Detect and fix repository entropy: stale changes, orphaned artifacts

All commands support --format json|text|markdown and --write-artifact for CI integration.

Profiles

Not every repo needs full governance on day one. Pick a profile that matches where you are:

Profile	Skills	When to use
minimal	6	Routing, active-change flow, and verification. Nothing more.
core	12	The everyday profile. Adds context mapping, drift scanning, permission review, archival, scoring.
full	16	The works. Adds grading, governance hardening, cleanup, and incident-to-learning loops.
custom	—	Pick exactly which skills to install via --skills.

# Start small
rctl init . --profile minimal --agents claude

# Graduate later
rctl init . --profile full --agents claude,cursor,windsurf,codex --force

Skills

Skills are the core of rctl. Each one is a structured agent workflow — not a prompt snippet. They define when to trigger, what steps to follow, what success looks like, and where things commonly go wrong.

Minimal profile — 6 skills

Skill	Purpose
rctl-onboard-repo	Bootstrap or refresh the control plane
rctl-plan-change	Create a durable change plan with risks and rollback notes
rctl-implement-change	Execute a change while keeping status and evidence current
rctl-verify-change	Validate against zone commands and acceptance criteria
rctl-sync-memory	Update durable repo knowledge after meaningful work
rctl-validate-repo	Check that rctl structure and discovery wiring are intact

Core profile adds 6 more

Skill	Purpose
rctl-map-context	Map zones, owners, and source-of-truth links
rctl-archive-change	Archive completed changes without losing lessons
rctl-permission-review	Review trust boundaries before risky actions
rctl-scan-drift	Detect divergence between code, docs, and plans
rctl-create-skill	Create or improve reusable skills
rctl-score-repo	Score readiness honestly using structure + evidence

Full profile adds 4 more

Skill	Purpose
rctl-cleanup-pr	Prune stale residue after review cycles
rctl-grade-trace	Grade a workflow trace for compliance and usefulness
rctl-govern-zone	Tighten zone invariants, owners, and permissions
rctl-incident-to-learning	Convert failures into durable repo lessons

How it works

graph TB
    subgraph "Canonical source — rctl/"
        CP["control-plane/"]
        SK["skills-src/"]
        REG["registry/"]
        SCH["schemas/"]
    end

    SK -->|"project"| CODEX[".agents/skills/\n(Codex)"]
    SK -->|"project"| CLAUDE[".claude/skills/ + commands/\n(Claude Code)"]
    SK -->|"project"| CURSOR[".cursor/skills/ + rules/\n(Cursor)"]
    SK -->|"project"| WIND[".windsurf/skills/ + workflows/\n(Windsurf)"]

    subgraph "Change lifecycle"
        direction LR
        PLAN["Plan"] --> IMPL["Implement"]
        IMPL --> VERIFY["Verify"]
        VERIFY --> SCORE["Score"]
        SCORE --> ARCHIVE["Archive"]
    end

One truth. Projected everywhere agents look. No drift.

Generated layout

After rctl init, your repo gets this structure:

repo/
  AGENTS.md                       # Root discovery — agents start here
  CLAUDE.md                       # Claude Code routing (when selected)
  rctl/
    control-plane/                # Machine-readable manifests
    changes/
      active/                     # Live change plans, status, evidence
      archive/                    # Completed change records
    docs/                         # Decisions, runbooks, quality artifacts
    registry/                     # Command, skill, profile, agent mappings
    skills-src/                   # Canonical skill definitions
    schemas/                      # JSON Schemas for validation
    bridges/                      # Integration protocols (e.g., OpenSpec)
  .agents/skills/                 # → Codex
  .claude/skills/                 # → Claude Code
  .claude/commands/               # → Claude Code slash commands
  .cursor/rules/                  # → Cursor
  .cursor/skills/                 # → Cursor
  .windsurf/rules/                # → Windsurf
  .windsurf/skills/               # → Windsurf
  .windsurf/workflows/            # → Windsurf

Design principles

These are opinions, not accidents:

1. Keep operating truth under rctl/. Business code and control-plane metadata don't belong in the same directories.
2. Root files are discovery layers, not documentation. AGENTS.md and CLAUDE.md point agents inward — the detail lives under rctl/.
3. Structural completeness ≠ operational readiness. Generating files is easy. Having plans, evidence, and passing checks is hard. rctl measures both, separately.
4. Conservative updates, explicit conflicts. rctl update tracks file hashes. If you edited a managed file, it writes a .rctl.new conflict file instead of overwriting your work.
5. One canonical source, many projections. Skills and commands are authored once under rctl/skills-src/ and projected to each agent's native surface.

Development

# Compile check
python3 -m compileall src

# Run tests
PYTHONPATH=src python3 -m unittest discover -s tests -v

# Smoke-check the control plane
PYTHONPATH=src python3 -m rctl validate . --smoke --format text

# Score this repo's own readiness
PYTHONPATH=src python3 -m rctl score . --format markdown

CI runs these across Python 3.10–3.13 on every push and PR.

When making non-trivial changes, create an active change record under rctl/changes/active/<change-id>/.

Working with OpenSpec

rctl and OpenSpec can coexist in the same repository. OpenSpec handles proposals, specs, and design intent; rctl handles execution plans, evidence, validation, and governance. The two coordinate through cross-links rather than shared directories — a formal bridge protocol defines the responsibility boundary, linking rules, and conflict resolution.

[!TIP] If your repo already uses OpenSpec, just run rctl init as usual. Validation will detect the openspec/ directory and verify the bridge protocol is in place.

Status

Alpha (v0.4.0). Actively evolving. The CLI installs, validates, scores, enforces, and projects assets to all four agent surfaces. Change lifecycle tracking, garbage collection, and zone enforcement are functional. Areas with room to grow: merge behavior, benchmark loops, deeper discovery checks.

Community

• Contributing
• Code of Conduct
• Security Policy
• Support
• Changelog

License

Apache License 2.0 — see LICENSE and NOTICE.