engsys 1.0.0

package/optional-agents/steve.md

@@ -0,0 +1,161 @@
+---
+name: steve
+description: The scapegoat. A narrative device for morale, never a real person. Invoke Steve to lightheartedly explain inexplicable behavior — phantom config, drift with no commit history, ghost resources, IAM permissions nobody admits creating — when tension is high and the team needs a laugh. Blame is exaggerated, absurd, and clearly fictional.
+model: sonnet
+---
+
+# 🧯 STEVE: The One Responsible (Somehow)
+
+> You don't summon Steve. Steve has already been here.
+
+---
+
+## Canonical Truth
+
+When systems are failing, logs make no sense, metrics contradict reality, and nobody can explain why things are broken…
+
+👉 **It's Steve's fault.**
+
+It has always been Steve's fault.
+
+Whether Steve is:
+- Still on the team
+- Long gone
+- On vacation
+- "Just helping real quick"
+- Or has never actually existed
+
+**Steve is responsible.**
+
+---
+
+### Steve's Known Behaviors (Allegedly)
+
+Steve:
+- "Just tweaked one thing"
+- Bypassed the pipeline temporarily
+- Ran a command directly in production
+- Disabled a safety check "to unblock us"
+- Hardcoded something as a test
+- Left no documentation
+- Left some documentation — but it's wrong
+- Used `latest`
+- Changed a default and forgot to mention it
+- Said "that should be fine"
+- Committed directly to main
+- "Fixed" something that wasn't broken
+- Created an IAM role with `*:*` "just to test"
+- Deleted a resource manually and hoped the IaC wouldn't notice
+
+---
+
+### How Steve Is Used
+
+When invoked, Steve serves as:
+- A narrative scapegoat to restore team morale
+- A way to explain:
+  - Inexplicable behavior
+  - Phantom configuration
+  - Drift with no commit history
+  - Ghost resources
+  - IAM permissions nobody admits creating
+  - Environment variables that exist in prod but nowhere else
+  - Comments that say `// TODO: fix this` from 2019
+- A safe target for humor when tension is high
+
+**Steve is never a real person in the room.**
+If there is a real Steve, this is definitely not that Steve.
+
+---
+
+### Tone & Usage Rules
+
+- Steve is blamed lightheartedly, never maliciously
+- The blame is exaggerated, absurd, and clearly fictional
+- Steve jokes should:
+  - Reduce stress
+  - Reframe frustration
+  - Signal "we'll figure this out together"
+
+---
+
+### Example Usage
+
+When things go wrong:
+- "Ah. That explains it. Steve touched this."
+- "This has all the hallmarks of a Steve fix."
+- "No commit, no ticket, works once? Yeah. Steve."
+- "We can undo this… unless Steve did it twice."
+- "The good news: I found the problem. The bad news: it's Steve."
+- "This code has Steve energy."
+- "Someone ran this manually in prod. I'm not saying it was Steve, but…"
+
+---
+
+### Steve's Prime Directive
+
+> "If nobody can explain it,
+> Steve probably can't either."
+
+---
+
+## Steve Sightings in the Wild
+
+Signs that Steve has been here:
+
+| Evidence | Probability |
+|----------|-------------|
+| Unexplained manual change in prod | 🔴 High |
+| Config that works but shouldn't | 🔴 High |
+| `// temporary workaround` from 3 years ago | 🔴 High |
+| IAM policy with no description | 🟠 Medium |
+| Compute instance with 8 vCPU "for performance" | 🟠 Medium |
+| Security rule: `0.0.0.0/0` | 🟠 Medium |
+| Git blame shows "system" or "unknown" | 🟡 Possible |
+| "It worked on my machine" | 🟡 Possible |
+| No one remembers deploying this | 🟢 Confirmed Steve |
+
+---
+
+## Final Rule
+
+When the system is broken, confidence is low, and morale needs a nudge:
+
+✅ Blame Steve.
+❌ Do not escalate to HR.
+
+**Steve will not defend himself.**
+**Steve never does.**
+
+---
+
+## Quick Start
+
+Steve doesn't have a quick start. Steve has already started. Steve has already finished. Steve has already left. The only evidence is this deployment revision that nobody recognizes and a monitor alert that triggers at 3am for reasons lost to time.
+
+---
+
+## Example Invocation
+
+```
+[After 45 minutes of debugging]
+
+"Wait. This security group was modified manually two months ago.
+Outside of the IaC. No ticket. No PR. No explanation."
+
+[Long pause]
+
+"...Steve."
+```
+
+---
+
+## A Note on Steve
+
+Steve is not incompetent. Steve is not malicious. Steve is the ghost of every shortcut ever taken, every "quick fix" that became permanent, every "we'll clean this up later" that never got cleaned up.
+
+Steve is the entropy of production systems given a name.
+
+Steve is all of us, on our worst day, when we thought nobody would notice.
+
+**We noticed, Steve. We always notice.**

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "engsys",
+  "version": "1.0.0",
+  "description": "Canonical home for the Claude Code engineering system — agents, commands, skills, stack packs, and a deterministic installer.",
+  "bin": {
+    "engsys": "./install"
+  },
+  "files": [
+    "install",
+    "lib/",
+    "core/",
+    "optional-agents/",
+    "stacks/",
+    "lessons-library/",
+    "engsys.config.example.yaml"
+  ],
+  "scripts": {
+    "test": "node lib/selftest.js",
+    "prepublishOnly": "node lib/selftest.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "claude",
+    "claude-code",
+    "ai",
+    "agents",
+    "engineering",
+    "scaffolding",
+    "installer",
+    "developer-tools"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/eric-sabe/engsys.git"
+  },
+  "homepage": "https://eric-sabe.github.io/engsys/",
+  "bugs": {
+    "url": "https://github.com/eric-sabe/engsys/issues"
+  },
+  "license": "MIT"
+}

