skilldrop-cli 0.2.0

package/skills/api-contract-draft/manifest.json

@@ -0,0 +1,11 @@
+{
+  "name": "api-contract-draft",
+  "version": "0.1.0",
+  "description": "Draft an OpenAPI 3.1 contract from a feature brief or story — resource-oriented paths, a full error catalog (RFC 9457), pagination/idempotency/versioning decided not deferred, examples on every operation, plus a decisions log so review argues choices instead of YAML. Use when the user wants to design an API, draft an OpenAPI/Swagger spec, define request/response shapes, or agree a contract between frontend/backend or two teams before code.",
+  "entrypoint": "SKILL.md",
+  "deps": { "npm": [], "pip": [] },
+  "env": { "required": [], "optional": [] },
+  "related": ["council-review", "doc-critique", "guide-builder", "tech-comparison-matrix", "user-story-splitter"],
+  "tags": ["api-design", "openapi", "contract-first", "rest", "swagger", "asyncapi"],
+  "model": { "tier": "standard", "rationale": "Schema synthesis against fixed conventions. The resource modeling needs judgment; the conventions bound it. Escalate via ambiguous-input on contested multi-team contracts." }
+}

package/skills/api-contract-draft/reference.md

@@ -0,0 +1,73 @@
+# api-contract-draft reference — house conventions
+
+These are defaults, not laws: deviate when the brief forces it, and log every deviation in the decisions table with its reason. An unlogged deviation is a bug in the contract.
+
+## Naming & paths
+
+- Resources are **plural nouns**: `/refunds`, `/payment-methods`. Kebab-case in paths, `snake_case` in JSON bodies.
+- No verbs in paths. State changes are either a `PATCH` of a status field or a **sub-resource action collection** when the transition has its own data/lifecycle: ✅ `POST /orders/{id}/cancellations` — ❌ `POST /orders/{id}/cancel` (acceptable only when the action is truly fire-and-forget and modeling it as a resource adds nothing — log it).
+- Nest **one level max** (`/customers/{id}/payment-methods`). Deeper relationships flatten to filters: ✅ `/invoices?customer_id=…` — ❌ `/customers/{id}/orders/{id}/invoices`.
+- IDs are opaque strings with a type prefix in examples (`"ord_8f4k2m"`) — prefixed IDs make logs and support tickets self-describing.
+
+## Errors — RFC 9457 `application/problem+json`
+
+Every error response is a `Problem`:
+
+```yaml
+Problem:
+  type: object
+  required: [type, title, status, code]
+  properties:
+    type: { type: string, format: uri, description: "Stable URI identifying the error class" }
+    title: { type: string, description: "Human summary, not for switching on" }
+    status: { type: integer }
+    code: { type: string, pattern: "^[a-z0-9_]+$", description: "Stable machine-readable code clients switch on" }
+    detail: { type: string }
+    errors: { type: array, description: "Field-level validation failures", items: { type: object, properties: { field: {type: string}, code: {type: string}, message: {type: string} } } }
+```
+
+- Enumerate **every 4xx the operation can produce**, each with its `code` values: `validation_failed`, `idempotency_key_reused`, `insufficient_funds`, …
+- `5xx`: document `500` once globally with a generic Problem; never invent per-operation 500 variants.
+- The `code` list is contract — adding one is additive; changing one is breaking.
+
+## Pagination, filtering, sorting
+
+- **Cursor pagination is the default**: request `?cursor=&limit=` (limit capped, cap stated), response `{ "data": [...], "next_cursor": "..." | null }`. Offset pagination only with a logged reason (e.g. "UI needs page numbers; dataset < 100k and stable").
+- Every list endpoint paginates **from day one** — even "small" lists; retrofitting is a breaking change.
+- Filters are query params named after the field (`?status=pending&created_after=…`). Sorting: `?sort=-created_at` (leading `-` = descending). Document which fields are filterable/sortable — "all of them" is never true.
+
+## Idempotency & retries
+
+- Every **unsafe POST** accepts `Idempotency-Key` (UUID, 24h retention stated). Same key + same body → replay the original response; same key + different body → `409` `idempotency_key_reused`.
+- `PUT` and `DELETE` are idempotent by construction; `DELETE` of a missing resource is `404` first time, `404` every time (not `204` — log if you choose tombstone semantics instead).
+- State the retry guidance in the operation description: which errors are retryable (`503`, `429` with `Retry-After`) and which never are (`4xx` except `429`).
+
+## Versioning
+
+- URL major version: `/v1/`. The policy sentence for `info.description`: *"Additive changes (new optional fields, new endpoints, new enum values where the field is documented as open) do not bump the version; removals, renames, type changes, and semantic changes do."*
+- Mark enums **open or closed** explicitly (`x-extensible-enum` note or description) — clients must know whether to tolerate unknown values.
+- Deprecation: `deprecated: true` + `Sunset` header mention + the replacement named in the description. No silent removals, ever.
+
+## Field typing rules
+
+| Concern | Rule |
+|---|---|
+| Money | Integer minor units + ISO-4217 `currency` field. Float money fails review. |
+| Timestamps | `type: string, format: date-time`, UTC, ISO-8601. Field names end `_at`. |
+| IDs | `type: string` opaque; never `integer` (leaks sequence, blocks resharding). |
+| Enums | `enum: [...]` with every value, plus open/closed declared. |
+| Free text | `maxLength` always — unbounded strings are a storage and abuse contract. |
+| Booleans | Name as predicate: `is_default`, `has_failed`. Never tri-state a boolean — use an enum. |
+| Optionality | `required` array on every object schema; absent ≠ null — pick one and state it. |
+| Quantities | `minimum`/`maximum` on every numeric the business bounds. |
+
+## Request/response shape separation
+
+Per resource, three schemas minimum: `{Resource}` (response), `{Resource}CreateRequest`, `{Resource}UpdateRequest`. Server-set fields (`id`, `created_at`, `status` when machine-driven) appear **only** in the response schema. The update schema has no required fields (PATCH semantics) unless the business requires atomically-paired fields — log that decision.
+
+## Event/webhook contracts (AsyncAPI-shaped)
+
+- Channel names: `{domain}.{resource}.{event}` past-tense — `payments.refund.completed`.
+- Payload: the same typing rigor; include `event_id` (UUID, for consumer dedupe), `occurred_at`, and a `schema_version`.
+- Delivery semantics stated per channel: default **at-least-once** — consumers must dedupe on `event_id`; say so in the channel description.
+- Webhooks out: HMAC signature header named, timestamp-skew window stated, retry schedule with backoff and a cap, and the consumer's expected 2xx contract ("respond 2xx within 10s; processing happens async on your side").

