Workflows

Common patterns using the design user-intent commands (colon product names). In Cursor type hyphen forms (/auth-scan); in Claude Code type colon forms (/auth:scan); in Codex type $authright-scan. Greenfield and brownfield are paths, not slash commands.

/auth:explore and /auth:change are two commands — pick one. Both start from an IAM Brief and an accepted slice. Explore is HITL (Agenda native HITL; recommended labeled not defaulted). Change is auto-plan (full plan of resolved/unresolved, batch --set, confirm-plan → ready → request-match → export). Must Decide items come from the same accepted Brief slice on both paths — explore and change differ in how they present those items, not in which must items exist for that slice. Thin delta and SP-only analogue stay thin; copy-class analogue inventories open bound lifecycle must work on both. Either command may be used on greenfield or brownfield. Later change <id> flags are follow-up on the Auth Change record either command created.

Chat skills /auth:explore, /auth:change, and /auth:doctor run their CLI loop when the opening text matches that command or the invoke has no extra text. A mismatched opening line is answered in chat and does not create an Auth Change. The agent may hint the other of those two commands; it must not auto-switch slash/skill. Later questions in an already-started change are digression — do not abandon that change. This gate does not apply to /auth:to-openspec or /auth:to-plan.

Happy path (greenfield) — `/auth:explore`

Use this when you want interactive option walking: new product, no identity estate yet, or the approach is not locked. /auth:explore asks the host to write an IAM Brief and accept a slice before allocating AUTH-YYYY-NNNN and must not mark decisions accepted from slice-accept alone. After a slice is accepted_for_lock, Decide continues in the same session. /auth:to-openspec and /auth:to-plan intercept unfinished work instead of bouncing away when a gap is already actionable.

init → /auth:explore → (optional /auth:scan on intake) →
Brief + slice accept (native HITL when unbounded) → Decide in the same chat
(--analyze, Agenda next HITL, summary) →
--ready → request-match → confirm → detect OpenSpec →
  /auth:to-openspec (OpenSpec apply + implement) | Plan mode + /auth:to-plan → /auth:review

Step	Chat / CLI	Why
Setup	`authright init`	`.authright/` + agent files for the host you pick
Open work	`/auth:explore` or `authright explore -- <intent>`	Brief first (`phase: slice`, no `AUTH-` id until `accepted_for_lock`); then create/resume DRAFT. Intake scans when context is missing or stale
Discover (optional)	`/auth:scan` or `authright scan`	If a repo exists and context is empty/sparse
Clarify	Present slice-accept when aperture is unbounded (Brief slice ids). Recommended ≠ selected. Do not start Decide until a slice is accepted_for_lock. Cancelled-empty does not start Decide.	Host judgment; bounded single slice skips the scope interview
Analyze	`authright change <id> --analyze`	Structure analysis + advisory `decision-graph.yaml` (ranking is not a Decision Lock). IAM-shaped work vs generic architecture is a structured judgment (`iam-shaped.yaml`)
Inspect	`authright change <id>`	Show change status
Decide	Map slice picks (do not re-ask the same registry set); refresh Decision Agenda (`change <id> --agenda --json`) and present `next` by default (one choose; `conflict_clarify` first); when `next` is null, optional `related_optional` Enable/Skip (default Skip; `change <id> --enable-offer`); fill `analysis.md`; edit `decisions.yaml` + `contract.md`	Accept decisions and fill the contract. Declared decision variables are projected by the CLI; the host model writes alignment and wording. Related offers are not must slots and not Decision Gaps
Summary	Host-LLM, user-friendly	Architecture / technology / engineering strategy; still-pending items called out — not a YAML dump
Lock	Confirm, then `authright change <id> --ready`	Records `LOCKED` graph nodes, projects AuthRight Design, then `DECIDED`
Request match	`authright request-match <id>` / `/auth:request-match`	Show where the locked plan still matches what you asked, and where it does not. Export waits until this check passes
Handoff	pick `/auth:to-openspec` or `/auth:to-plan`	Two handoff commands—pick one. If Decide is unfinished, finish that first; else OpenSpec (OpenSpec tool required) or Plan mode + `to-plan`
Check	`/auth:review` or `authright review`	Write `semantic.md` first, then mechanical CLI verify

Happy path (greenfield) — `/auth:change`

init → /auth:change → (optional scan on intake) →
Brief + slice accept → allocate → --analyze → auto-plan.yaml (all resolved + unresolved) →
NL → --set (batch) → --confirm-plan → --ready → request-match →
detect OpenSpec → /auth:to-openspec | Plan mode + /auth:to-plan → /auth:review

Step	Chat / CLI	Why
Open work	`/auth:change` or `authright change -- <intent>`	Host writes Brief; allocate/resume after `accepted_for_lock`; ambiguity lands as plan unresolved
Analyze + plan	`change <id> --analyze` then `change <id> --plan`	CLI auto-fills recommended where allowed; writes `auto-plan.yaml`
Override	`change <id> --set slot=option` (repeatable); optional `--enable-offer <offer_id>` for Related	Batch assignments / Enable; recompute; confirmation resets to pending
Confirm	`change <id> --confirm-plan`	Only when unresolved is empty; remaining related offers do not block
Lock → request-match → export	`--ready` → `request-match` → `to-openspec` \| `to-plan`	Order is fixed; do not ready without confirm; do not skip request-match

