Amazon Engineering Skills — Cursor Rules

Source of truth. This file is a thin router. The actual content lives in skills/, agents/, patterns/, and .claude/commands/. Do not duplicate guidance here — point to it.

This project uses Amazon-style engineering practices. When working in this codebase:

1. Identify the lifecycle phase (Working Backwards / Design / Build / Deploy / Operate / Learn).
2. Load the relevant skill(s) from skills/ for that phase.
3. Follow the skill's Process section step by step, including approval gates.
4. When in doubt about which skill applies, read skills/using-amazon-skills/SKILL.md first — it is the meta-skill that routes ambiguous requests.

Skill Index

Meta

Working Backwards

Design

Build

Deploy

Operate

Learn

Architectural Patterns

Patterns live in patterns/. Read patterns/INDEX.md (lightweight catalog with title, description, and applicability criteria) during design to decide which patterns are relevant. Only load the full patterns/<name>/PATTERN.md when criteria match. This prevents loading hundreds of lines of pattern docs into context unnecessarily.

Bar Raiser Personas

Personas live in agents/. When a skill specifies bar raiser review, load the persona and apply its lens.

Slash Command Definitions

Slash command flows are defined in .claude/commands/ (canonical) and mirrored in .gemini/commands/. Each command file lists steps, gates, and output artifacts. When the user invokes a command, follow the corresponding file.

Operating Behaviors (the contract)

Read AGENTS.md for the full operating contract. The non-negotiable behaviors are:

1. Respect approval gates. During /wb, /design, /spec, stop at each gate and present work.
2. Match the ceremony to the change. Trivial → direct to code; Small → direct or lightweight spec; Medium → /spec + /build; Large → full /design flow; New product → /wb first. The agent picks; the user only sees outcome-framed options when there is genuine ambiguity. For brownfield projects without BLA artifacts, propose /onboard (3 paths: anchor only / validate-the-why with inferred PR/FAQ / forward WB + gap analysis). See skills/using-amazon-skills/SKILL.md → "Match the Ceremony to the Change" and skills/brownfield-discovery/SKILL.md for details.
3. API First. Every customer-facing surface is an API. UI / CLI / SDK / MCP / agent / partner are all clients. The API spec is created before any client spec. Pick the right contract standard per protocol — OpenAPI for REST, GraphQL SDL for GraphQL, .proto for gRPC, AsyncAPI + JSON Schema/Avro/Protobuf for async events, ODCS for data contracts, MCP manifest for MCP tools, provider-native spec for AI agent tools. See skills/api-contract-first/SKILL.md.
4. Patterns enter design as alternatives. Read patterns/INDEX.md to identify relevant patterns; load full PATTERN.md only when criteria match.
5. Track tasks during /build. The orchestrator owns tasks.md. Flip [ ] → [-] before dispatching a wave; [-] → [x] as sub-agents report success; [!] for blockers. No spec is "done" while any task is [ ] or [-].
6. /build is autonomous to feature completion. Approval gates happened in /design. /build runs all specs end-to-end without asking between specs, waves, or PASSED reviews. Stops only for hard blockers, FAILED review, unrecoverable green-build failure, or explicit user pause request.
7. Use implementation memory internally during /build. After current spec/tasks and coherence-review action items are known, read skills/implementation-memory/SKILL.md and .bla/implementation-memory.md if present. Select active rules using multi-signal matching (Tags, File patterns, Applies when). Increment Hit count. Semi-automatic trigger: after PASSED WITH FIXES NEEDED and fixes done, generate self-reflection, extract candidates, present to user for Accept/Reject/Edit. Manual trigger: after PASSED, prompt user to test/debug, update memory only after Quality Memory Review request. Nudge: if ≥3 builds without update, remind in summary. Multi-source: also capture from /review (recurring findings) and /learn (COE actions). Staleness: flag rules unused >90 days during Quality Memory Review. Do not expose as a separate user command.
8. Code Quality Bar. While writing code, apply paradigm-by-context (functional core, imperative shell), SOLID where it pays, clean naming, no dead code. See skills/incremental-implementation/SKILL.md → "Code Quality Bar".
9. Surface assumptions. Never proceed on an unstated assumption. Ask.
10. Push back when warranted. Not a yes-machine.
11. Verify, don't assume. Run the tests; check the file; don't claim something works without evidence.

Lifecycle Flow

/wb → /listen → /define → /invent → /refine → /test-idea
                                                    ↓
                            /design → (specs) → /build → /review → /deploy
                                                                       ↓
                                                            /operate → /learn ↺

Each phase produces artifacts that feed the next.