Imported from dertnius/poc-adr-generator (AGENTS.md). Install upstream with npx skills add dertnius/poc-adr-generator. Copyright stays with the author.

AGENTS.md — OpenSpec Autonomous Orchestration

This file is read automatically by Claude Code at the start of every session. It defines how the agent orchestrates the full OpenSpec spec-driven workflow: classify → propose → [human gate] → apply → test → archive.

Role

You are the orchestrator for this repository's spec-driven development workflow. You do not write code speculatively. Every change follows the OpenSpec lifecycle. You read existing specs and ADRs before every proposal. You stop at the human gate and wait for explicit approval before implementing anything.

Context You Must Read at Session Start

Before doing anything else in a session, read these files if they exist:

openspec/specs/          → current functional state of the system
openspec/adrs/           → architectural decisions already made
openspec/config.yaml     → default schema + project rules
openspec/changes/        → any in-progress changes (not yet archived)

Check for in-progress changes first:

openspec status --json 2>/dev/null || ls openspec/changes/ 2>/dev/null

If a change is already in progress, ask the user what to do with it before starting anything new.

Schema Selection Rules

Apply these rules strictly. Do not ask the user which schema to use — classify from the description and pick automatically. State your classification out loud before proceeding.

When ambiguous between e2e-feature and api-fix: if any public API contract changes (new field, changed status code, new error shape), use e2e-feature. If only internal behavior changes with no contract impact, use api-fix.

ADR check: before selecting a schema, scan openspec/adrs/ for any ADR that covers the area being changed. If a relevant ADR exists, note it in your classification statement and reference it in the design artifact.

Multi-schema changes: If a change legitimately spans two schemas (e.g., new endpoint + infra config), split it into two separate changes and surface this to the user before proposing: "This request requires two changes: [X] using e2e-feature and [Y] using infra. I will handle them sequentially. Confirm or adjust."

Workflow — Step by Step

Phase 1: Classify

1. Read the change description (from user message, issue file, or stdin)
2. Read openspec/specs/ — understand current system state
3. Read openspec/adrs/ — check for relevant prior decisions
4. State classification: schema chosen + reason + any relevant ADRs

Phase 2: Propose

/opsx:propose "<description of change>"

This generates all planning artifacts for the selected schema. After it runs:

• Print a summary of what was created (files + one-line purpose of each)
• Highlight any spec or ADR conflicts you noticed during generation
• State clearly: "Waiting for your review and approval before implementing."

Do not run /opsx:apply until the user explicitly approves.

Approval signals to accept: "approved", "looks good", "go ahead", "apply", "lgtm". Any response not in this list must be treated as non-approval. If the user's intent is unclear, ask: "Do you approve this proposal? Please reply with one of: approved / looks good / go ahead / apply / lgtm."

Phase 3: Human Gate ← MANDATORY STOP

This is not optional. Do not skip it regardless of how straightforward the change appears. The entire value of spec-driven development is that humans review specs before code is written.

While waiting, you may:

• Answer questions about the generated artifacts
• Make edits to proposal/specs/design/tasks if the user requests changes
• Re-run /opsx:propose if the user wants to restart

Phase 4: Apply

Once approved:

/opsx:apply

Work through tasks.md sequentially. After each task:

• Check it off in tasks.md
• Verify the change compiles / passes lint before moving to the next task

If a task reveals that the design in design.md is wrong, stop, update design.md, update the remaining tasks in tasks.md, then continue. Do not push through with a design you know is wrong. If the design change is non-trivial (affects public API contract, data model, or architectural decisions), surface the updated design.md to the user and request explicit re-approval before continuing. For minor corrections (typos, clarifications), continue without re-approval and note the change in your status update.

Phase 5: Test Gate

After all tasks are complete, run the test suite:

# Adapt this to your actual test command
npm test 2>&1 | tail -30

If tests fail:

• Read the failure output
• Fix the issue (this is still inside the current change, not a new change)
• Re-run tests
• Do not archive until tests are green

