Guides

How to use Cornerstone, one situation at a time. Each guide names its profile and its default mode.

Cornerstone v1 supports all 10 profiles (D24). stone render writes the role files, the checks, and the trigger workflows of each profile. Each guide has two parts:

• Today: the steps that work now, with the real commands.
• Not built yet: a short list of the parts that do not work. Do these by hand.

Pick a guide

Situation	Guide	Profile	Default mode	Status
I have an empty folder and an idea	Start a project	full-project	hybrid	Works today
I have a repo with no agent framework	Add Cornerstone to a repo	single-ticket	agent-centric	Works today
I use Spec Kit, OpenSpec, BMAD, or rule files	Migrate to Cornerstone	(setup)	—	Partial
I want to make one small, clear change	Make a small change	single-ticket	agent-centric	Works today
I have a confirmed bug	Fix a bug	debugging	hybrid	Works today
I want a feature that touches many layers	Build a feature	app-slice	hybrid	Works today
I have new bug reports to sort	Triage bug reports	bug-triage	agent-centric	Partial
I want a structured view of the health of one area	Audit an area of the code	code-audit	agent-centric	Partial
I need to answer one question with throwaway code	Run a spike	spike	human-centric	Works today
A bot opened a dependency PR, or a package is old	Upgrade a dependency	dependency-upgrade	agent-centric	Partial
A vendor released a new model or new guidance	Refresh an adapter	adapter-refresh	agent-centric	Partial
A new Cornerstone version came out	Upgrade Cornerstone	(setup)	agent-centric	Works today
I want to change the structure of the code, with the same behavior	Refactor or migrate	refactor-migration	hybrid	Works today

All guides use Run the roles. It shows how to start each role in its own session, and how to commit its work.

flowchart TD
  Q{What do you have?} -->|An idea, no code| SP[Start a project]
  Q -->|A repo, no framework| AR[Add Cornerstone to a repo]
  Q -->|A repo with another framework| MG[Migrate to Cornerstone]
  SP --> W{What is the work?}
  AR --> W
  MG --> W
  W -->|Small and clear| SC[Make a small change]
  W -->|A confirmed bug| FB[Fix a bug]
  W -->|A feature across layers| BF[Build a feature]

Profile or mode?

The two words have different meanings in Cornerstone.

Word	Answers	Values
Profile	What type of work is this? Which gates and checks apply?	single-ticket, debugging, app-slice, full-project, and 6 more
Mode	Who does each stage: an agent, a human, or the two together?	agent-centric, hybrid, human-centric

The profile sets the gates. The mode does not change them. Each profile can run in each mode.

Mode	Use when
agent-centric	The ticket is complete and the work is routine. Ticket in, draft PR out.
hybrid	You own the design. An agent does the build.
human-centric	The build needs your judgment, or you want to learn the code. An agent still writes the tests.

To change the mode for one ticket, add a mode:<name> label or field to the ticket. To change the default, see customization.md.

What you need

Tool	Why
A clone of this repo	The framework files that stone render reads
Python 3.11 or later, and pip install ./stone from the clone	The stone CLI
git and the GitHub CLI (gh)	Branches, issues, and PRs
Claude Code, with the cornerstone plugin	The only harness adapter at this time. See the install steps.