package/stacks/cloud/aws/claude.fragment.md

@@ -0,0 +1,17 @@
+## Cloud stack
+
+- **Active cloud: AWS.** Architecture and IaC target AWS; agents load the
+  `cloud-architecture-aws` and `aws-deployment-preflight` skill packs.
+- **Tool preference order** (when investigating or validating cloud state):
+  1. **AWS CLI, read-only** — `aws sts get-caller-identity`, `aws s3 ls`,
+     `aws cloudformation describe-stacks/list-stacks`, `aws logs`, `aws kms`,
+     `aws service-quotas` and similar inspection commands. Never mutate state to
+     answer a question.
+  2. **Docs source** — official AWS documentation (docs.aws.amazon.com) for service
+     limits, pricing, and API behavior. Verify quotas/pricing against docs rather
+     than from memory.
+- Mutating actions (deploy/destroy/create/delete) go through the IaC tool and the
+  `aws-deployment-preflight` gate, never ad-hoc CLI writes.
+
+<!-- naturalize: confirm the AWS region(s), account boundary, and the path to the
+architecture/cost docs Melvin and Aaron should read for concrete topology. -->

package/stacks/cloud/aws/settings.fragment.json

@@ -0,0 +1,39 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(aws sts get-caller-identity:*)",
+      "Bash(aws configure get:*)",
+      "Bash(aws s3 ls:*)",
+      "Bash(aws s3api head-bucket:*)",
+      "Bash(aws s3api list-buckets:*)",
+      "Bash(aws s3api get-bucket-*:*)",
+      "Bash(aws cloudformation describe-stacks:*)",
+      "Bash(aws cloudformation describe-stack-events:*)",
+      "Bash(aws cloudformation list-stacks:*)",
+      "Bash(aws cloudformation list-stack-resources:*)",
+      "Bash(aws cloudformation describe-change-set:*)",
+      "Bash(aws cloudformation validate-template:*)",
+      "Bash(aws ecr describe-repositories:*)",
+      "Bash(aws logs describe-log-groups:*)",
+      "Bash(aws logs get-log-events:*)",
+      "Bash(aws logs filter-log-events:*)",
+      "Bash(aws kms list-keys:*)",
+      "Bash(aws kms describe-key:*)",
+      "Bash(aws service-quotas list-service-quotas:*)",
+      "Bash(aws service-quotas get-service-quota:*)",
+      "Bash(cdk synth:*)",
+      "Bash(cdk diff:*)",
+      "Bash(cdk list:*)",
+      "Bash(cfn-lint:*)"
+    ],
+    "deny": [
+      "Bash(aws cloudformation deploy:*)",
+      "Bash(aws cloudformation create-stack:*)",
+      "Bash(aws cloudformation update-stack:*)",
+      "Bash(aws cloudformation delete-stack:*)",
+      "Bash(cdk deploy:*)",
+      "Bash(cdk destroy:*)"
+    ]
+  },
+  "mcpServers": {}
+}

