Overview

AuthRight Harness is the identity-security decision layer between your codebase and implementation. You understand the IAM reality, record durable decisions, export a handoff package coding agents can implement, then verify. Read this after Getting started when you want the mental model on one screen. The long form is Concepts.

The path into implementation: Understand → Decide → Request Match → Handoff (OpenSpec | Agent Plan-mode). Pick one Decide command; pick one handoff command.

The product loop

Intent → Understand → Decide → Request Match → OpenSpec | Agent Plan-mode → Implement → Verify

• AuthRight Harness owns discovery, context, decisions, contracts, request match, and review
• OpenSpec owns proposal / specs / design / tasks / apply / archive when you pick that handoff (needs the OpenSpec tool)
• Agent Plan-mode owns the Plan-mode package under .authright/changes/<dir>/agent-plan/ when you pick that handoff (/auth:to-plan)
• Coding agents own application code changes

AuthRight Harness does not write application source and does not replace OpenSpec or host Plan mode.

The six ideas

1. Auth Context is what IAM looks like today. Heuristic discovery (authright scan) writes .authright/context.yaml. Some notes stay unconfirmed until you decide — they are not decisions. Java and Node.js / TypeScript have the strongest coverage today; Python and Go are supported and being strengthened. More languages and stacks will follow.

2. Decision locks are the durable project constraints. authright init writes an empty .authright/constitution.yaml stub that is not enforced. The first Decide path (/auth:explore or /auth:change) locks decisions from intent and scan observations. A later change appends, or explicitly supersedes a still-valid lock through conflict clarification. Engineering style for a change defaults silently to Keep current style (keep_style) at --ready — there is no Centralize IAM mode choose. When request.md explicitly asks to relocate/centralize auth, that maps into allowed_improvements while mode stays keep_style. Landing/pack_defaults are projected from request commitments ∩ commitment-aligned IAM locks ∩ observed integration mechanisms (Technology Registry) — not showcase pack defaults (Java ≠ always Spring Security). After upgrading, re-analyze open Auth Changes so stale pack_defaults regenerate.

3. An Auth Change is one unit of IAM decision work. Folder under .authright/changes/ with id AUTH-YYYY-NNNN (immutable). Intent, analysis, decisions, security notes, contract, status.

4. Decisions must be accepted before export. Edit decisions.yaml (and related markdown) deliberately. Decision Lock: accepted decisions must not be silently inverted during implementation; authright review looks for conflicts.

5. Request match, then pick one handoff. After --ready, authright request-match checks that the locked plan still matches what you asked. Export waits until that check passes. Pick OpenSpec (authright to-openspec, needs the OpenSpec tool) or Agent Plan-mode (authright to-plan in Plan mode)—two handoff commands, same locked change. Coding agents implement outside AuthRight Harness.

6. Review verifies without mutating app source. authright review writes under .authright/reviews/—it checks the lock against implementation; it is not a full security audit.

Also useful anytime: /auth:doctor reads your app source and writes a risk report at .authright/diagnosis/report.md. /auth:doc writes a decisions summary under .authright/docs/. Different jobs—don’t mix them up.

Picture

.authright/
├── context.yaml / constitution.yaml
├── diagnosis/report.md      ← doctor: code risk report (read this)
├── docs/                    ← doc: decisions write-up
├── logs/                    ← local run black box (gitignored)
├── changes/AUTH-YYYY-NNNN-…/     ← decide here
└── reviews/AUTH-YYYY-NNNN/      ← verify here

openspec/changes/<slug>/         ← OpenSpec handoff (when OpenSpec is present)
.authright/changes/…/agent-plan/ ← Agent Plan-mode handoff

The loop you'll run

authright init
authright scan                    # chat: Cursor /auth-scan · Claude /auth:scan
pick one Decide command:
  authright explore -- "…"        # HITL
  authright change -- "…"         # auto-plan
on that Auth Change record:
  (explore: Agenda HITL | change: plan → --set → --confirm-plan)
  authright change <id> --ready
authright request-match <id>
pick one handoff command:
  authright to-openspec <id>      # needs OpenSpec installed
  # or Plan mode + authright to-plan <id> / /auth:to-plan
        (exported package → agents implement)
authright review <id>             # or /auth:review

/auth:explore and /auth:change are two Decide commands—pick one. /auth:to-openspec and /auth:to-plan are two handoff commands—pick one. authright change <id> is follow-up on the record either Decide command created.

Brownfield tip: start with Existing projects—scan first, don't boil the ocean.