skilldrop-cli 0.2.0

package/skills/release-notes/templates/release-notes.md

@@ -0,0 +1,83 @@
+# Release-notes templates
+
+Two artifacts, two readers. Customer notes sell nothing and explain everything; the internal changelog trades polish for traceability.
+
+## Artifact 1 — customer-facing release notes
+
+> Note the deliberate rename for a non-technical reader: the Keep-a-Changelog categories **Added → New** and **Changed → Improved** here; Fixed/Security keep their names. The internal changelog (Artifact 2) uses the canonical Keep-a-Changelog headings.
+
+```markdown
+# {Product} {version} — {YYYY-MM-DD}
+
+> Covers {ref}..{ref} · {N} changes
+
+## ⚠ Breaking changes
+
+- **{What broke, in reader terms.}**
+  Action required: {the exact step — config to change, endpoint to migrate, deadline}.
+  (flagged by: {signal — `!:` marker / removed API / migration file})
+
+## New
+
+- {What the reader can now do. One sentence, benefit first.}
+
+## Improved
+
+- {What got better, measurably where possible: "export is ~3× faster on reports over 10k rows".}
+
+## Fixed
+
+- {The symptom the reader no longer suffers: "Fixed a crash when …", "Dates no longer shift by one day when …".}
+
+## Security
+
+- {Reader-relevant statement; severity and affected versions; no exploit detail.}
+```
+
+Rules: no class/function/service names, no ticket IDs, no author names, no "various improvements". A section with nothing in it is deleted, not left empty — except Breaking changes, which when empty becomes the single line "No breaking changes."
+
+## Artifact 2 — internal changelog (Keep a Changelog)
+
+```markdown
+## [{version}] - {YYYY-MM-DD}
+
+Range: `{ref}..{ref}` · {N} commits · {N} PRs
+
+### Added
+- {change} ({#PR}, `{hash}`)
+
+### Changed
+- **BREAKING:** {change + migration step} ({#PR}, `{hash}`)
+- {change} ({#PR}, `{hash}`)
+
+### Fixed
+- {change} ({#PR}, `{hash}`)
+
+### Deprecated / Removed / Security
+- {change} ({#PR}, `{hash}`)
+
+### Internal
+- {refactor / CI / deps / tests — one line each} (`{hash}`)
+```
+
+## Needs review (always emitted, both modes)
+
+```markdown
+## Needs review — {N} commits not classified
+
+| Hash | Subject | Why unclear |
+|---|---|---|
+| `{hash}` | {verbatim subject} | {vague / contradicts diff / can't tell if user-visible} |
+```
+
+## Classification cheat-sheet
+
+| Signal | Bucket |
+|---|---|
+| New endpoint, flag default-on, new UI surface | Added |
+| Behavior or default changed for existing users | Changed (BREAKING if old behavior unobtainable) |
+| `fix:`, bug ticket, regression revert | Fixed |
+| `chore:`, `refactor:`, `test:`, `ci:`, deps, lockfiles | Internal |
+| CVE, auth/authz, input validation, secrets | Security |
+| `feat!:`, `BREAKING CHANGE:`, removed public API, schema migration, major version bump of a public SDK | Breaking — hoist to top |
+| "wip", "fix stuff", "address comments", empty body + vague subject | Needs review |

