Docs
Playbooks

Playbooks

Step-by-step workflows, team adoption patterns, and troubleshooting for Aircury's Framework in day-to-day practice.

The practical companion to the rest of the Framework documentation. Where Methodology, Architecture, and Testing pages explain what and why, this page explains how — the concrete actions you take day-to-day when working with the Framework.

End-to-End Workflow

A complete feature implementation using the OpenSpec Extended Framework:

Receive and understand the requirement

Start with a clear understanding of what’s needed. Talk to stakeholders, review any existing specs, check if there’s a related capability in openspec/specs/. The goal is to have a mental model of the change before you touch a keyboard.

Verify the Definition of Ready is met before proceeding.

Create the proposal — opsx:propose

/opsx:propose "descriptive-name-for-the-change"

The agent scaffolds a proposal at openspec/changes/<name>/. Review and refine proposal.md:

  • Is the Why accurate and specific?
  • Are the Capabilities correctly identified? (These drive the spec files)
  • Is the Impact complete?

Review and refine the specs

The agent generates spec files under openspec/changes/<name>/specs/. For each capability:

  • Are requirements written with SHALL/MUST language?
  • Does each requirement have at least one scenario?
  • Are scenarios written testably — would they become good Gherkin tests?
  • Is anything missing from the business requirements?

This is the highest-leverage investment — good specs prevent rework.

Review the design

The agent generates design.md. Verify:

  • Does the file structure follow the three-layer convention (domain/, application/, infrastructure/)?
  • Are all external dependencies defined as Port interfaces?
  • Are technical decisions explained with rationale?
  • Are Aggregates, Bounded Context, and Use Cases explicitly named?

Add comments or regenerate sections if the architecture isn’t right.

Implement — opsx:apply

/opsx:apply

The agent works through the task list. During implementation:

  • Check in after each major task group
  • Validate architecture rules as you go — don’t wait until the end
  • Commit incrementally after each logical unit of work

Write BDD scenarios (if not already done)

Convert the OpenSpec scenarios in your spec files to Gherkin .feature files. Run them. They should pass. If they don’t, you’ve found a bug the unit tests missed.

npx cucumber-js features/ --require steps/

Code review

Run through the Quality Guardrails checklist. Two-layer review: automated checks (lint, types, tests, architecture boundaries) pass first; then human review for architectural fit and business correctness.

Archive — opsx:archive

/opsx:archive

Promotes specs to openspec/specs/, archives the change folder, and updates the living documentation of the system. The capability becomes part of the permanent record.

Verify the Definition of Done is met before archiving.

Team Adoption

Introducing the Framework to a team that isn’t used to it requires a phased approach. Don’t try to introduce everything simultaneously.

Phase 1 — Foundations (Week 1-2)

  1. Start with Conventional Commits — visible, measurable, low-friction
  2. Introduce AGENTS.md — set up the project’s rules file as a team
  3. Introduce OpenSpec proposals for the next two features — no specs yet, just proposals
  4. Hold a team session using this wiki as the guide

Phase 2 — Specs & Architecture (Week 3-4)

  1. Write specs for the next feature before the agent implements it
  2. Apply the three-layer architecture to one service as a reference implementation
  3. Review it as a team — walk through what each layer does and why
  4. Add eslint-plugin-boundaries to CI — architecture violations become build failures

Phase 3 — Full Framework (Week 5+)

  1. All changes go through opsx:propose → opsx:apply → opsx:archive
  2. Architecture lint running in CI
  3. BDD scenarios written from specs before implementation

Common Objections

ObjectionResponse
”This slows us down”It front-loads time into planning. Implementation is faster because the agent knows exactly what to build. Total cycle time decreases after the first 2-3 changes.
”The agent can figure out the architecture itself”It can. But it won’t use your architecture. It will use whatever plausible pattern it was trained on most recently, which may change between sessions.
”We don’t have time to write specs”How much time do you spend in post-implementation debugging and refactoring? Specs prevent more time than they cost.
”Tests slow down feature development”Tests slow down the first implementation of a feature. They speed up every subsequent touch of that code.

Troubleshooting

Agent is ignoring architecture rules

Symptom: Infrastructure imports appearing in domain classes despite explicit rules.

Causes and fixes:

  1. Rules are in chat history, not AGENTS.md → Move rules to AGENTS.md
  2. Context too long → Start a new session, reference AGENTS.md immediately
  3. Rules too vague → Use the specific rule format from the Architecture Rules page

Specs are too vague to implement

Symptom: Agent asks many clarifying questions, or implementation doesn’t match intent.

Fix: Return to the spec. Add more WHEN/THEN scenarios. Each scenario is a concrete case the implementation must handle. The more scenarios, the tighter the implementation.

Tests are testing implementation, not behaviour

Symptom: Tests break when you refactor internals without changing behaviour.

Fix: Test through public interfaces only. If you’re calling a private method in a test, restructure the code or move the behaviour to a public method on an appropriate class.

Context window fills up mid-implementation

Symptom: Agent starts making mistakes that seem inconsistent with earlier, correct work.

Fix:

  1. Complete the current task cleanly and commit
  2. Start a new context window
  3. Reference AGENTS.md: “Please read AGENTS.md for our conventions, then read openspec/changes/<name>/tasks.md for the remaining tasks”

Team isn’t adopting consistently

Symptom: Some engineers use the Framework, others don’t. Code quality is inconsistent.

Fix: Make it structural, not optional. Add eslint-plugin-boundaries to CI (fails the build on architecture violations). Add commitlint as a pre-commit hook. These turn conventions into enforced rules.

Agent keeps writing anemic domain models

Symptom: Domain classes that are just data containers with getters and setters, no business logic.

Fix: Add an explicit rule to AGENTS.md: “Domain entities must contain business logic and enforce their own invariants. Use cases orchestrate; entities enforce.” Then in the spec, describe behaviour through actions (Order.confirm(), Payment.refund()), not data (order.setStatus('confirmed')).