CodeStable offers lightweight skill contracts for serious software. It does not orchestrate agent teams and does not create a second documentation system. Models act within boundaries, prove results, and return knowledge to existing homes.

30-Second Model

User intent
   ↓
cs: execute directly / discuss in this session / advise
   ↓
feat · issue · refactor · epic
   ↓
proportionate verification + necessary review / owner gates
   ↓ code results + the project's canonical knowledge

For team workflows, combine them by responsibility:

• Stable coding: use CodeStable to make task boundaries, assurance, evidence, and project memory explicit.
• Team context sharing: use Threadshare to turn Codex, Claude Code, and other agent conversations into read-only links for teammates and later agents.
• Multi-agent coding collaboration: use cs-agent to create, invoke, and manage Codex, Claude, and other subagents during implementation, including independent review.

The three complement one another: CodeStable does not publish conversations or orchestrate agents, while Threadshare and cs-agent do not replace CodeStable's engineering contracts.

You only need to tell cs what you want to accomplish:

• When the request is clear: it starts directly and delivers the result with enough verification.
• When it finds a concrete risk: it adds only the confirmation, tests, or review needed for that risk; it does not enable the whole workflow.
• When you want to discuss first: it aligns goals, terms, and boundaries with you. It will not change code without execution authorization.
• When terminology could cause misunderstanding: it aligns the meaning as the shared language for this task; otherwise it reuses the project's existing language.

Pure discussion, advice, and overview requests write no project files by default. CodeStable does not persist unfinished discussions or guarantee automatic recovery in a later session.

Start in 5 Minutes

Install

Codex plugin marketplace:

codex plugin marketplace add codestable/CodeStable
codex plugin add codestable@codestable

Claude plugin marketplace:

/plugin marketplace add codestable/CodeStable
/plugin install codestable@codestable

skills CLI (v1 users must first follow the upgrade guide to remove the 24 retired entries, then install v2):

npx skills@latest add codestable/CodeStable/plugins/codestable

If the catalog misses the plugin entity, use npx skills@latest add codestable/CodeStable/plugins/codestable --full-depth as the deep-scan fallback.

Onboard a Project

Run /cs-onboard from the repository root. It creates only the minimal project-memory skeleton and does not take over documentation, worktree, or branch policy.

Start Working

When you are unsure which entry fits, call /cs; you can also call the owning skill directly. v2 ships 8 skills:

Skill	Purpose
cs	Route explicit actions, in-session discussion, advice, and system overview
cs-onboard	Create the minimal project-memory skeleton
cs-feat	Implement new capability or change existing behavior
cs-issue	Diagnose problems; once repair is authorized, fix with red-to-green evidence
cs-refactor	Change structure or performance under equivalence evidence
cs-epic	Decompose and advance multiple deliverable items under confirmed policies
cs-review	Read-only leaf executor; one review, with no child agent
cs-keep	Manage evidence-backed project facts, lesson lifecycle, and canonical homes

cs-code-review is a compatibility alias of cs-review. It only forwards and contains no independent rules.

Three Principles

1. thin harness, thick context

CodeStable writes responsibilities for strong models, not step-by-step scripts. Skills constrain goals, hard boundaries, and evidence; models choose paths from repository facts and load guidance on demand.

Thin means no permanent state machine or stage-artifact micromanagement, not no gates.

2. Evidence before conclusions

Feature work gets design and verification proportionate to risk; bug fixes go red to green; refactors establish equivalence first. The outer flow creates read-only reviewers.

Humans enter for product-contract changes, major risk, and overall acceptance, not every mechanical step.

3. One fact, one canonical owner

Project docs, ADRs, code, and domain documents keep their facts. CodeStable adds only a few session facts, lessons, and active cursors, never a parallel archive.

The owning skill returns conclusions to one home; if none exists, it asks the owner to choose.

Project Memory

/cs-onboard creates:

.codestable/
├── attention.md
├── lessons/
└── work/

• attention.md holds the small set of project facts needed every session, capped at 25 entries.
• lessons/ keeps one lesson per file, evolves it through observed / validated / retired, and deduplicates before writing.
• work/ exists only for active cross-session work, multi-agent handoff, or an explicitly requested durable record.

CodeStable recognizes crystallization moments while working: it observes silently and shows at most one evidence-backed candidate at ordinary completion.

Mechanizable failures go to tests or checkers first. New lessons still require explicit authorization; later sessions validate or retire them after checking current facts.

Ordinary work creates no CodeStable stage docs; the diff, tests, and delivery summary are the evidence. Discussion does not enter work/; only stable conclusions graduate through the owning skill to a canonical home.

The Two-Layer Epic Model

Large initiatives separate durable contracts from temporary execution state. A permanent Epic document owns goals, scope, acceptance, approved items, key decisions, and final delivery.

When the route is still unclear, the permanent Epic document itself is the route map; decision dependencies derive the frontier.

The agent resolves facts, and genuine product judgment and trade-offs enter HITL. Once the route is clear, reviewable, and executable, existing design review, owner confirmation, and execution begin.

A temporary work cursor keeps only its pointer, approved revision, progress, policies, and evidence.

An Epic reuses an existing Epic, RFC, or initiative home when available and creates .codestable/epics/ only on demand. The temporary cursor is deleted at completion; the permanent document remains.

See WORKFLOW.en.md for owner gates, recovery, and terminal rules.

Fit

CodeStable fits best when:

• software will evolve for months or years;
• later sessions, models, or developers must recover historical constraints accurately;
• AI should execute efficiently while humans retain product boundaries and final acceptance;
• the team values verifiable results, independent review, and reusable knowledge.

It is not:

• a multi-agent team orchestrator or automatic relay platform;
• a process engine that forces every task through one pipeline;
• a replacement for existing project docs, ADRs, issues, or pull requests;
• a necessary dependency for a disposable prototype with no maintenance horizon.

CodeStable can coexist with agent-orchestration tools. It owns task boundaries, evidence, and memory, not how the host organizes agents.

For multi-agent collaboration or independent review by a heterogeneous agent inside a CodeStable flow, use cs-agent alongside CodeStable.

Go Deeper

• Full workflow and project structure
• Responsibilities of all 8 skills and retired-entry mappings
• Installation upgrades and the v1 project boundary
• Why CodeStable exists
• Roadmap
• Version changes