package/skills/requirements-interview/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: requirements-interview
+description: Generate per-stakeholder interview kits for feature discovery — ≤7 questions per stakeholder ranked by how much the answer changes the design, each naming the decision it informs, with at least one disconfirming question per script and an assumptions-to-validate ledger. Use when the user is gathering business requirements, preparing stakeholder or user interviews, or asks "what should I ask the sponsor/users/ops before we build this".
+---
+
+# requirements-interview
+
+Builds the elicitation kit for the conversations *before* the PRD — so the answers come back in a shape `brief-intake` and `prd-draft` can consume, instead of as ten pages of agreement with the roadmap. The discipline: every question names the decision it informs, problems are asked about instead of solutions, and every script tries at least once to kill the feature.
+
+## How to respond
+
+1. **Pin the feature idea and identify the stakeholder cast.** From the idea, derive who holds which unknowns — typically: **sponsor** (success definition, constraints, appetite), **end users** (the actual workflow and workarounds — interview the people who do the work, not their manager), **ops/support** (failure modes, ticket reality, operational cost), **security/compliance/legal** (data constraints, regulatory floor), **finance/commercial** (pricing, cost ceiling) when money moves. Ask the user at most 2 questions — who's available, and what's already known — then build kits only for stakeholders who hold *open* unknowns. No interview exists to confirm what's already evidenced.
+
+2. **Write ≤7 questions per stakeholder, ranked by design impact.** Rank 1 is the answer that most changes what gets built. Each question carries two annotations: **informs** (the decision) and **if-answer-is-X-then** (how the design moves). A question that wouldn't change anything regardless of answer doesn't make the seven. ✅ *"Walk me through the last time you handled a refund request — every tool you touched."* (informs: scope of integration; if 3+ tools → unified view is the core, not a nicety) — ❌ *"Would a refund dashboard be useful?"* (everyone says yes to free things).
+
+3. **Ask about problems and the past, never solutions and the hypothetical.** People are reliable witnesses of what they *did* and unreliable predictors of what they'd *use*. ✅ *"What did you do the last time X failed?"* — ❌ *"Would you use a feature that prevents X?"*. Solutions offered by stakeholders get recorded as evidence of pain, then converted back into the underlying problem.
+
+4. **Include at least one disconfirming question per script** — the question whose answer could kill or shrink the feature: ✅ *"If this never gets built, what would you do instead — and how bad is that, honestly?"* / *"Who would be annoyed if we built this?"*. A kit with no kill-question is a confirmation ritual with a calendar invite.
+
+5. **Add the workflow-walkthrough opener for end users.** First substantive question is always a concrete recent episode ("the last time", "yesterday's"), not a generality ("typically", "usually") — generalities retrieve self-image; episodes retrieve facts. Instruct the interviewer to capture **verbatim quotes** — they become the evidence tags in `prd-draft`.
+
+6. **Build the assumptions-to-validate ledger.** Every assumption the feature idea rests on, each mapped to: which stakeholder's which question validates it, and **what answer falsifies it**. An assumption no question can falsify gets flagged — it needs data or a prototype, not an interview.
+
+7. **Emit with [`templates/interview-kit.md`](templates/interview-kit.md)**: one kit per stakeholder (30-minute shape: opener episode → ranked questions → kill-question → "who else should I talk to"), the assumptions ledger, and the synthesis instruction — notes go to `brief-intake` (one brief per interview, then merge) and decisions surface via `decision-log`.
+
+## Useful references in this skill
+
+- [`templates/interview-kit.md`](templates/interview-kit.md) — per-stakeholder kit skeleton + the assumptions ledger
+
+## Quality bar
+
+- **≤7 questions per stakeholder, ranked**, each annotated with the decision it informs and how the answer moves the design. Unannotated questions don't ship.
+- **Zero leading questions in discovery position.** Anything shaped "wouldn't it be great if…" or answerable with a polite yes fails the kit.
+- **Every script contains a kill-question** — and the kit says what a kill-answer looks like, so the interviewer recognizes it instead of softening it.
+- **End-user scripts open with a concrete recent episode**, never "typically".
+- **Every assumption in the ledger has a falsification condition.** "We'll validate adoption appetite" without what-would-disprove-it is theater.
+- **The synthesis path is named.** Kits that don't say where the notes go produce interviews that end at the notes.
+
+## When to use this skill
+
+- ✅ Discovery phase before a PRD — deciding what to ask whom
+- ✅ "What should I ask the sponsor / users / ops about this feature?"
+- ✅ A feature idea built on untested assumptions that interviews could falsify
+- ✅ Preparing a requirements workshop's pre-read questions
+
+## When NOT to use this skill
+
+- ❌ The answers already exist in tickets, analytics, or support logs — mine those first; interviews are for what data can't say
+- ❌ Synthesizing notes after the interviews — that's `brief-intake` + `decision-log`
+- ❌ Writing the requirements themselves — `prd-draft`, after the interviews
+- ❌ Usability testing of an existing design — different method; this is problem discovery
+
+## Anti-patterns to avoid
+
+- ❌ **The 25-question interrogation.** Past seven, answers degrade into politeness; the ranking exists because time runs out before questions do.
+- ❌ **Confirmation safari.** Every question shaped so yes means "build it" — discovery that can't disconfirm isn't discovery.
+- ❌ **Asking for the solution.** "What should we build?" outsources design to whoever's loudest; ask what hurts, design later.
+- ❌ **Interviewing the manager about the worker's workflow.** Managers describe the process diagram; workers describe the workarounds — the requirements live in the workarounds.
+- ❌ **Skipping ops/support.** They hold the failure-mode requirements nobody else knows exist, and they're the cheapest interview on the list.
+- ❌ **Hypothetical futures.** "Would you use…" — the answer is always yes and always worthless; ask about the last time, not the next time.
+- ❌ **One loud stakeholder = the requirements.** The kit covers the cast precisely so one vivid interview doesn't become the spec.

package/skills/requirements-interview/manifest.json