package/skills/api-contract-draft/templates/openapi-skeleton.yaml

@@ -0,0 +1,148 @@
+# OpenAPI 3.1 skeleton — one fully-worked resource (refunds) showing every convention.
+# Replace the resource; keep the structure, the Problem schema, and the security wiring.
+openapi: 3.1.0
+info:
+  title: "{Service} API"
+  version: "1.0.0"
+  license: { name: "{license, e.g. Proprietary}" }
+  description: |
+    Versioning policy: additive changes (new optional fields, new endpoints, new enum
+    values on open enums) do not bump the major version; removals, renames, type
+    changes, and semantic changes do. Deprecated operations carry `deprecated: true`,
+    a Sunset header, and a named replacement.
+servers:
+  - url: https://api.example.com/v1
+security:
+  - bearerAuth: []
+paths:
+  /refunds:
+    post:
+      operationId: createRefund
+      summary: Request a refund for a captured payment
+      description: |
+        Retry guidance: retryable on 429 (honor Retry-After) and 503; never retryable
+        on other 4xx. Replays with the same Idempotency-Key return the original response.
+      parameters:
+        - name: Idempotency-Key
+          in: header
+          required: true
+          schema: { type: string, format: uuid }
+          description: Retained 24h. Same key + different body returns 409.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: "#/components/schemas/RefundCreateRequest" }
+            example:
+              payment_id: "pay_8f4k2mq7"
+              amount: 2500
+              currency: "EUR"
+              reason: "customer_request"
+      responses:
+        "201":
+          description: Refund created and queued for processing.
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/Refund" }
+              example:
+                id: "ref_3j9x1pd4"
+                payment_id: "pay_8f4k2mq7"
+                amount: 2500
+                currency: "EUR"
+                reason: "customer_request"
+                status: "pending"
+                created_at: "2026-06-10T14:02:11Z"
+        "400":
+          description: "Validation failed. codes: validation_failed"
+          content: { application/problem+json: { schema: { $ref: "#/components/schemas/Problem" } } }
+        "402":
+          description: "Refund exceeds refundable balance. codes: insufficient_refundable_amount"
+          content: { application/problem+json: { schema: { $ref: "#/components/schemas/Problem" } } }
+        "404":
+          description: "Payment not found. codes: payment_not_found"
+          content: { application/problem+json: { schema: { $ref: "#/components/schemas/Problem" } } }
+        "409":
+          description: "Idempotency conflict. codes: idempotency_key_reused"
+          content: { application/problem+json: { schema: { $ref: "#/components/schemas/Problem" } } }
+    get:
+      operationId: listRefunds
+      summary: List refunds
+      parameters:
+        - { name: cursor, in: query, schema: { type: string } }
+        - { name: limit, in: query, schema: { type: integer, minimum: 1, maximum: 100, default: 25 } }
+        - { name: payment_id, in: query, schema: { type: string } }
+        - { name: status, in: query, schema: { $ref: "#/components/schemas/RefundStatus" } }
+        - { name: sort, in: query, schema: { type: string, enum: ["created_at", "-created_at"], default: "-created_at" } }
+      responses:
+        "200":
+          description: Paginated refunds, newest first by default.
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [data, next_cursor]
+                properties:
+                  data: { type: array, items: { $ref: "#/components/schemas/Refund" } }
+                  next_cursor: { type: [string, "null"] }
+  /refunds/{refund_id}:
+    get:
+      operationId: getRefund
+      summary: Fetch one refund
+      parameters:
+        - { name: refund_id, in: path, required: true, schema: { type: string } }
+      responses:
+        "200":
+          description: The refund.
+          content: { application/json: { schema: { $ref: "#/components/schemas/Refund" } } }
+        "404":
+          description: "codes: refund_not_found"
+          content: { application/problem+json: { schema: { $ref: "#/components/schemas/Problem" } } }
+components:
+  securitySchemes:
+    bearerAuth: { type: http, scheme: bearer, bearerFormat: JWT }
+  schemas:
+    RefundStatus:
+      type: string
+      description: "Closed enum — clients may exhaustively switch."
+      enum: [pending, processing, succeeded, failed]
+    RefundCreateRequest:
+      type: object
+      required: [payment_id, amount, currency]
+      properties:
+        payment_id: { type: string, maxLength: 64 }
+        amount: { type: integer, minimum: 1, description: "Minor units (cents)." }
+        currency: { type: string, pattern: "^[A-Z]{3}$", description: "ISO 4217." }
+        reason:
+          type: string
+          description: "Open enum — clients must tolerate unknown values."
+          enum: [customer_request, duplicate, fraud, other]
+    Refund:
+      type: object
+      required: [id, payment_id, amount, currency, status, created_at]
+      properties:
+        id: { type: string }
+        payment_id: { type: string }
+        amount: { type: integer, minimum: 1 }
+        currency: { type: string, pattern: "^[A-Z]{3}$" }
+        reason: { type: string, enum: [customer_request, duplicate, fraud, other] }
+        status: { $ref: "#/components/schemas/RefundStatus" }
+        failure_code: { type: [string, "null"], description: "Set only when status=failed." }
+        created_at: { type: string, format: date-time }
+    Problem:
+      type: object
+      required: [type, title, status, code]
+      properties:
+        type: { type: string, format: uri }
+        title: { type: string }
+        status: { type: integer }
+        code: { type: string, pattern: "^[a-z0-9_]+$" }
+        detail: { type: string }
+        errors:
+          type: array
+          items:
+            type: object
+            required: [field, code]
+            properties:
+              field: { type: string }
+              code: { type: string }
+              message: { type: string }

