Code Cycle Toolkit

Take a work item from the issue tracker to a reviewed, verified pull request that is ready for a human to merge.

Start here · Quick start · Workflows · Skills · Configuration · Documentation index · 2.0 roadmap

---

Coding agents can write a change. Getting that change reviewed, fixed, re-reviewed and proven to work — with a record anyone can audit later — is the part that usually stays manual and inconsistent.

Code Cycle Toolkit (cc = Code Cycle) is a set of portable Agent Skills plus an optional Python runtime. The skills tell Claude Code, Codex, or OpenCode how to run each stage of that cycle the same way every time. The runtime routes stages to models and records what happened.

flowchart LR
    A([Work item<br/>GitHub · Plane · Jira]) -.-> R[Issue review, optional<br/>cc-issue-review]
    R -- READY --> B
    R -- NEEDS_REFINEMENT / BLOCKED --> H([Stop for a person])
    A --> B[Implement<br/>cc-implement-issue]
    B --> C[Initial review<br/>cc-initial-review]
    C -- APPROVED --> F([Ready for<br/>manual merge])
    C -- CHANGES_REQUESTED --> D[Resolve findings<br/>cc-resolve-comments]
    D --> E[Rereview<br/>cc-rereview]
    E -- CHANGES_REQUESTED --> D
    E -- APPROVED --> F

Loading

The toolkit stops at READY_FOR_MANUAL_MERGE. It never merges.

What it is built on

Principle	What it means in practice
Issue provider ≠ code host	Work items come from GitHub Issues, Plane, or Jira. Code and review live on GitHub or Bitbucket. Any pair works. → Providers
Host-portable	The same skills/ run in Claude Code, Codex, and OpenCode, on Linux, macOS, Windows, and WSL.
Manual merge boundary	No skill merges, force-pushes, or deletes remote refs. A person owns the merge.
Stable findings	Every review finding gets a REV-xxx ID with a machine-readable header that survives across review rounds. → Review lifecycle
Evidence over claims	A fix counts as verified only after it has been run. Skipped checks and unverified items are reported as such. → Verification
Your conventions win	AGENTS.md, CLAUDE.md, and CONTRIBUTING.md are read when present and override the defaults. None of them is required.
Measured, not guessed	The optional runtime records every stage in local telemetry, and cc-stats reports it. → Telemetry

Start here

Pick the row that matches what you want to do.

I want to…	Use	Changes code?
check an issue is ready before implementing it	cc-issue-review	—
implement an issue and open a pull request	cc-implement-issue	✅
review an existing pull request	cc-initial-review	—
fix the findings a review left	cc-resolve-comments	✅
re-review a pull request after new commits	cc-rereview	—
run the whole cycle from one prompt	cc-orchestrator	via its stages
run the whole cycle as supervised Orca workers	cc-orca-orchestrator	via its stages
have Claude implement and Codex review	cc-orchestrator in claude_codex mode	via its stages
run a recorded cycle from the command line	run_cycle.py	via its stages
close a cycle whose rereview ran outside the runtime	manual_rereview.py	publishes one PR comment
list or revoke stored sandbox permissions	consent_control.py	—
review a diff or branch without a pull request	cc-code-review	—
audit a change for security	cc-security-review	—
prove a change actually works	cc-verify	—
bring an unfamiliar project up locally	cc-run	—
check that provider access is configured	cc-provider-bootstrap	—
see how the cycle has been performing	cc-stats	—
see or change which model serves each role	cc-profile-config	writes .code-cycle.yml on confirmation

Not sure? Read Choosing a workflow.

Quick start

Note

This is the shortest path. Getting started covers each step in full, including Windows and repository-level installs.

1. Requirements. Git, Python 3, an agent host (Claude Code, Codex, or OpenCode), and authenticated tooling for your issue provider and code host. See Requirements for executor versions and Claude sandbox prerequisites. For GitHub, the provider tool is gh:

gh auth status

2. Install the skills and the runtime. One command downloads the latest release and installs the skills for every host, plus the runtime (routing and telemetry). Run it again later to update:

curl -fsSL https://raw.githubusercontent.com/datacas/code-cycle-toolkit/main/scripts/get.sh | sh

irm https://raw.githubusercontent.com/datacas/code-cycle-toolkit/main/scripts/get.ps1 | iex