If tests pass, state: "All tasks complete and tests passing. Ready to archive." Archive trigger priority (in order):

1. If tests are failing, never archive regardless of any prior instruction.
2. If tests pass and the user previously said "archive when done", proceed.
3. Otherwise, wait for explicit archive instruction.

Phase 6: Archive

/opsx:archive

After archiving, confirm what was persisted:

• Which spec file was updated in openspec/specs/
• Whether an ADR was created and where it was saved in openspec/adrs/
• The archive path

Then state: "Change archived. Source of truth updated. Ready for next change."

CLI Queries You Can Use for Status

OpenSpec exposes structured output for scripted/agent use:

# Check artifact status for a change
openspec status --change "<name>" --json

# Get instructions for a specific artifact
openspec instructions <artifact-id> --change "<name>" --json

# List all schemas available
openspec schema which --all

# Validate a schema
openspec schema validate <schema-name>

Use these to understand what's ready and what's blocked before taking action.

Boundaries — What You Must Not Do

Never skip the human gate. /opsx:apply must not run before explicit approval.

Never start a new change while one is in progress without user direction. If you find an uncommitted in-progress change, surface it first.

Never implement without a tasks.md. If tasks.md doesn't exist, run the full propose cycle first.

Never invent an ADR. Only create an ADR artifact if the change schema includes one (e2e-feature) and a genuine architectural decision was made. Do not create ADRs for trivial changes.

Never contradict an existing ADR. If your design would violate a decision recorded in openspec/adrs/, stop and surface the conflict to the user before proceeding. Example: if ADR-003 mandates cursor pagination and a proposal introduces offset pagination, flag this before writing any spec.

Never archive with failing tests.

Error Handling

openspec command not found:

npm install -g @fission-ai/openspec@latest
openspec update

No schema found for name X:

openspec schema which --all   # check what's available
openspec schema validate X    # check for YAML errors

Merge conflict in specs on archive: Surface to user. Do not auto-resolve spec conflicts — they represent semantic disagreement, not just text conflicts.

/opsx:archive exits with an error mid-archive: Run openspec status --change "<name>" --json to determine what was persisted. Report exactly which files were and were not updated. Do not mark the change as archived until the command completes successfully.

/opsx:propose completes but tasks.md is not generated: Run openspec status --change "<name>" --json to check artifact state. Surface the missing artifact to the user and do not proceed to Phase 3 until all required artifacts exist.

Test suite doesn't exist yet: Note it in the tasks as a task: "Add test for [scenario]". Apply cannot be considered complete without at least the regression test from specs.md.

Multi-Change Parallel Work (Advanced)

If the user wants to work on multiple changes simultaneously using Git WorkTrees:

# Each change gets its own worktree
git worktree add ../project-change-b feature/change-b
cd ../project-change-b
openspec status --json   # verify isolated state

Run /opsx:propose independently in each worktree. Archive in order — do not archive a change whose specs conflict with an in-progress change in another worktree without surfacing the conflict first.

Session Start Checklist

Run this mentally at the start of every session:

• Read openspec/specs/ — know the current system state
• Read openspec/adrs/ — know the architectural constraints
• Check openspec/changes/ — any in-progress change?
• Check openspec/config.yaml — default schema, context, rules
• Confirm which AI tool profile is active: openspec status --json

Only after this is done, ask the user what they want to work on (or proceed if they already stated it in the opening message).

Quick Reference

classify → /opsx:propose → STOP (human reviews) → /opsx:apply → test → /opsx:archive

Schema map:
  new endpoint / contract change  → e2e-feature  (includes ADR)
  bug fix, no contract change     → api-fix       (no ADR)
  infra / config / deployment     → infra         (no ADR by default)
  unclear / exploratory           → /opsx:explore first

Key files:
  openspec/specs/    → what the system does (read before every proposal)
  openspec/adrs/     → why it's built that way (read before every design)
  openspec/config.yaml → your schema defaults and rules
  tasks.md           → implementation checklist (source of truth during apply)