package/skills/architecture-diagrams/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: architecture-diagrams
+description: Generate architecture diagrams (Mermaid, PlantUML, C4) from a written description of a system. Supports AWS/Azure/GCP cloud topologies, microservice landscapes, sequence flows, container diagrams, and ER models. Use whenever the user asks for an architecture diagram, system sketch, flow diagram, or visualization of a design.
+---
+
+# architecture-diagrams
+
+You help the user turn a written system description into a clean, renderable architecture diagram.
+
+## How to respond
+
+1. **Clarify only what blocks correctness.** Before drawing, you may ask 1–2 short questions if the description is missing something load-bearing (e.g., "Is auth synchronous or via a sidecar?"). Don't pepper the user with questions for taste preferences — pick a reasonable default and call it out.
+
+2. **Pick the right notation.** Use this rough mapping unless the user requests otherwise:
+
+   | User's intent | Use |
+   |---|---|
+   | Cloud architecture (AWS/Azure/GCP) — boxes, arrows, services | **Mermaid** `flowchart` or `graph` |
+   | Request flow across services / call order matters | **Mermaid** `sequenceDiagram` |
+   | Strategic / multi-level view (context → container → component) | **C4 (PlantUML !include c4)** |
+   | Data model, tables, relationships | **Mermaid** `erDiagram` |
+   | State machine / workflow | **Mermaid** `stateDiagram-v2` |
+   | Class / type hierarchy | **Mermaid** `classDiagram` |
+   | Looks-pretty UML-style for slides | **PlantUML** |
+
+3. **Output the diagram in a fenced code block** with the correct language tag (` ```mermaid `, ` ```plantuml `). Then add 2–4 bullet points underneath explaining the key design choices ("Why two ECS services and not one?") so the diagram is reviewable, not just renderable.
+
+4. **Offer next steps**, e.g., "Want me to export this as SVG via the Mermaid CLI?" or "Want me to push this into a Figma file? (use the `figma-diagrams` skill)".
+
+## Useful references in this skill
+
+When you need a starting shape, copy from one of the templates rather than inventing notation from scratch — it cuts down on syntax errors and keeps style consistent across diagrams.
+
+- [`templates/mermaid-flowchart.md`](templates/mermaid-flowchart.md) — basic boxes-and-arrows starter
+- [`templates/mermaid-sequence.md`](templates/mermaid-sequence.md) — sequenceDiagram with actors and async messages
+- [`templates/mermaid-aws.md`](templates/mermaid-aws.md) — AWS-flavoured flowchart using emojis as service icons
+- [`templates/c4-container.puml`](templates/c4-container.puml) — C4 container diagram skeleton (PlantUML)
+
+Worked examples to learn from:
+
+- [`examples/aws-three-tier.md`](examples/aws-three-tier.md) — three-tier web app on AWS, Mermaid flowchart
+- [`examples/microservices-sequence.md`](examples/microservices-sequence.md) — order-placement flow across 4 services
+- [`examples/c4-container-saas.md`](examples/c4-container-saas.md) — SaaS app, C4 container level
+
+## Quality bar
+
+A good diagram from this skill should:
+
+- **Fit on one screen.** If you have more than ~15 nodes, split into two diagrams (e.g., "Context" and "Container") rather than cramming everything in.
+- **Show direction of data flow,** not just connections. Arrows should mean something.
+- **Label every arrow** that crosses a trust boundary or a network hop.
+- **Use subgraphs / groups** to make zones explicit (VPC, public/private subnets, account boundaries, on-prem vs cloud).
+- **Be valid syntax.** Mentally trace through the Mermaid/PlantUML once before responding. Common breakers: unescaped `(` `)` `<` `>` inside labels, missing `end` for subgraphs, mixing graph types.
+
+## What this skill does NOT do
+
+- It doesn't render to PNG/SVG itself. To render, suggest the user use the Mermaid Live Editor (https://mermaid.live), the Mermaid CLI (`mmdc`), or the VS Code Mermaid preview.
+- It doesn't push to Figma directly. For that, hand off to the [`figma-diagrams`](../figma-diagrams/SKILL.md) skill.
+- It doesn't generate Visio/Lucid native files.
+
+## Anti-patterns to avoid
+
+- ❌ Inventing service names ("ServiceA", "ServiceB"). Use the user's vocabulary or ask.
+- ❌ Putting every box at the top level. Group by concern.
+- ❌ Mermaid flowchart with 30+ nodes — split it.
+- ❌ Using a sequence diagram when the user asked "what does the system look like" — that's a structural question, use a flowchart or C4.

