OpenSpec

Status: supported — one Implementation handoff option (alongside Agent Plan-mode).

Use OpenSpec when the OpenSpec tool is installed (openspec on your PATH—not AuthRight’s authright). /auth:to-openspec and /auth:to-plan are two handoff commands—pick one.

AuthRight Harness owns the decisions. OpenSpec stays a separate apply/archive workflow. AuthRight does not bundle OpenSpec, does not run openspec apply, and does not depend on @fission-ai/openspec.

When to export

After decisions are accepted, contract.md is filled, and request-match has passed:

authright change <id> --ready
authright request-match <id>
authright to-openspec <id> --phase prepare   # feed + claims (default if --phase omitted)
# OpenSpec propose (read authright-feed.md + authright-claims.yaml first)
authright to-openspec <id> --phase check     # coverage floor
authright to-openspec <id> --phase finalize  # DECIDED → EXPORTED

Bare to-openspec does not silent-write the full package — it prepares feed/claims and requires host OpenSpec propose.

Chat equivalent (after init): /auth:to-openspec (engineering handoff—not one of the Decide commands such as /auth:explore or /auth:change). If Decide is unfinished, the chat skill intercepts pending work instead of bouncing away when a gap is actionable. When nothing is pending it summarizes the decisions, including whether the locked plan still matches what you asked, and asks whether to continue before export. Happy path on change: confirm-plan → ready → request-match → propose-first handoff.

Under openspec/changes/<slug>/:

  • authright-feed.md + authright-claims.yaml — AuthRight propose inputs (not implementer Binding SoT). Prepare compiles them from the same Binding expansions used for to-plan / shared gather (locks, engStrategy, UI, baseline/user NFRs, pack landing, admin/lifecycle recipes, checklist, Design/migration when applicable)—not locks-only. Binding prose uses readable surface labels (scanned . → “repository root”). Future Binding emitters must extend that prepare mapping in the same change. Guidance-only security.md / curated analysis prose stays design/feed narrative unless product law already treats it as Binding for to-plan. External eval verifies are evidence only, not the theme catalog.
  • proposal.md, design.md, tasks.md, specs/** — authored by OpenSpec propose; must cover claims (extras allowed; coverage is a floor, not a ceiling). Prefer observable Scenario THENs and milestone/surface-oriented tasks; do not treat Coverage-hints columns or 1:1 claim dumps as the preferred Binding style. Check may emit non-blocking quality_warnings for oracle-scaffold patterns.
  • authright.yaml optional link back to the Auth Change id — do not treat it as the implementation checklist

Export surface language: Binding text in specs/, tasks.md, proposal.md, and normative design.md constraints is OpenSpec-executable English. AuthRight registry ids, Decide-axis artifact names, and Decision Package paths are export-time inputs—not required reading after export. On refresh, refined tasks.md may be preserved; if it still contains harness pass-through, fix via propose/repair or --force-tasks.

design.md Implementation Constraints include pack-idiomatic landing, baseline Implementer Engineering NFRs, optional User-stated NFRs when mapped, and UI continuity worded with OpenSpec WHEN: keep the current visual language and place new feature entry points in the existing information architecture when the change adds or changes user-visible UI. Do not invent UI work when WHEN does not hold; do not strip those gates from the package solely because scan found no UI surface.

Chat handoff: OpenSpec propose-first or hard-fail to to-plan

When /auth:to-openspec runs on an export-ready change, the agent detects OpenSpec before writing:

PathWhenWhat happens
OpenSpec presentopenspec is installed(1) --phase prepare → feed/claims. (2) OpenSpec propose (claims front-loaded; elaboration OK). (3) --phase check → coverage; repair ≤3 if needed. (4) --phase finalize → EXPORTED. (5) validate/show. No --force-project.
OpenSpec absent → to-planopenspec is not installedStop — no write under openspec/changes/. Switch the chat to Plan mode and run /auth:to-plan (host spelling). AuthRight will not invent an OpenSpec package for you.

Having an openspec/ folder without the openspec tool still means OpenSpec absent—to-openspec will not write.

When OpenSpec is present, you may still pick Plan mode + /auth:to-plan instead—both options are fine. If both packages exist, implement from one of them this session; do not mix them as the source of truth.

Mapping (export)

AuthRight HarnessOpenSpec
Intent / analysisproposal.md
Decisions / architecturedesign.md
Security + contractdelta specs/
Implementation scopetasks.md
Traceabilityauthright.yaml

After export

Implement with your usual OpenSpec + coding-agent workflow. Then:

authright review <id>
# or: /auth:review

Review runs from EXPORTED (or implementing states), writes .authright/reviews/<id>/, and does not mutate application sources. MVP review is deterministic heuristics—not a full security audit.

Editing changes

Auth Changes are meant to be revised as you learn. Artifacts under .authright/changes/AUTH-YYYY-NNNN-…/ are the source of truth for that unit of work.

Agent Plan-mode

Status: supported — one Implementation handoff option (alongside OpenSpec).

On this page

When to exportChat handoff: OpenSpec propose-first or hard-fail to to-planMapping (export)After exportRelated