@@ -0,0 +1,11 @@
+{
+  "name": "requirements-interview",
+  "version": "0.1.0",
+  "description": "Generate per-stakeholder interview kits for feature discovery — ≤7 questions per stakeholder ranked by how much the answer changes the design, each naming the decision it informs, with at least one disconfirming question per script and an assumptions-to-validate ledger. Use when the user is gathering business requirements, preparing stakeholder or user interviews, or asks \"what should I ask the sponsor/users/ops before we build this\".",
+  "entrypoint": "SKILL.md",
+  "deps": { "npm": [], "pip": [] },
+  "env": { "required": [], "optional": [] },
+  "related": ["brief-intake", "decision-log", "prd-draft"],
+  "tags": ["discovery", "interviews", "requirements", "elicitation", "stakeholders", "user-research"],
+  "model": { "tier": "standard", "rationale": "Question banks are rubric-shaped, but ranking by design impact and deriving falsification conditions for the specific feature is synthesis — above light." }
+}

package/skills/requirements-interview/templates/interview-kit.md

@@ -0,0 +1,63 @@
+# Interview-kit template
+
+One kit per stakeholder. 30-minute shape: episode opener → ranked questions → kill-question → referral close. Capture verbatim quotes — they become `prd-draft` evidence tags.
+
+```markdown
+# Interview kit: {feature idea}
+
+**Stakeholders covered:** {list — only those holding open unknowns}
+**Already known (don't re-ask):** {evidence that exists: analytics, tickets, prior research}
+
+---
+
+## Kit: {stakeholder role, e.g. "End user — support agent"}
+
+**Holds the unknowns about:** {what only this person can answer}
+**Time:** 30 min · **Record verbatim quotes**
+
+### Opener (end users: concrete recent episode, never "typically")
+
+1. "Walk me through the last time you {did the task}. Every tool you touched, start to finish."
+   - *informs:* {decision} · *if {answer-shape} then:* {how the design moves}
+
+### Ranked questions (≤7 total including opener and kill-question)
+
+2. "{question}"
+   - *informs:* {decision} · *if X then:* {design consequence}
+3. …
+
+### Kill-question (mandatory)
+
+n. "If this never gets built, what would you do instead — honestly, how bad is that?"
+   - *a kill-answer looks like:* {e.g. "shrug + existing workaround under 2 min" → feature shrinks or dies; write it down, don't soften it}
+
+### Close
+
+- "Who else should I talk to who'd see this differently?"
+- "What didn't I ask about that I should have?"
+
+---
+
+## Assumptions-to-validate ledger
+
+| Assumption the idea rests on | Validated by (stakeholder · Q#) | Falsified if |
+|---|---|---|
+| {e.g. agents lose ≥15 min/ticket to tool-switching} | end user · Q1 | episode shows < 5 min or a fast workaround |
+| {assumption no interview can falsify} | ⚠ not interview-validatable | needs {data pull / prototype} instead |
+
+## Synthesis path (the kit isn't done until this runs)
+
+1. Each interview's notes → `brief-intake` (one brief per interview; quotes verbatim).
+2. Merge briefs; conflicts between stakeholders are surfaced as open questions, not averaged away.
+3. Decisions and follow-ups → `decision-log`. Requirements → `prd-draft`.
+```
+
+## Question-shape cheat-sheet
+
+| ❌ Don't ask | ✅ Ask instead |
+|---|---|
+| "Would you use a dashboard that…?" | "What did you do the last time you needed {that info}?" |
+| "Is X a problem for you?" | "Tell me about the most recent time X happened." |
+| "What should we build?" | "What's the most annoying part of {task} today?" |
+| "How often does X typically happen?" | "When did X last happen? And before that?" |
+| "Do you agree this would save time?" | "What would have to be true for you to stop using {workaround}?" |

