Help us improve
Share bugs, ideas, or general feedback.
From build-like-amazon
Reverse-engineers existing projects to produce auto-anchored Design Docs, API contracts, and Threat Models from real code, IaC, and observability data.
npx claudepluginhub robisson/build-like-amazon-agent-skillsHow this skill is triggered — by the user, by Claude, or both
Slash command
/build-like-amazon:brownfield-discoveryThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Build Like Amazon's canonical flow assumes a greenfield path: `/wb` → `/design` → `/spec` → `/build`. Most real adoption happens on **existing projects** with code, IaC, CI/CD, observability, and on-call already running — but no BLA artifacts.
Builds and maintains ARCHITECTURE.md and DETAILED_DESIGN.md incrementally with coverage tracking. Principal mode analyzes vision, bottlenecks, gaps, and alternatives.
Deep architectural review of a platform or product — cross-references code against claims, maps failure modes, evaluates scaling bottlenecks, and produces a decision-grade handoff document with ADRs. Use when: reviewing an existing system for scaling readiness, performing a CTO handoff, evaluating platform architecture for enterprise readiness, or auditing a codebase before a major migration. Triggers: architecture review, scaling review, platform review, CTO handoff, system audit, scaling analysis, architecture assessment, production readiness.
Reverse-engineers an existing codebase into V-Model artifacts (ADRs, arc42, FEATURE inventory, backlog seed) with sourced claims. Use for brownfield projects, legacy code, or entering the V-Model workflow from existing code.
Share bugs, ideas, or general feedback.
Build Like Amazon's canonical flow assumes a greenfield path: /wb → /design → /spec → /build. Most real adoption happens on existing projects with code, IaC, CI/CD, observability, and on-call already running — but no BLA artifacts.
This skill closes that gap. It does an engineering reverse pass on the project: reads the code, IaC, CI, dashboards, and external dependency calls, then produces a Design Document, API contracts, and a Threat Model anchored in the real state of the system. Subsequent /spec and /build invocations use these reverse-engineered artifacts as their anchor — exactly as they would use canonical artifacts in greenfield.
This is not retroactive approval. The output carries a banner saying "REVERSE-ENGINEERED — not approved by any bar raiser, used as context, not as historical decision record." It exists so the agent stops re-discovering the project on every invocation and so future bar raisers have something to compare against.
docs/design/, docs/working-backwards/)/onboardDo NOT use for:
/wb → /design instead)using-amazon-skills/SKILL.md handles those without needing discovery)Inside Amazon, services accumulate years of decisions that live only in the heads of long-tenured engineers and in the code. New owners onboarding a service do a structured system walkthrough — a disciplined pass where they read the code, the runbooks, the incident history, and produce a written summary of the system as it is. This skill is the same pattern: a one-time, structured pass that produces written artifacts so the next reader (human or agent) is not starting from scratch.
The artifacts produced are deliberately marked as reverse-engineered. Pretending a reverse-engineered Design Doc is the same as one approved by a Design Bar Raiser would corrupt the process — bar raisers exist precisely because retroactive justification is not the same as upfront design.
brownfield-discovery runs in one of three paths, picked by the user via AskUserQuestion at the start. The differences:
| Path | Purpose | Output | Time |
|---|---|---|---|
| A — Anchor (default, recommended) | Anchor the agent on the real state of the project so future /spec and /build are precise. Does not touch customer / problem / PR/FAQ. | Design Doc + API contracts + Threat Model + patterns-observed | ~15–30min |
| B — Reverse Working Backwards | Validate that the project is solving the right customer problem, as-built. Inferred PR/FAQ with hard questions for the user where the code cannot answer. | Path A's output + reverse-engineered customer-profile / problem-statement / solution-sketch / PR/FAQ (DRAFT, INFERRED) + bar-raiser questions | ~30–45min |
| C — Forward WB + Gap Analysis | Run a fresh Working Backwards as if greenfield (with full approval gates), then compare it to the existing project. Surfaces strategic gaps. | Path A's output + full WB artifacts + gap-analysis.md | ~1–2h, with gates |
The agent presents these three as outcome-framed options (not process names) and runs the chosen path. The shared engine (Steps 1–6 below) is the same; Path B and C extend Path A with additional steps.
Use AskUserQuestion to surface the three options to the user, framed by outcome:
Detected: existing project, no BLA artifacts. How would you like to use
/onboard?[A] Anchor only — produce a Design Doc, API contracts, and a Threat Model from the existing code. Future
/specand/builduse these as anchor. Does not try to recover the customer story or PR/FAQ. Recommended for "I'll keep building here, give me the agent the context it needs." ~15–30min.[B] Validate the why — everything in [A], plus an inferred PR/FAQ reconstructed from the code, README, and docs. The doc-bar-raiser persona surfaces hard questions where the code can't tell us why. Recommended for "I built fast and want to check whether I'm solving the right problem." ~30–45min.
[C] Forward WB + Gap Analysis — full
/wbfrom scratch (5 stages with approval gates) as if this were greenfield, with the agent reading the existing code during the conversation. At the end, produces agap-analysis.mdcomparing "what we'd build today" vs "what exists." Recommended for "I'm pivoting / re-strategizing / want to revalidate from scratch." ~1–2h.
If the user does not answer or asks the agent to pick, default to A.
These steps form Path A in full. Path B and Path C extend them with additional steps below.
Read the project in breadth, not depth. Goal: a bird's-eye view.
package.json, pyproject.toml, go.mod, pom.xml, Cargo.toml, etc.main, Lambda function entries, controllers, queue consumers, scheduled jobs.github/workflows, .gitlab-ci.yml, buildspec.yml, Jenkinsfile, pipeline configsProduce a brief inventory list. Don't write prose yet.
From the inventory, infer:
.proto files or inferred from code), event topics/queues (publishers, subscribers, payload shapes), CLI commands, MCP tools, etc.patterns/INDEX.md and assess whether each is present, partial, or absent.For each inference, note your confidence level (high / medium / low) and the evidence that supports it (file paths, line ranges, IaC resources). Inferences with low confidence are flagged for the user.
Produce docs/design/<service-name>/design-doc.md using the canonical template (skills/design-document/templates/design-doc-template.md), with these adjustments:
Banner at top — must say:
⚠️ REVERSE-ENGINEERED — produced by
brownfield-discoveryfrom the existing codebase on<date>. Not approved by any bar raiser. Use as context for future changes, not as a historical record of decisions made. Sections marked LOW CONFIDENCE were inferred without strong evidence and should be reviewed.
Per-section confidence: each section ends with a confidence line: [Confidence: HIGH / MEDIUM / LOW] and one sentence on what supports the rating.
Section 1 (Problem Statement) — likely LOW in Path A: the customer problem rarely lives in the code. Pull what you can from the README, docstrings, marketing pages if present; otherwise mark explicitly as "TO BE FILLED — customer context not inferable from code." (In Path B and C, this section is filled more completely — see Steps 7+ below.)
Section 2 (Requirements) — MEDIUM to HIGH for non-functional requirements that show up in code (latency targets in alarms, throughput in autoscaling configs, error budgets in dashboards). Functional requirements: MEDIUM at best — list the observable behaviors the API exposes.
Section 3 (Proposed Architecture) — HIGH confidence: this is the strongest part of reverse-engineering. Diagrams, components, data flows, storage choices.
Section 4 (Alternatives Considered) — NOT INFERABLE. Mark as: "Not reverse-engineered — alternatives considered at original design time are not recoverable from code. Future changes should re-evaluate alternatives in context."
Section 5 (Trade-offs) — MEDIUM: infer from architecture choices made (e.g., "this service uses DynamoDB; the implied trade-off is key-value over ad-hoc query, accepting that analytical queries require a separate path"). Flag inferred trade-offs explicitly.
Section 6 (Cost Estimation) — MEDIUM if billing data accessible; otherwise estimate from infrastructure footprint (instance counts, storage GB, request volume from metrics). Mark assumptions.
Section 7 (Operational Concerns) — HIGH: existing alarms, dashboards, runbooks (if present) are observable directly. List them as-is. Gaps (no alarm for X) are findings, not failures.
Section 8 (Testing Strategy) — HIGH: what tests exist; what's missing.
The Design Doc is not pristine — it carries the project's existing debt visibly. Don't paper over gaps; surface them.
For each API surface identified in step 2, produce the canonical contract artifact (per skills/api-contract-first/SKILL.md mapping):
openapi.yaml exists, link it; if not, generate one from route definitions in code (Express/Fastify routes, FastAPI decorators, Spring @RequestMapping, etc.). Save to docs/design/<service>/openapi.yaml..proto files; if missing (rare), reconstruct from generated stubs.asyncapi.yaml describing channels (queues / topics) and operations (publish / subscribe), plus payload schemas (JSON Schema / Avro / Protobuf) inferred from event producers' code.Each artifact carries a header comment: # REVERSE-ENGINEERED from <source files>. Confidence: HIGH/MEDIUM/LOW. Review before relying on this for client integration.
Produce docs/design/<service>/threat-model.md:
This is not a complete threat model — it's a starting baseline. Mark as such.
For each pattern in patterns/*/PATTERN.md, note: present, partial, or absent in the current architecture. This goes into a section of the Design Doc and into a separate patterns-observed.md, becoming input for future /design invocations that scan the pattern catalog.
Don't recommend pattern changes here — that's a future /design decision. Only document what's there.
After steps 1–6, present the closing summary via AskUserQuestion:
Path A complete. Produced in
docs/design/<service>/:
design-doc.md— confidence: HIGH on architecture/operations, LOW on customer problem and alternatives- API contracts — confidence HIGH (one artifact per protocol used)
threat-model.md— baseline onlypatterns-observed.md[A] Accept as starting context (recommended) [B] Review LOW-confidence sections together [C] Discard
If [A]: save artifacts; brief end-of-onboarding summary; done.
If [B]: walk through LOW-confidence sections; prompt for input; update.
If [C]: delete or move to docs/design/_discarded/.
Skip Steps 7+ if Path A was chosen.
Produce inferred WB artifacts in docs/working-backwards/<service-name>/. Each artifact carries the same banner as the Design Doc — REVERSE-ENGINEERED, INFERRED, with per-section confidence.
Sources for inference:
docs/, especially anything that looks like requirements or design discussionProduce these files (DRAFT, INFERRED):
customer-profile.md — who appears to be the customer based on the artifacts. Confidence will usually be LOW: inferring "who" from code is unreliable.problem-statement.md — what problem the project appears to solve. Pull from README + docs; do not fabricate.solution-sketch.md — the existing system, described in the language of "what this lets the customer do." Higher confidence — derived from API + UI surface.prfaq.md — DRAFT press release + FAQ, with each FAQ answer either filled (from inferable content) or marked TO BE FILLED — needs customer evidence.Mark every section that depends on customer evidence as INFERRED — needs validation. Never fabricate. The customer story is the part that the code cannot answer.
Activate the doc-bar-raiser persona (agents/doc-bar-raiser.md) in "Inferred PR/FAQ review" mode. The persona's job here is not to bless the PR/FAQ — it's to surface the questions the user has to answer themselves by talking to real customers / sponsors / stakeholders.
Produce docs/working-backwards/<service-name>/bar-raiser-questions.md with the structured questions, grouped by section (customer, problem, solution, business case, metrics).
Present via AskUserQuestion:
Path B complete. Produced everything from Path A, plus inferred WB artifacts in
docs/working-backwards/<service>/.Notably: the doc-bar-raiser surfaced N questions where the code cannot tell us why. Strongly recommend you answer them before continuing.
[A] Accept as starting context. I'll keep the bar-raiser questions visible for future invocations. [B] Walk through the bar-raiser questions with me now. [C] Discard the WB artifacts (keep Path A's design artifacts).
Path C is the heaviest path. It is intended for strategic re-evaluation — pivots, major refactors, "we lost our way" moments. It runs the canonical Working Backwards flow with full approval gates, knowing the existing project, and produces a gap analysis at the end.
Hand off to the canonical working-backwards skill (skills/working-backwards/SKILL.md). Run all 5 stages with their mandatory approval gates:
Critical: during this WB run, the agent has read access to the existing project. Use it to:
Equally critical: do not let the existing project bias the WB. The whole point of Path C is to re-derive from the customer outwards. If the WB says "build Y" and Y already exists, that's a useful confirmation. If WB says "build Z" and the system actually does W, that's a strategic gap — record it.
The WB artifacts go to docs/working-backwards/<service>/ as canonical (no INFERRED banner — they were produced through the real WB process with the user).
After WB approval, produce docs/design/<service>/gap-analysis.md:
extend (add to project) / sunset (remove from project) / re-justify (keep but document why) / align (refactor toward the WB target).The recommendations are suggestions for future /design invocations — Path C does not implement them.
Present via AskUserQuestion:
Path C complete. Produced:
- Full canonical WB artifacts in
docs/working-backwards/<service>/- Reverse-engineered design artifacts in
docs/design/<service>/(from steps 1–6)gap-analysis.mdcross-referencing them[A] Accept all. Future
/specand/builduse the design artifacts as anchor; the gap-analysis informs the next/design. [B] Walk through the gap-analysis with me to prioritize next moves. [C] Discard all and go back to default.
| Intention | Mechanism |
|---|---|
| "I'll remember the project's architecture" | Persisted in docs/design/<service>/design-doc.md so the next agent invocation reads it instead of re-inferring |
| "I'll be careful not to break things" | Threat model + existing alarms documented; patterns catalog cross-referenced so future changes know what's load-bearing |
| "We'll add docs later" | Discovery is a one-time investment that pays back on every subsequent /spec and /build |
| "Reverse-engineered docs are as good as designed ones" | Banner + per-section confidence + non-inferable sections marked explicitly |
| What They Say | Why It's Wrong | What To Do Instead |
|---|---|---|
| "We don't have time to onboard the agent on this project" | Without onboarding, the agent re-discovers the project on every invocation, hallucinating interfaces and missing existing constraints. The cost compounds. | Spend the 15-30min once; save it on every subsequent change. |
| "The reverse-engineered Design Doc is good enough as a permanent record" | It's a starting point, not the source of truth. Bar raiser approval is what makes a Design Doc canonical. | Use it as anchor; promote sections to canonical only after a real /design review when scope warrants. |
| "We should reverse-engineer everything before any change" | Diminishing returns. Trivial and small changes don't need the discovery. | Run /onboard only when the next change is medium or larger (per the proportionality ladder). |
| "The agent should figure it out from code each time" | LLMs hallucinate when reading code without anchors. Persisted artifacts are the anchors. | Onboard once; persist; reuse. |
docs/design/<service>/design-doc.md exists with the REVERSE-ENGINEERED banner and per-section confidence.proto / AsyncAPI / etc.)patterns-observed.md/spec and /design invocations are aware of these artifacts (they appear in repo state detection)docs/working-backwards/<service>/ with REVERSE-ENGINEERED, INFERRED banner and per-section confidenceINFERRED — needs validationbar-raiser-questions.md exists with structured hard questions from the doc-bar-raiserworking-backwards skill, with all 5 approval gates honored — these do not carry the INFERRED banner because they came from the user, not from inferencegap-analysis.md exists with capabilities-in-WB / capabilities-built / gaps grouped as extend / sunset / re-justify / align/spec and /build.