Happy path (brownfield)

Scan first so the chosen command is anchored in current context and the IAM Domain Snapshot. Then pick /auth:explore or /auth:change.

init → /auth:scan → pick /auth:explore or /auth:change →
on that Auth Change record: --analyze
  (explore: Agenda HITL | change: plan / --set / --confirm-plan) →
--ready → request-match → /auth:to-openspec | Plan mode + /auth:to-plan → /auth:review

Step	Chat / CLI	Why
Setup	`authright init`	`.authright/` + agent files
Discover	`/auth:scan` or `authright scan`	IAM Domain Snapshot + discovery classes (observe-only; a finding is not a Gap)
Pick explore	`/auth:explore`	Recommend-and-choose native HITL; recommended ≠ selected
Pick change	`/auth:change`	Auto-plan; recommended may auto-apply into plan; unresolved listed together
Inspect	`authright change <id>`	Show change status (and `--plan` on auto path)
Lock	`authright change <id> --ready`	After explore chooses cleared, or after change plan confirmed
Request match	`authright request-match <id>`	After ready, before export. Export waits until this check passes
Handoff	`/auth:to-openspec` or `/auth:to-plan`	Stops if Decide is unfinished or request-match has not passed
Check	`/auth:review`	Write `semantic.md` first, then mechanical verify

Document

Use /auth:doc (Cursor /auth-doc, Codex $authright-doc) when you want a readable write-up of decisions already on disk—approach, identity model, runtime behavior, risks you deferred, and checks to run when those are locked. Output goes under .authright/docs/ (or a change’s docs/ folder if you name an id). It does not change decisions, Design, or your app. There is no authright doc in the terminal.

Diagnose

Use /auth:doctor / authright doctor when you want to know what’s risky in the current code—missing login, open APIs, weak permissions, secrets or debug tools exposed. Prefer a prior scan. The report you should open is .authright/diagnosis/report.md: APIs and UI routes with file pointers, how someone could abuse them, and what data is at stake. Extra machine notes under .authright/findings/ are helpers, not the main report.

Doctor looks at your app source, not AuthRight’s own files under .authright/ (except writing the report). It is not /auth:doc, does not lock decisions, and does not patch code—follow up with explore or change when you’re ready to design a fix.

User Lifecycle & Assurance

When the request commits lifecycle / CIAM / integration concepts (sign-up, forgot-password, MFA manage, profile, linking, session revoke, provisioning, trusted-device, account closure, identity proofing, step-up, adaptive risk, organization tenancy, end-user consent, identity brokering), Decide asks the matching closed slots. They do not open on every IAM-shaped change. Authentication methods include passkey, magic link, TOTP, social, push, and email OTP when seeded — not only password and mobile OTP. Integration Briefs bind authority IdPs (PingAM, Keycloak, ForgeRock, Entra ID, Auth0, Okta, …) and social IdPs (GitHub, Google, Apple, Facebook, LinkedIn, Microsoft Account). Identity brokering is distinct from AccountLinking and from SP social-rp. Vendor overlays supply Capability names plus optional concept/IdP hints — not Decide locks. Dependent slots (login_identifier, recovery_proof, external_idp_set) follow option-gated cascade. No /auth:signup, /auth:devices, or /auth:broker intents — see Concepts.

What not to do

Don't invent /auth:greenfield / /auth:brownfield / /auth:engineering slash commands
Don't invent /auth:signup / /auth:profile / /auth:devices / /auth:broker slash commands for lifecycle coverage
Don't ask engineering mode (Keep vs Centralize) during /auth:scan — style defaults to silent keep_style at --ready
Don't invent user NFRs when request.md is silent — baseline Implementer Engineering NFRs still export; UI/frontend themes use OpenSpec WHEN (honor WHEN; do not strip gates solely because scan found no UI surface)
Don't treat /auth:to-openspec or /auth:to-plan as user-intents equal to scan/explore/change/request-match/review/doctor
Don't invent /auth:plan as a Decide intent — Plan mode is a host UI mode; handoff is /auth:to-plan
Don't treat /auth:doc as changing your app or locking decisions—it only writes a summary document
Don't confuse /auth:doctor with /auth:doc—doctor reviews code risks; doc summarizes decisions
Don't expect doctor to redesign IAM or edit source—use explore or change next
Don't bounce from handoff skills to explore/change when a gap is already actionable
Don't run /auth:to-plan outside Plan mode (skill interrupts); don't expect to-openspec without OpenSpec CLI
Don't auto-run /auth:doctor just because someone asked about risks in chat (hint after answering is fine)
Don't use Agenda next as the primary UX on /auth:change auto-plan
Don't type product slash commands in the terminal—How commands work

Scan (or empty) then /auth:to-openspec with nothing in flight: hint /auth:explore or /auth:change. Export waits for an explicit continue confirm when nothing is pending — --ready is not silent.

On this page