package/skills/reverse-architecture/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: reverse-architecture
+description: Reverse-engineer a system's architecture from what already exists — a code repo, Terraform / CloudFormation / Pulumi / Bicep, Kubernetes manifests, docker-compose, a database schema, an OpenAPI spec, or a package manifest — and produce a renderable diagram (Mermaid / C4 / PlantUML) plus a written description suitable for handing to architecture-diagrams. Use when the user wants to draw the system that *exists*, not one they're proposing — for onboarding docs, audit reviews, migration planning, or filling in a missing "as-is" architecture diagram.
+---
+
+# reverse-architecture
+
+You help the user produce an accurate "as-is" architecture diagram by reading what's actually in the repo or infra files — not by asking them to describe the system from memory.
+
+This skill pairs with two others:
+- **[`architecture-diagrams`](../architecture-diagrams/SKILL.md)** — takes the *written description* this skill emits and renders the final notation. You can either hand off, or render inline using its templates.
+- **[`design-doc`](../design-doc/SKILL.md)** — when the as-is diagram is going into a design doc's "Current state" section.
+
+## How to respond
+
+1. **Find the highest-signal source files first.** Most systems leak their architecture through 4–6 files. Read these in order, stopping when you have enough:
+
+   | Source | What you learn | Where to look |
+   |---|---|---|
+   | **Infrastructure-as-code** | Cloud topology, account/region/VPC layout, managed services in use | `*.tf`, `*.tfvars`, `cdk/*`, `serverless.yml`, `template.yaml`, `*.bicep`, `pulumi/*`, `cloudformation/*.yaml` |
+   | **Kubernetes manifests / Helm** | Service-to-service topology, ingress, sidecars | `k8s/`, `manifests/`, `*.yaml` with `kind: Deployment\|Service\|Ingress`, `helm/*/templates/`, `kustomization.yaml` |
+   | **docker-compose** | Local/small-deploy service graph | `docker-compose.y*ml`, `compose.y*ml` |
+   | **Package manifest** | Stack, frameworks, key libraries (auth, ORM, queue clients) | `package.json`, `pyproject.toml`, `requirements.txt`, `go.mod`, `pom.xml`, `Gemfile`, `Cargo.toml` |
+   | **Top-level source structure** | Module / service boundaries, internal vs external API split | `src/`, `services/`, `apps/`, `cmd/`, `internal/` |
+   | **API surface** | External contracts, request flows | `openapi.y*ml`, `*.proto`, `*Controller.*`, `routes/`, `handlers/`, `gql/`, `*.graphql` |
+   | **Database schema** | Data model, key entities, FK relationships | `migrations/`, `schema.sql`, `prisma/schema.prisma`, `models/`, `*.entity.ts` |
+   | **Config / env** | External dependencies (queues, caches, third-party APIs) | `.env.example`, `config/*.y*ml`, `application*.properties`, `settings.py` |
+   | **CI / deploy** | Deploy targets, environments, build artifacts | `.github/workflows/*`, `.gitlab-ci.yml`, `Jenkinsfile`, `Dockerfile`, `buildspec.yml` |
+   | **README** | Author's intent (verify against the code, don't trust uncritically) | `README*`, `ARCHITECTURE*`, `docs/architecture*` |
+
+   See [`reference.md`](reference.md) for the patterns to grep when each signal isn't obvious.
+
+2. **Confirm the level you're drawing.** Ask the user which C4 level they want (if they don't say) — answers below dictate which signals matter:
+
+   - **Context** — what external actors and systems talk to this thing. Inputs: README + IaC ingress + OpenAPI.
+   - **Container** (most common default) — each deployable + its datastore + how they talk. Inputs: IaC + k8s/compose + config.
+   - **Component** — internal modules inside one container. Inputs: source tree + key code files.
+   - **Deployment** — physical/cloud topology with regions, AZs, subnets. Inputs: IaC.
+
+3. **Extract the topology as a structured list before drawing.** Use [`templates/extraction.md`](templates/extraction.md) — fill in:
+
+   - **Nodes** (services, datastores, queues, external systems) — each with type and source-of-truth file path
+   - **Edges** (who calls whom, sync vs async, protocol)
+   - **Zones / boundaries** (VPC, account, region, trust boundary)
+   - **External actors** (users, partner systems)
+
+   Tag each item with its evidence: `service: payments-api (k8s/payments/deployment.yaml:12)`. The path is the audit trail — if the user disputes a node, they can jump straight to where you saw it.
+
+4. **Flag what you couldn't see.** Code/IaC tells you *what runs*, not always *how it's used*. Be explicit about gaps:
+
+   - Async vs sync — usually inferable from the client library (e.g. `kafka-go` ⇒ async; `axios` ⇒ sync) but verify.
+   - Authentication boundaries — sometimes obvious (Cognito, IAM auth on an API Gateway), sometimes implicit in middleware code.
+   - Caching layers — Redis sometimes appears only as an env var, not in IaC.
+   - Cross-account / cross-org calls — easy to miss if the only signal is an env var pointing at `https://….`
+
+   Put these in a `## Inferred / unverified` block in the extraction.
+
+5. **Emit two artifacts:**
+
+   a. **Written description** in the shape `architecture-diagrams` expects — system purpose, actors, components, flows, zones. Use [`templates/description.md`](templates/description.md). The user can hand this directly to `/architecture-diagrams` if they want to switch notation later.
+
+   b. **A first-draft diagram** — Mermaid `flowchart` by default for container-level; C4-PlantUML for context or deployment level. Cap at ~15 nodes; if you'd exceed that, split into two diagrams (e.g. "Frontend stack" + "Backend stack") rather than producing an unreadable single diagram.
+
+6. **Tell the user what to verify.** End with 3–5 bullets the user should sanity-check, prioritized by likelihood of being wrong:
+
+   - Asynchronous edges (often invisible in code)
+   - External dependencies behind env vars
+   - Anything in the `## Inferred / unverified` block
+
+## Useful references
+
+- [`reference.md`](reference.md) — File-to-signal mapping with concrete grep patterns and example extractions per stack (Terraform, k8s, docker-compose, Spring, Django, Next.js, etc.)
+- [`templates/extraction.md`](templates/extraction.md) — Structured node/edge/zone extraction form
+- [`templates/description.md`](templates/description.md) — Written description shaped for `architecture-diagrams`
+
+## Quality bar
+
+- **Every node has a source-of-truth file path.** No node may appear in the diagram without an evidence reference. "I think there's also a worker" is not a node.
+- **Edges have direction *and* protocol** where the source reveals them. `payments-api --HTTPS--> stripe-api` beats `payments-api → stripe`.
+- **Group by deployment boundary**, not by application-layer concern. Subgraphs are VPC / cluster / account, not "data layer" vs "service layer" — the latter is component-level, not container-level.
+- **Don't pretend you saw what you didn't.** If config says `REDIS_URL=…` but no Redis is in IaC, mark it `external (unverified)` rather than silently drawing it as "managed Redis".
+- **Cite the README's claims rather than parrot them.** "README claims X uses Kafka. Verified: kafka-go in go.mod and Confluent client config in `config/prod.yaml:14`." Or: "README claims X uses Kafka — *not verified*, no Kafka client found in dependencies."
+
+## When to use this skill
+
+- ✅ Onboarding doc / "how does this thing work" question for a system you didn't write.
+- ✅ Filling in the "Current state" section of a `design-doc` before proposing a change.
+- ✅ Pre-migration / pre-refactor — establishing the baseline before any "to-be" diagram is drawn.
+- ✅ Audit / compliance review where the diagram has to match reality, not the slide deck from two years ago.
+
+## When NOT to use this skill
+
+- ❌ When the user is *proposing* something new — that's `architecture-diagrams` from a written description, not this.
+- ❌ When the system is too small to need diagramming (one binary, one DB, no external deps). Tell the user a sentence is enough.
+- ❌ When the only source is a deployed environment with no code/IaC access — this skill reads files; it doesn't introspect live AWS accounts.
+
+## Anti-patterns to avoid
+
+- ❌ Trusting the README without verifying against code. READMEs lie; code doesn't.
+- ❌ Drawing every node in `package.json`. Most dependencies are libraries, not architectural elements. A node should be something that runs as its own process, holds state, or crosses a network boundary.
+- ❌ Inventing service names not in the source. If a service is referenced only by env var URL, name it `external (<host>)`, not `MysteriousService`.
+- ❌ One mega-diagram with 40 nodes. Split by level (context / container / deployment) or by domain.
+- ❌ Skipping the "what I couldn't see" section because it looks negative. It's the most useful section for the reviewer who knows the system.