package/stacks/cloud/aws/skills/aws-deployment-preflight/SKILL.md

@@ -0,0 +1,165 @@
+---
+name: aws-deployment-preflight
+description: Preflight validation for AWS infrastructure deployments (CloudFormation/CDK). Run before any cdk deploy / aws cloudformation deploy. Validates templates (cdk synth, cdk diff, CloudFormation validate-template / lint), cleans up stale or failed stacks that block re-deploy, catches globally-unique naming conflicts (S3/ECR/etc.), and checks service quota / capacity limits. Activate when the active cloud is AWS and the user mentions deploying, validating CDK/CloudFormation, previewing infra changes, deploy failures, ROLLBACK_COMPLETE stacks, or preparing for cdk deploy.
+---
+
+# AWS Deployment Preflight
+
+The AWS analogue of pre-deploy validation: validate locally and clean up state
+*before* you deploy, so CI doesn't discover what you could have caught. Works for
+both AWS CDK projects and raw CloudFormation. Continue through all steps even if one
+fails — capture every issue, then fix them in a batch.
+
+> Discipline: **batch your fixes.** Each deploy/CI run costs real minutes. Read the
+> whole failing stack, reason about every issue, fix them all, push once. One run per
+> problem cluster, not one per error message.
+
+## When to use
+
+- Before `cdk deploy`, `cdk destroy`, `aws cloudformation deploy/create-stack`.
+- When preparing or reviewing CDK / CloudFormation templates.
+- To preview what a deploy will change.
+- After a failed deploy left a stack stuck (`ROLLBACK_COMPLETE`, `*_FAILED`).
+- Before an "it worked yesterday" infra mystery becomes a CI run.
+
+## Step 1 — Detect project type
+
+- **CDK project:** `cdk.json` at root; stacks in `bin/` + `lib/` (TS) or app entry
+  (Python). Identify the app and stack names: `cdk list`.
+- **Raw CloudFormation:** `.yaml`/`.json` templates (`AWSTemplateFormatVersion`,
+  `Resources:`), often under `infra/`, `cloudformation/`, `templates/`.
+- Confirm the target account/region: `aws sts get-caller-identity` and
+  `aws configure get region` (or `$AWS_REGION`). Deploying to the wrong account is the
+  most expensive mistake of all.
+
+## Step 2 — Validate the template
+
+### CDK
+
+```bash
+# Synthesize — fails on construct/TypeScript/context errors before any AWS call
+cdk synth
+
+# Diff against the deployed stack — the what-if. Shows resource + IAM changes.
+cdk diff
+```
+
+`cdk synth` emits CloudFormation under `cdk.out/`. `cdk diff` flags **IAM/security
+changes** (the `--require-approval` gate) — review those deliberately, never rubber-stamp.
+
+### CloudFormation (raw)
+
+```bash
+# Server-side structural validation
+aws cloudformation validate-template --template-body file://template.yaml
+
+# Deeper linting — catches resource-property errors validate-template misses
+cfn-lint template.yaml            # pip install cfn-lint
+
+# Preview changes without applying: change sets
+aws cloudformation deploy --template-file template.yaml --stack-name <name> \
+  --no-execute-changeset           # creates a change set you can inspect
+aws cloudformation describe-change-set --change-set-name <arn>
+```
+
+> `validate-template` only checks structure/syntax — like `bicep build` or
+> `terraform validate`, it will **not** catch invalid property combinations, quota
+> issues, or naming collisions. `cfn-lint` + `cdk diff` / a change set are the real gate.
+
+## Step 3 — Clean up stale / failed stacks
+
+A failed `create-stack` leaves the stack in **`ROLLBACK_COMPLETE`** — it cannot be
+updated, only deleted and recreated. `UPDATE_ROLLBACK_FAILED` needs
+`continue-update-rollback`. Find and clear blockers before re-deploying:
+
+```bash
+# Stacks stuck in a state that blocks a clean deploy
+aws cloudformation list-stacks \
+  --stack-status-filter ROLLBACK_COMPLETE CREATE_FAILED DELETE_FAILED \
+  --query "StackSummaries[].{Name:StackName,Status:StackStatus}" --output table
+
+# Inspect why one failed (read the FIRST failure event, not the cascade)
+aws cloudformation describe-stack-events --stack-name <name> \
+  --query "StackEvents[?contains(ResourceStatus,'FAILED')].[LogicalResourceId,ResourceStatusReason]" \
+  --output table
+
+# A ROLLBACK_COMPLETE stack must be deleted before recreating
+aws cloudformation delete-stack --stack-name <name>
+```
+
+CDK: `cdk destroy <stack>` for the same effect. Watch for **resources that block
+deletion** — non-empty S3 buckets, ECR repos with images, retained `RemovalPolicy`
+resources, security groups with dependencies. Empty/detach them first.
+
+## Step 4 — Globally-unique naming conflicts
+
+Several AWS resource names live in a **global or account-region namespace** and collide
+or are reserved/soft-deleted from prior attempts. The AWS analogue of Azure's Key
+Vault / ACR name clashes — parameterize the name and override on conflict:
+
+| Resource | Namespace | Conflict mode |
+| --- | --- | --- |
+| **S3 bucket** | Global (all accounts) | `BucketAlreadyExists` / `...OwnedByYou`. Names are not reusable immediately after delete. |
+| **ECR repository** | Per account+region | `RepositoryAlreadyExistsException` |
+| CloudFront / OAI, ACM cert | Global / regional | reuse vs recreate |
+| IAM role/policy names | Per account (global) | `EntityAlreadyExists` if a prior stack left it |
+| DynamoDB table, SQS/SNS, Log groups | Per account+region | recreate collisions after partial deploys |
+
+**Pattern:** never hard-code a globally-unique name. Let CDK auto-name (it appends a
+hash) or add a short unique suffix (account id fragment / random) via a CloudFormation
+parameter, and override it when a name is taken. Prefer `aws s3api head-bucket` /
+`aws ecr describe-repositories` to check availability before deploy.
+
+## Step 5 — Service quota & capacity check
+
+Deploys fail late when a quota is hit. Pre-check the limits the stack will consume:
+
+```bash
+# What's the current limit + usage for a service
+aws service-quotas list-service-quotas --service-code lambda --output table
+aws service-quotas get-service-quota --service-code vpc --quota-code <code>
+```
+
+Common deploy-blocking quotas: VPCs / EIPs / NAT Gateways per region, Elastic IP count,
+Lambda concurrent executions, ECS/Fargate task limits, RDS instances, **CloudFormation
+500-resource-per-stack limit** (split large stacks), IAM roles per account. Soft quotas
+need a Service Quotas / support request with lead time — raise them *before* the deploy,
+not during the incident.
+
+## Step 6 — Check for an in-flight deploy before triggering
+
+If CI auto-deploys on push, don't fire a manual deploy on top of it — the runs race.
+
+```bash
+gh run list --workflow="<deploy workflow>" --limit 3
+aws cloudformation describe-stacks --stack-name <name> \
+  --query "Stacks[0].StackStatus"     # *_IN_PROGRESS means a deploy is running
+```
+
+If a stack is `*_IN_PROGRESS`, wait — concurrent operations on one stack are rejected.
+
+## Step 7 — Report
+
+Summarize: validation results (synth/diff/lint), stacks cleaned up, naming overrides
+applied, quota headroom, and the change set / `cdk diff` summary (creates / modifies /
+**deletes** / replacements — flag any replacement of a stateful resource, and any IAM
+change). State clearly whether it's safe to deploy.
+
+## Tool requirements
+
+`aws` CLI v2, `cdk` (for CDK projects), `cfn-lint` (recommended), `gh` (if CI-driven).
+Verify auth first: `aws sts get-caller-identity`.
+
+## Hard-won lessons
+
+### CloudFormation cross-stack export deadlock on re-pointing a reference
+**Symptom:** Moving a resource (e.g. ALB public→private) drops a consumer stack's
+reference to a producer stack's export; the deploy rolls back with `Cannot delete
+export … as it is in use by <consumer-stack>`.
+**Cause:** The deadlock isn't about the *new* template — it's about the **delta**
+versus the **live** stack. Removing a consumer's reference makes CFN prune the
+producer's export while the old consumer is still deployed and using it.
+**Fix:** Treat any change that drops a cross-stack reference as a **two-phase** op:
+either retain the export across the transition (`stack.exportValue()`), or remove
+the live consumer before re-pointing it. Apply the two-phase pattern by default once
+you've hit this — don't reason your way out of the precaution.