package/skills/architecture-diagrams/examples/aws-three-tier.md

@@ -0,0 +1,44 @@
+# Example: Three-tier web app on AWS
+
+**Prompt the user gave:** *"Draw me a three-tier web app on AWS with an ALB, two ECS services (web + worker), and an RDS Postgres backend."*
+
+**Response:**
+
+```mermaid
+flowchart TB
+    Internet([🌐 Internet])
+
+    subgraph AWS["☁️ AWS us-east-1"]
+        subgraph VPC["🛡️ VPC 10.0.0.0/16"]
+            subgraph PubSub["Public subnet"]
+                ALB[🔀 Application Load Balancer]
+            end
+            subgraph PrivSub["Private subnet"]
+                Web[📦 ECS web service]
+                Worker[📦 ECS worker service]
+            end
+            subgraph DataSub["Data subnet"]
+                RDS[(🐘 RDS Postgres Multi-AZ)]
+            end
+        end
+        SQS{{📨 SQS jobs}}
+        S3[(🪣 S3 user uploads)]
+    end
+
+    Internet -->|HTTPS 443| ALB
+    ALB -->|HTTP 8080| Web
+    Web -->|SQL| RDS
+    Web -->|enqueue| SQS
+    Worker -->|dequeue| SQS
+    Worker -->|SQL| RDS
+    Web -.signed URLs.-> S3
+```
+
+**Design notes:**
+
+- **Why two ECS services and not one?** Long-running background work (image resize, email, exports) needs its own scaling profile and shouldn't share CPU with request-serving containers.
+- **RDS Multi-AZ** for automatic failover — single-AZ is fine for dev/test but rarely acceptable in production for a three-tier app.
+- **Uploads bypass the API** via S3 pre-signed URLs to avoid a 100 MB file streaming through ECS containers.
+- **No NAT gateway shown** — add one (or VPC endpoints) if the private subnet containers need to reach S3/SQS over the AWS network without a public IP.
+
+**Want to extend?** Common follow-ups: add CloudFront in front of ALB, add ElastiCache Redis for sessions, add WAF rules, split into multi-region active/passive.