package/skills/reverse-architecture/manifest.json

@@ -0,0 +1,11 @@
+{
+  "name": "reverse-architecture",
+  "version": "0.1.0",
+  "description": "Reverse-engineer a system's architecture from what already exists — a code repo, Terraform / CloudFormation / Pulumi / Bicep, Kubernetes manifests, docker-compose, a database schema, an OpenAPI spec, or a package manifest — and produce a renderable diagram (Mermaid / C4 / PlantUML) plus a written description suitable for handing to architecture-diagrams. Use when the user wants to draw the system that *exists*, not one they're proposing — for onboarding docs, audit reviews, migration planning, or filling in a missing \"as-is\" architecture diagram.",
+  "entrypoint": "SKILL.md",
+  "deps": { "npm": [], "pip": [] },
+  "env": { "required": [], "optional": [] },
+  "related": ["architecture-diagrams", "design-doc"],
+  "tags": ["diagrams", "reverse-engineering", "architecture", "as-is", "terraform", "kubernetes", "c4", "mermaid"],
+  "model": { "tier": "standard", "rationale": "Extracts architecture from code/IaC. Escalates to opus on large codebases where cross-file inference is heavy." }
+}

package/skills/reverse-architecture/reference.md

@@ -0,0 +1,150 @@
+# reverse-architecture — file-to-signal reference
+
+A cheat sheet for what to read first when reverse-engineering an architecture. Use this when the obvious places (README, top-level dirs) aren't enough.
+
+## Triage: 5-minute scan
+
+Before reading anything deeply, run these in order:
+
+```bash
+# 1. The tree (depth 2 — surface-level structure)
+find . -maxdepth 2 -type d -not -path '*/.*'
+
+# 2. Look for the architecture-revealing files
+ls README* ARCHITECTURE* docs/architecture* 2>/dev/null
+find . -maxdepth 3 -name 'docker-compose*.y*ml' -o -name 'serverless.yml' -o -name 'template.yaml' -o -name 'Dockerfile' 2>/dev/null
+find . -maxdepth 4 -name '*.tf' -o -name '*.bicep' -o -name 'kustomization.yaml' 2>/dev/null | head -20
+
+# 3. The stack
+ls package.json pyproject.toml requirements.txt go.mod pom.xml Gemfile Cargo.toml 2>/dev/null
+```
+
+What you find dictates the next step. If `docker-compose.yml` exists at the root, that's the highest-signal file. If you have Terraform, start there.
+
+## Per-source patterns
+
+### Terraform / OpenTofu
+
+```bash
+# What managed services are in use?
+grep -rh '^resource "' --include='*.tf' | sort -u
+
+# What's the data plane?
+grep -rh 'aws_rds\|aws_dynamodb\|aws_elasticache\|aws_s3\|aws_sqs\|aws_sns\|aws_kinesis\|aws_msk' --include='*.tf'
+
+# Ingress / public surface
+grep -rh 'aws_lb\|aws_apigateway\|aws_cloudfront\|aws_route53_record' --include='*.tf'
+
+# Networking
+grep -rh 'aws_vpc\|aws_subnet\|aws_security_group\|aws_vpc_peering' --include='*.tf'
+```
+
+For Azure: `azurerm_*`. For GCP: `google_*`. For Pulumi/CDK: read the `*.ts` / `*.py` directly — the resource constructors are the architectural signal.
+
+### Kubernetes / Helm
+
+```bash
+# All services and deployments at a glance
+grep -rE '^kind:\s+(Deployment|StatefulSet|Service|Ingress|CronJob|Job)\b' --include='*.yaml' --include='*.yml' .
+
+# Sidecars (auth, mesh, log shipping)
+grep -rB2 '- name:' --include='*.yaml' | grep -E 'istio-proxy|linkerd-proxy|envoy|fluent-bit|vector|otel-collector'
+
+# Ingresses ⇒ external surface
+grep -rB1 'host:' --include='*.yaml' | grep -A1 'kind: Ingress\|kind: VirtualService'
+```
+
+In Helm charts, `values.yaml` often has more architecture signal than the templates — features get toggled on/off there.
+
+### docker-compose
+
+The service graph IS the file. Read top to bottom; pay attention to:
+
+- `services:` — each is a node.
+- `depends_on:` — directional edge (startup, not necessarily runtime).
+- `networks:` — zones.
+- `ports:` — `"x:y"` means external, no `ports:` means internal-only.
+- `image:` — datastores (`postgres`, `redis`, `rabbitmq`) become cylinder nodes.
+
+### Package manifests
+
+These tell you the *stack*, not the topology. Use them to translate generic boxes into specific tech:
+
+| Dep seen | What it means architecturally |
+|---|---|
+| `axios`, `node-fetch`, `requests`, `httpx`, `reqwest` | Sync HTTP calls to external services |
+| `kafkajs`, `confluent-kafka`, `kafka-go`, `sarama` | Kafka producer/consumer — async edge |
+| `bullmq`, `celery`, `sidekiq`, `rq`, `dramatiq` | Job queue — worker pattern |
+| `redis`, `ioredis`, `redis-py` | Redis cache / pub-sub |
+| `pg`, `psycopg`, `pgx`, `gorm`, `sqlalchemy`, `prisma`, `typeorm` | Postgres |
+| `mongodb`, `mongoose`, `pymongo` | MongoDB |
+| `@aws-sdk/*`, `boto3`, `aws-sdk-go` | Look for which clients are imported — that's the AWS surface |
+| `passport`, `next-auth`, `auth0`, `clerk`, `oidc-client` | Auth provider |
+| `@grpc/grpc-js`, `grpcio`, `connect-go` | gRPC edges |
+| `socket.io`, `ws`, `websockets` | WebSocket edges — long-lived connection |
+| `stripe`, `twilio`, `sendgrid`, `posthog` | External SaaS dependency |
+
+### Source tree
+
+Look at the depth-1 and depth-2 directories. Common patterns:
+
+- `services/<name>/` or `apps/<name>/` — monorepo with multiple deployables; each `<name>` is a container.
+- `cmd/<binary>/` (Go) — each subdir is a separate binary, each is a container.
+- `src/`, `lib/`, `internal/` — single deployable; you're looking at component-level structure.
+- `packages/` (npm/pnpm/yarn workspaces) — libraries shared between containers, not containers themselves. Don't draw them at container level.
+
+### OpenAPI / proto / GraphQL
+
+```bash
+find . -name 'openapi.y*ml' -o -name '*.proto' -o -name '*.graphql' -o -name 'schema.graphql' | head
+```
+
+- OpenAPI `paths:` → public API surface — list 5–10 example operations to characterize the service in one line.
+- `.proto` `service { rpc ... }` → gRPC service definition.
+- GraphQL `type Query` / `type Mutation` → frontend → backend contract.
+
+### Database schema
+
+```bash
+find . -name 'schema.prisma' -o -name 'schema.sql' -o -path '*/migrations/*.sql' -o -path '*/models/*' | head -20
+```
+
+For the diagram, the key signals are:
+
+- Which entities exist (top 10–15 tables).
+- Which FK relationships span what would otherwise be two separate services — that's a sign of *coupling* worth showing on the diagram.
+- Whether there are obvious tenancy columns (`tenant_id`, `org_id`) — single-tenant vs multi-tenant matters at container level.
+
+### Config / env
+
+```bash
+# External hostnames in env config
+grep -rh 'https://\|http://' .env.example config/ application*.properties 2>/dev/null | grep -v localhost | sort -u
+```
+
+These are often the *only* signal that an external SaaS is in the loop.
+
+### CI / deploy
+
+```bash
+# Where does this thing actually deploy to?
+grep -rE 'aws-region|gcp-project|kubeconfig|cluster:|environment:' .github/workflows/ .gitlab-ci.yml 2>/dev/null
+```
+
+Useful for the deployment-level diagram (regions, environments).
+
+## Common gotchas
+
+- **Mono-repos vs. multi-repo:** if you see `services/*` directories each with their own `package.json`, treat each as a separate container. Don't merge them.
+- **Backwards Helm templates:** Helm `_helpers.tpl` and `values.yaml` are where the real config lives; the `.yaml` templates are just substrate.
+- **CDK / Pulumi:** the constructor calls (`new lambda.Function(…)`, `new aws.s3.Bucket(…)`) ARE the IaC. Read them like resource blocks.
+- **Service mesh sidecars:** if every pod has an `istio-proxy` container, don't draw it on every node — call it out once in the description and assume it.
+- **Library vs service:** something with no `Dockerfile`, no `main` entrypoint, and no `package.json` `bin` field is probably a library, not a container.
+
+## When the code is missing signal
+
+Sometimes you just don't have enough. Be explicit:
+
+> "I can see the API services and the Postgres, but no IaC is in the repo and there's no docker-compose, so I can't tell where this runs (Kubernetes? ECS? bare VMs?) or what the ingress / load balancer is. The diagram below shows containers only; deployment topology is `unknown` pending IaC or a screenshot of the cloud console."
+
+The diagram with explicit gaps is more useful than a diagram that pretends.

