star-guidelines

---

TL;DR — Frontier coding agents don't fail at intelligence. They fail at execution discipline. Star Guidelines is an installable, verifiable, cross-IDE execution contract — install it, ask one question, confirm it's active.

---

Why this exists

Six systemic failure modes of coding agents. None of them are model capability problems:

Failure mode	Root cause	Real cost
Picks a direction when the request is ambiguous	Missing clarification gate	Rollback cost ×2, trust erosion
Edits code outside the task boundary	Missing scope constraint	PR diff bloat, exponential review cost
Stacks three layers of abstraction for one caller	Missing simplicity bias	Technical debt arrives early
Overwrites uncommitted user changes	Missing ownership boundary	Lost work — highest-severity trust incident
Reports "Done" without running any verification	Missing evidence requirement	False completion → production incident
Loads Cursor rules in Claude, or vice versa	Missing adapter isolation	Rules cancel out = running naked

Better models will not fix these. An execution contract with enforcement will.

---

The Star Contract

Source of truth: core/CONTRACT.md. Every adapter is a projection of these seven rules into the target IDE's native loader.

#	Rule	Trigger	Agent behavior
1	Clarify before editing	Ambiguity touches files / API / data / safety / visible behavior	State assumptions, ask before acting
2	Read before designing	Any non-trivial change	Read owning module, tests, docs, conventions first
3	Keep the change narrow	Every edit	Touch only files the request needs; no drive-by refactors
4	Prefer the current simple solution	Temptation to add abstraction / config / strategy pattern	No new layer without >1 real caller
5	Preserve user work	Uncommitted changes exist	Owned by the user by default; don't touch without instruction
6	Verify with concrete evidence	Before reporting completion	Run smallest useful test/build/lint/screenshot/repro
7	Explain tradeoffs briefly	Meaningful risk or alternative exists	One or two sentences; don't turn routine work into ceremony

Contract intensity scales linearly with risk. A typo fix stays ultra-light; a cross-module refactor requires plan + evidence + risk report.

---

Execution loop

The seven rules constrain what not to do. The execution loop defines how to do it:

┌─────────┐     ┌─────────┐     ┌─────────┐     ┌─────────┐     ┌─────────┐
│  Orient │ ──▶ │  Scope  │ ──▶ │  Edit   │ ──▶ │ Verify  │ ──▶ │ Report  │
└─────────┘     └─────────┘     └─────────┘     └─────────┘     └─────────┘
 Read owning     State assumptions  Touch smallest   Run smallest     Report: what
 files/tests/    that affect the    file set         useful check     changed, passed,
 docs/conventions implementation                    + collect evidence skipped, risk left

Five steps. Each has an exit condition. No ceremony.

Rules vs loop: The loop is the operation path; rules are guardrails at each step. Orient is constrained by Rule 2, Edit by Rules 3/4/5, Verify by Rule 6.

---

Adapter architecture

Core design decision: each IDE loads rules through its own native format, not a universal file that hopes every loader reads it.