package/skills/architecture-diagrams/examples/c4-container-saas.md

@@ -0,0 +1,51 @@
+# Example: C4 container diagram for a SaaS app
+
+**Prompt the user gave:** *"Give me a C4 container view of a B2B SaaS app — single tenant per database schema, with Stripe for billing."*
+
+**Response:**
+
+```plantuml
+@startuml
+!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Container.puml
+
+LAYOUT_WITH_LEGEND()
+
+title Container diagram — Acme SaaS
+
+Person(admin, "Tenant admin", "Configures workspace, invites users")
+Person(user, "End user", "Day-to-day usage")
+
+System_Boundary(saas, "Acme SaaS") {
+    Container(web, "Web app", "Next.js", "Tenant-aware UI")
+    Container(api, "API", "Node, Fastify", "REST/JSON, business logic")
+    Container(worker, "Worker", "Python, Celery", "Async jobs, billing sync")
+    ContainerDb(db, "Tenant DB", "Postgres", "One schema per tenant")
+    ContainerDb(cache, "Cache", "Redis", "Session + rate-limit")
+    ContainerQueue(queue, "Job queue", "SQS", "Async work")
+}
+
+System_Ext(stripe, "Stripe", "Subscriptions + invoicing")
+System_Ext(idp, "Auth0", "OIDC identity provider")
+System_Ext(post, "Postmark", "Transactional email")
+
+Rel(admin, web, "Uses", "HTTPS")
+Rel(user, web, "Uses", "HTTPS")
+Rel(web, idp, "Auth (OIDC)", "HTTPS")
+Rel(web, api, "Calls", "HTTPS / JSON")
+Rel(api, db, "Reads/writes (per-tenant schema)", "SQL")
+Rel(api, cache, "Reads/writes", "RESP")
+Rel(api, queue, "Publishes", "HTTPS")
+Rel(worker, queue, "Consumes", "HTTPS")
+Rel(worker, db, "Reads/writes", "SQL")
+Rel(worker, stripe, "Syncs subscriptions", "HTTPS")
+Rel(worker, post, "Sends mail", "HTTPS")
+Rel(stripe, api, "Webhooks (invoice.*)", "HTTPS")
+@enduml
+```
+
+**Design notes:**
+
+- **One schema per tenant** is shown via the relationship label on `api -> db` — keeps the diagram clean while making the isolation strategy reviewable.
+- **Webhooks back from Stripe** (note arrow reversal) — a common trip-up; if it's missing, billing state drift is hard to debug.
+- **Worker hits external services**, not the API — avoids the API being a chokepoint for outbound integrations and keeps retries close to the queue.
+- For **context-level** (one box per system, no internals), drop everything inside `System_Boundary` and replace with one `System(saas, ...)`. For **component-level** (one container's internals), drill into `api` with `C4_Component.puml`.

package/skills/architecture-diagrams/examples/microservices-sequence.md

@@ -0,0 +1,49 @@
+# Example: Order placement across microservices
+
+**Prompt the user gave:** *"Show me the sequence of calls when a customer places an order — we have an Order service, an Inventory service, a Payment service, and a Notification service."*
+
+**Response:**
+
+```mermaid
+sequenceDiagram
+    autonumber
+    actor C as Customer
+    participant W as Web frontend
+    participant O as Order service
+    participant I as Inventory service
+    participant P as Payment service
+    participant N as Notification service
+    participant Q as Event bus
+
+    C->>W: Click "Place order"
+    W->>O: POST /orders
+    O->>I: Reserve(items)
+    alt items in stock
+        I-->>O: ReservationId
+        O->>P: Charge(amount, cardToken)
+        alt payment OK
+            P-->>O: PaymentId
+            O->>Q: Publish OrderPlaced
+            O-->>W: 201 Created
+            W-->>C: "Order confirmed"
+            Q-->>N: OrderPlaced
+            N->>C: Email + push notification
+        else payment declined
+            P-->>O: 402 Declined
+            O->>I: Release(reservationId)
+            O-->>W: 402 Payment failed
+            W-->>C: "Card declined"
+        end
+    else out of stock
+        I-->>O: 409 OutOfStock
+        O-->>W: 409 Unavailable
+        W-->>C: "Sold out"
+    end
+```
+
+**Design notes:**
+
+- **Two-step inventory** (reserve → confirm) avoids the classic race where two customers buy the last unit between stock-check and charge.
+- **Compensating action** (`Release`) on payment failure — explicit in the diagram so reviewers can spot the rollback gap if it's missing.
+- **Notification is async** (event bus, dashed line) — slow email shouldn't block the customer's response.
+- **`autonumber`** makes every step referenceable in design-review comments ("what happens at step 8?").

package/skills/architecture-diagrams/manifest.json

@@ -0,0 +1,28 @@
+{
+  "name": "architecture-diagrams",
+  "version": "0.1.0",
+  "description": "Generate architecture diagrams (Mermaid, PlantUML, C4) from a written description of a system. Supports AWS/Azure/GCP cloud topologies, microservice landscapes, sequence flows, container diagrams, and ER models. Use whenever the user asks for an architecture diagram, system sketch, flow diagram, or visualization of a design.",
+  "entrypoint": "SKILL.md",
+  "deps": {
+    "npm": [],
+    "pip": []
+  },
+  "env": {
+    "required": [],
+    "optional": []
+  },
+  "related": [
+    "figma-diagrams"
+  ],
+  "tags": [
+    "diagrams",
+    "mermaid",
+    "plantuml",
+    "c4",
+    "architecture"
+  ],
+  "model": {
+    "tier": "standard",
+    "rationale": "Prose to diagram syntax. Correctness matters; reasoning is bounded."
+  }
+}

package/skills/architecture-diagrams/templates/c4-container.puml

@@ -0,0 +1,31 @@
+@startuml
+!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Container.puml
+
+LAYOUT_WITH_LEGEND()
+
+title Container diagram for <System name>
+
+Person(user, "End user", "Description of who this is")
+
+System_Boundary(sys, "<System name>") {
+    Container(web, "Web application", "React, TypeScript", "Customer-facing UI")
+    Container(api, "API", "Node, Express", "REST API, business logic")
+    Container(worker, "Background worker", "Python, Celery", "Async jobs, retries")
+    ContainerDb(db, "Primary DB", "PostgreSQL 16", "Customer + transactional data")
+    ContainerDb(cache, "Cache", "Redis 7", "Session + hot lookups")
+    ContainerQueue(queue, "Job queue", "RabbitMQ", "Async work coordination")
+}
+
+System_Ext(stripe, "Stripe", "Payment provider")
+System_Ext(ses, "AWS SES", "Transactional email")
+
+Rel(user, web, "Uses", "HTTPS")
+Rel(web, api, "Calls", "HTTPS / JSON")
+Rel(api, db, "Reads/writes", "SQL/TCP")
+Rel(api, cache, "Reads/writes", "RESP")
+Rel(api, queue, "Publishes jobs", "AMQP")
+Rel(worker, queue, "Consumes jobs", "AMQP")
+Rel(worker, db, "Reads/writes", "SQL/TCP")
+Rel(api, stripe, "Charges", "HTTPS / JSON")
+Rel(worker, ses, "Sends email", "HTTPS / JSON")
+@enduml

package/skills/architecture-diagrams/templates/mermaid-aws.md

@@ -0,0 +1,52 @@
+# AWS-flavoured Mermaid starter
+
+Mermaid doesn't ship native AWS icons, but emojis + clear naming get you 80% of the visual clarity for free, and the diagram still renders anywhere Markdown does.
+
+```mermaid
+flowchart TB
+    Internet([🌐 Internet])
+
+    subgraph AWS["☁️ AWS — us-east-1"]
+        subgraph VPC["🛡️ VPC 10.0.0.0/16"]
+            subgraph Public["Public subnet"]
+                ALB[🔀 ALB]
+            end
+            subgraph Private["Private subnet"]
+                ECS1[📦 ECS web]
+                ECS2[📦 ECS worker]
+            end
+            subgraph DataZone["Data"]
+                RDS[(🐘 RDS Postgres)]
+                Redis[(⚡ ElastiCache)]
+            end
+        end
+        S3[(🪣 S3 assets)]
+        SQS{{📨 SQS queue}}
+    end
+
+    Internet --> ALB --> ECS1
+    ECS1 --> Redis
+    ECS1 --> RDS
+    ECS1 --> SQS --> ECS2
+    ECS2 --> RDS
+    ECS1 -.reads.-> S3
+```
+
+## Service → emoji cheat sheet
+
+| Service | Emoji | Service | Emoji |
+|---|---|---|---|
+| EC2 / ECS / Fargate | 📦 | RDS / Aurora | 🐘 |
+| Lambda | λ or ⚡ | DynamoDB | 🗄️ |
+| S3 | 🪣 | ElastiCache | ⚡ |
+| ALB / NLB / API GW | 🔀 | CloudFront | 🌍 |
+| SQS / SNS | 📨 | EventBridge | 🚌 |
+| Cognito / IAM | 🔐 | KMS | 🔑 |
+| Route 53 | 🧭 | CloudWatch | 📊 |
+
+## Tips
+
+- Use `subgraph` to make VPC → subnet → service nesting visible — it's the single biggest readability win.
+- Mark public vs private subnets explicitly.
+- Dotted arrows (`-.label.->`) for async / read-only / observability paths so the primary request path stays prominent.
+- For multi-region, draw one region in detail and a thin "replica" box for the others, with a labeled arrow between them.

package/skills/architecture-diagrams/templates/mermaid-flowchart.md

@@ -0,0 +1,37 @@
+# Mermaid flowchart starter
+
+Use for: boxes-and-arrows structural diagrams. Top-down (`TD`) reads like a deployment stack; left-right (`LR`) reads like a request flow.
+
+```mermaid
+flowchart LR
+    User([User])
+
+    subgraph Edge["Edge"]
+        CDN[CDN]
+        WAF[WAF]
+    end
+
+    subgraph App["App tier"]
+        LB[Load balancer]
+        Web1[Web server 1]
+        Web2[Web server 2]
+    end
+
+    subgraph Data["Data tier"]
+        DB[(Primary DB)]
+        Cache[(Cache)]
+    end
+
+    User --> CDN --> WAF --> LB
+    LB --> Web1 & Web2
+    Web1 & Web2 --> Cache
+    Web1 & Web2 --> DB
+```
+
+## Tips
+
+- `[Box]` rectangle · `([Stadium])` user/external · `[(Cylinder)]` database · `{Diamond}` decision · `>Flag]` event
+- Use `&` to fan-out from one source to many destinations: `LB --> Web1 & Web2 & Web3`
+- Use `subgraph Name["Display label"]` to draw zones (VPC, account, region)
+- Annotate links with `--label-->` to name the arrow
+- Pick *one* direction (`TD`, `LR`) per diagram; mixing kills readability

package/skills/architecture-diagrams/templates/mermaid-sequence.md

@@ -0,0 +1,39 @@
+# Mermaid sequence diagram starter
+
+Use for: showing the **order** of messages between participants. Best when "who calls whom in what order" is the question.
+
+```mermaid
+sequenceDiagram
+    autonumber
+    actor User
+    participant Web as Web app
+    participant API as API gateway
+    participant Auth as Auth service
+    participant DB as Database
+
+    User->>Web: Click "sign in"
+    Web->>API: POST /login {email, pwd}
+    API->>Auth: Validate credentials
+    Auth->>DB: SELECT user WHERE email=?
+    DB-->>Auth: User row
+    Auth-->>API: JWT (15 min) + refresh
+    API-->>Web: Set-Cookie, 200 OK
+    Web-->>User: Dashboard
+
+    Note over API,Auth: All hops over mTLS
+```
+
+## Tips
+
+- `->>` solid arrow (call) · `-->>` dashed arrow (return/async) · `-x` lost message
+- `autonumber` adds 1, 2, 3 to each step — great for design reviews
+- `Note over A,B: text` annotates a span; `Note left of A: text` annotates one side
+- `loop`, `alt`/`else`, `par` for control flow:
+  ```
+  alt token valid
+      API-->>Web: 200
+  else token expired
+      API-->>Web: 401
+  end
+  ```
+- Don't overuse — past ~12 messages it becomes a wall. Split into "happy path" and "error path" diagrams.