npx skills add datacas/code-cycle-toolkit --all --global --copy installs the skills without the runtime, so cc-stats and recorded cycles won't work. See what the runtime adds and other install options.

Codex skills install to ~/.agents/skills/ only. If an earlier version also left them in ~/.codex/skills/, Codex lists each one twice; running the command again removes those copies.

3. Optional configuration. In the repository you want to work on, a .code-cycle.yml stores non-secret defaults. On the first run, cc-provider-bootstrap proposes this file, including review.trusted_authors set to your authenticated login, and writes it only if you confirm. You can skip this step, or write it yourself:

code_cycle:
  issue_provider: github
  code_host: github
  repository:
    selector: owner/repository
    default_branch: main
  review:
    trusted_authors: [your-github-login]

4. Run it. Open your agent in that repository and ask:

Use cc-orchestrator for issue 123. Stop at READY_FOR_MANUAL_MERGE.

5. What happens. The orchestrator checks provider access. Unless the work is declared trivial and not security-sensitive, or you pass issue_review=off, it first checks read-only that the issue is ready to implement, and stops before any code work when it is not. It then implements the issue on a branch, runs the tests, and opens a pull request. It reviews that pull request and publishes one consolidated comment with REV-xxx findings. It fixes valid findings and re-reviews, up to 6 rounds. It stops when the reviewed head is approved, checks pass, and no blocking finding remains.

6. What you get. An open pull request with a review trail in its comments, and a final status:

Status	Meaning	Your next step
READY_FOR_MANUAL_MERGE	Approved at the current head, checks passed	Review and merge it yourself
HUMAN_INTERVENTION	The issue needs refinement or its readiness was not confirmed; or the iteration limit was hit, or no progress between rounds	Refine the issue with the proposed edits, or read the last review, and decide
BLOCKED	Missing access, information, or an external condition, including one the issue review found	Fix what the summary names and rerun
FAILED	Unexpected technical failure	Read the reported cause

Ways to use it

Mode	You drive…	Best for	Needs
Single skills	each stage by hand	one review, one fix, one audit	the skill
Manual cycle	the four cycle skills in order	full control between stages	the cycle skills
cc-orchestrator	one prompt	the whole cycle in the current agent	nothing extra
Claude + Codex	one prompt in Claude Code	Claude writes, Codex reviews	codex-plugin-cc, Codex
cc-orca-orchestrator	one prompt	supervised workers, paired-review calibration	Orca
run_cycle.py	a shell command	recorded, routed cycles across executors	runtime, Codex and/or Claude CLIs

Read-only roles can use Codex, whose sandbox enforces read-only, or Claude, which reviews in a disposable clone where writes are detected but not prevented. See workspace policy for what that does and does not guarantee.

Skills

Fifteen skills in two layers. Cycle skills own the workflow: the change request, the finding IDs, the published comments, and the merge boundary. Supporting skills are focused passes that cycle skills delegate to. Each one also works on its own.

Skill	Layer	Purpose	Changes code?
cc-issue-review	cycle	Decide, read-only, whether a work item is ready to implement	—
cc-implement-issue	cycle	Implement a work item, verify it, open a pull request	✅
cc-initial-review	cycle	Review the full pull-request diff, publish findings	—
cc-resolve-comments	cycle	Triage findings, fix valid ones, verify, push	✅
cc-rereview	cycle	Re-review the accumulated diff after changes	—
cc-orchestrator	cycle	Run the whole cycle, sequentially or with host delegation	via stages
cc-orca-orchestrator	cycle	Run the whole cycle through Orca Runs, Tasks, and Workers	via stages
cc-pr-review	supporting	Review criteria for a change request	—
cc-code-review	supporting	Review criteria for a diff, without the PR framing	—
cc-security-review	supporting	Security audit scoped to the change	—
cc-verify	supporting	Execution-backed verification	—
cc-run	supporting	Start a project's services and confirm they respond	—
cc-provider-bootstrap	supporting	Resolve and health-check the provider pair	—
cc-stats	supporting	Report local telemetry for this repository	—
cc-profile-config	supporting	Show, choose, and write routing profiles	—
cc-host-permissions	supporting	Explain stage permissions; apply or revert the opt-in global set	—

