Metadata-Version: 2.4
Name: repo-control-suite-kit
Version: 0.4.0
Summary: Agent-first repository control-plane suite
Author: Repo Control Suite Kit contributors
License-Expression: Apache-2.0
Keywords: ai,agents,developer-tools,repository,cli,automation
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: Software Development :: Documentation
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: PyYAML>=6.0
Requires-Dist: jsonschema>=4.0
Dynamic: license-file

# Repo Control Suite Kit

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

[![CI](https://img.shields.io/github/actions/workflow/status/liqiongyu/repo-control-suite-kit/ci.yml?branch=main)](https://github.com/liqiongyu/repo-control-suite-kit/actions/workflows/ci.yml)
[![Python](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org)
[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
[![Status](https://img.shields.io/badge/status-alpha%20v0.4.0-orange)]()

---

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

```bash
pip install repo-control-suite-kit
```

For development:

```bash
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:

```bash
# 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:

```bash
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`. |

```bash
# 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.

<details>
<summary><strong>Minimal profile — 6 skills</strong></summary>

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

</details>

<details>
<summary><strong>Core profile adds 6 more</strong></summary>

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

</details>

<details>
<summary><strong>Full profile adds 4 more</strong></summary>

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

</details>

## How it works

```mermaid
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:

```text
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

```bash
# 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](https://github.com/nicholasgriffintn/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](rctl/bridges/openspec.md) 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](CONTRIBUTING.md)
- [Code of Conduct](CODE_OF_CONDUCT.md)
- [Security Policy](SECURITY.md)
- [Support](SUPPORT.md)
- [Changelog](CHANGELOG.md)

## License

Apache License 2.0 — see [LICENSE](LICENSE) and [NOTICE](NOTICE).