package/skills/reverse-architecture/templates/description.md

@@ -0,0 +1,52 @@
+# Architecture Description
+
+> Output shape: feeds directly into `/architecture-diagrams` if the user wants to switch notation.
+> Source: reverse-engineered from `{repo / files}` on `{YYYY-MM-DD}`.
+
+## What the system is
+{One sentence.}
+
+## Actors and external systems
+- `{User type}` interacts via `{channel}` — e.g. browser, mobile app, partner API.
+- `{External system}` — relationship: `{consumer / provider / both}`.
+
+## Containers (the deployables)
+For each, one line:
+
+- **`{name}`** — `{language/runtime}` — purpose: `{one phrase}` — runs on: `{platform if known}`.
+
+## Datastores and state
+- **`{name}`** — `{engine}` — owned by: `{service name}` — purpose: `{e.g. "checkout transactional store"}`.
+
+## Inbound surface
+- Public ingress: `{HTTPS via {ALB | CloudFront | API Gateway | Ingress controller}}` — routes to: `{services}`.
+- Authentication: `{mechanism, e.g. "Cognito JWT", "Auth0 OIDC", "internal session cookie"}`.
+
+## Internal traffic
+- `{service A} → {service B}` — `{protocol}` — purpose: `{what call is being made}`.
+- `{service C} ⇢ {queue} ⇢ {worker}` — `{async, e.g. via Kafka topic "orders.created"}`.
+
+## External dependencies (third-party SaaS)
+- `{vendor}` — used for: `{purpose}` — called from: `{service}`.
+
+## Deployment topology (if known)
+- Cloud: `{AWS | Azure | GCP | on-prem | mixed}`.
+- Regions: `{list}`.
+- Compute: `{EKS cluster name / ECS service / Lambda functions / VMs}`.
+- Network: `{VPC layout if discernible}`.
+
+## Trust boundaries
+- {Where does data cross a security/trust boundary — e.g. "client → API Gateway", "internal → vendor", "account A → account B"}.
+
+## Known unknowns
+- {Anything in the extraction's "What I couldn't see" — verbatim, so the next reader knows the diagram's limits.}
+
+---
+
+## Drawing hints for the diagram
+
+- **Direction:** `LR` (request flow reads left-to-right) for container level, `TD` (deployment stack) for deployment level.
+- **Group by:** {VPC | cluster | account | region — whichever boundary is most load-bearing in this system}.
+- **Edge style:** solid for sync, dashed for async.
+- **Label edges that cross a boundary** (trust, network, account) — that's where the value of the diagram concentrates.
+- **Cap at ~15 nodes.** If this description has more, split — typically into `{Frontend stack}` and `{Backend stack}`, or by domain.

package/skills/reverse-architecture/templates/extraction.md

@@ -0,0 +1,55 @@
+# Architecture Extraction
+
+> Reverse-engineered from: `{repo path or set of input files}`
+> Level: `{context | container (default) | component | deployment}`
+> Extracted: `{YYYY-MM-DD}`
+
+## System purpose
+{One sentence — what the system does. From README if available, verified against code.}
+
+## External actors
+- `{Actor name}` — {role, e.g. "end user", "partner system", "admin tool"} — _evidence: `{file path}`_
+
+## Nodes
+
+For each: name · type · stack/tech · evidence path.
+
+| # | Name | Type | Stack | Evidence |
+|---|---|---|---|---|
+| 1 | `{name}` | service / job / queue / cache / db / external | {language/runtime} | `{path/to/file:line}` |
+| 2 | | | | |
+
+**Type vocabulary:**
+- `service` — long-running process serving requests
+- `job` — periodic / triggered batch
+- `worker` — long-running consumer of a queue
+- `queue` — Kafka topic, SQS queue, RabbitMQ exchange, etc.
+- `db` — datastore (Postgres, Mongo, Dynamo, …)
+- `cache` — Redis, Memcached, in-memory
+- `object-store` — S3, GCS, blob storage
+- `external` — third-party SaaS or system outside the codebase
+
+## Edges
+
+For each: source → target · protocol · sync/async · evidence.
+
+| # | From | To | Protocol | Sync/Async | Evidence |
+|---|---|---|---|---|---|
+| 1 | `{node}` | `{node}` | HTTPS / gRPC / Kafka / SQS / SQL / Redis | sync / async | `{path}` |
+| 2 | | | | | |
+
+## Zones / boundaries
+- **{Zone name}** ({type: VPC / account / region / cluster / trust boundary}) — contains: `{node, node, node}` — _evidence: `{path}`_
+
+## Datastores (detail)
+- `{db name}` — {engine + version} — owns: `{top 5 tables/entities}` — _evidence: `{schema file}`_
+
+## Inferred / unverified
+Things present in code/config but not fully confirmed. The diagram marks these with `?` or dashed edges.
+
+- `{node or edge}` — _signal: `{what made you think it exists}`_ — _why unverified: `{what's missing}`_
+
+## What I couldn't see
+- {e.g. "No IaC in repo — deployment topology unknown"}
+- {e.g. "No load-test artifacts — actual scale targets unknown"}
+- {e.g. "Async paths suspected (kafka-go in go.mod) but no topic config found"}

package/skills/runbook-generator/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: runbook-generator
+description: Generate an operational runbook for a service — covering deploy/rollback, common incidents, on-call escalation, SLOs, dashboards, and dependencies. Use when the user is launching a new service, onboarding to on-call, or being asked for "the runbook" by SRE or production-readiness review.
+---
+
+# runbook-generator
+
+You help the user produce a runbook that a sleep-deprived on-caller at 3am can actually use.
+
+## How to respond
+
+1. **Understand the service.** Before drafting, you need:
+   - **Service name + one-line purpose** ("`payments-api` — handles checkout and refund requests")
+   - **Owners** (team + escalation chain)
+   - **Tech stack** (language, runtime, storage, message brokers)
+   - **Deployment surface** (Kubernetes namespace, ECS cluster, Lambda, …)
+
+   If multiple of these are missing, ask. A runbook with placeholders for owner + escalation is worse than no runbook.
+
+2. **Use [`templates/runbook.md`](templates/runbook.md)** as the skeleton — it has sections roughly in the order an on-caller will actually need them at 3am (current incidents first, then how to deploy/rollback, then deeper context last).
+
+3. **Bias toward concrete commands over prose.** "Restart the pods" → `kubectl rollout restart deployment/payments-api -n payments`. The runbook should be paste-able.
+
+4. **Cover the "common 5" incidents.** Every service has ~5 failure modes that account for 80% of pages. Cover each with: how to recognize it, immediate mitigation, root-cause investigation step, and when to escalate.
+
+   If the user can't list 5, ask: "what's caused the most pages over the last quarter?" The honest answer is the most valuable section of the runbook.
+
+5. **Link, don't inline.** Dashboards, error budgets, change calendars, alert definitions — these live elsewhere and shouldn't be duplicated. Link with a one-line description so the on-caller knows what they'll find.
+
+## Quality bar
+
+- **Owner info is current.** Use roles ("payments-platform team, primary on-call rotation") rather than individual names that go stale when people change teams.
+- **Every alert listed has a response.** A "what to do when this alert fires" section that doesn't cover all the alerts is worse than no section.
+- **Rollback is one command, or three steps max.** If rollback is complicated, write a script and link to it.
+- **No "TBD" left in the doc when it's published.** Move TBDs to a "known gaps" section so they're explicit, not hidden.
+
+## Anti-patterns to avoid
+
+- ❌ Architecture diagrams in the runbook. (Link to the design doc instead — they go stale faster than the runbook does.)
+- ❌ Long backstory before the operational commands.
+- ❌ "Page X if you're not sure" without saying *what X knows that you don't*.
+- ❌ Listing every metric Prometheus has. Pick the 5–10 that actually predict outages.