→ Inputs, statuses, and examples for each: Skills reference

Everything you can configure

Configuration is optional. Invocation parameters override .code-cycle.yml, which overrides what can be inferred safely.

Area	Where	Reference
Issue provider, code host, work-item scope	issue_provider, code_host, issue.*	Configuration → Providers
Repository selector and default branch	repository.selector, repository.default_branch	Configuration → Providers
Provider health-check cache	verification.cache_ttl	Configuration → Provider health
Models, executors, effort, fallbacks	profiles.<profile>.primary / .fallback	Routing → Profiles
Routing strategy	routing.strategy (fixed | measured)	Routing → Strategies
Pre-implementation issue review	issue_review.mode (auto | off), issue_review=, --issue-review	Review lifecycle → Issue review
Jev shadow suggestions	routing.jev.*, TYPESAFE_API_KEY	Routing → Jev
Who can advance findings	review.trusted_authors	Review lifecycle → Trust
When the security audit always runs	security_review.always_when.*	Configuration → Security
Orchestration mode	orchestration.mode, orchestration_mode=	Workflows → cc-orchestrator
Reviewer calibration candidates	calibration.profiles.*	Routing → Calibration
Commands a stage may run to verify	allowed_commands.test, allowed_commands.verify	Host permissions
Output language	lang= in the prompt	Configuration → Language
Iterations, agents, paired review	max_iterations=, implementer=, reviewer=, paired_review=	Configuration → Invocation parameters
Telemetry location	CODE_CYCLE_HOME	Configuration → Environment
Installer and CLI flags	install.sh, run_cycle.py, stats.py	Configuration → Command-line flags

→ Full key-by-key reference with defaults: Configuration

Optional workspace tools

The skills work better when the host offers semantic code navigation (Serena), persistent memory (AgentMemory), a repository knowledge graph (Graphify), output compaction (RTK), large-output processing (context-mode), or current library documentation (Context7). These tools are recommended, external, and optional: no installer or npx skills installs them, and their absence is never an error. The skills state capability preferences without naming products, and each tool's own host integration does the routing. → Optional workspace tools

What it does not do

• Merge. The final merge is always a human decision.
• Replace your tools. It isn't a tracker, CI service, code host, or deployment system, and it ships no API clients or credentials. It uses the gh CLI, connectors, or MCP servers you already authenticated.
• Invent verification. It runs the tests and checks your project defines. When it can't run something, it says so and why.
• Treat silence as success. Skipped, pending, or missing checks are reported as exactly that.
• Pick models from statistics. Routing follows declared rules. Telemetry records outcomes, and nothing adapts automatically. Jev only ever runs in shadow mode.
• Bundle external components. Orca (for cc-orca-orchestrator) and codex-plugin-cc (for Claude + Codex mode) are installed and authenticated separately. See the adapter contract.
• Enforce publication everywhere. On a GitHub cycle, each native Claude stage runs under its closed command table and a hook that denies anything else; Codex stages are confined by their sandbox profile, which filters files and network, not commands. Elsewhere, and on Orca workers, what a stage may publish is a rule in its prompt. Use separate credentials when you need a hard guarantee. → Host permissions · Routing → Publication

Documentation

Guide	Covers
Getting started	Requirements, installation, authentication, first run
Workflows	Every way to run the toolkit, and when to choose each
Skills reference	All sixteen skills: inputs, outputs, statuses
Review lifecycle	REV-xxx findings, severities, dispositions, run lines
Verification	Evidence rules, stop conditions, CI reporting
Routing and models	Profiles, executors, fallbacks, strategies, Jev, calibration
Configuration	Every .code-cycle.yml key, parameter, flag, and variable
Providers	Issue provider and code host contract
Telemetry and cc-stats	What is recorded, where, and how to read it
Optional workspace tools	Recommended host tools, how stages use them, privacy, pitfalls
Role workspace policy	What each stage may write
Instrumentation internals	Design reference for the record, routing, and telemetry

Contributing

Run the validator and tests before opening a pull request:

python3 scripts/validate-package.py
python3 -m unittest discover -s tests

See CONTRIBUTING.md for the skill-authoring rules, including how the duplicated sections are kept in sync. Security reports go through SECURITY.md. Changes are recorded in CHANGELOG.md. Released under the MIT License.