6.lsdlc cartridge — golden-spec on the Forge

1. Why this cartridge, why this slice

The Forge model is supposed to make cartridges thin: declare your app, inherit substrate (KMS, network, guardrails, schedules, obs, SDK), and ship business logic. We have two cartridges that prove the model for browser-fronted vibe apps (chatbot, obs). We do not have a cartridge that proves the model for event-driven background work. Adding one closes that gap.

We could close the gap by absorbing all of Ammar's paycargo-ai work into cartridges/engineering/code-agents/ directly. The trade is large: 9 Terraform modules to rewrite against the substrate, 11 Docker agents to reroute through AgentCore Gateway with our IAM, ECR + CodeBuild + deploy pipelines to migrate. Multi-day effort with real risk of regression on something Ammar already has running.

The smaller, safer move: pick the simplest agent (golden-spec, which reads an issue and writes a spec), rebuild it on the Forge in roughly one focused day, and demo the full pipeline. If it works, we know the doctrine is real for event-driven cartridges. If we then decide to absorb the rest of paycargo-ai, we have a working template. If we decide to keep paycargo-ai standalone, we lost a day but proved the model.

2. The demo loop

Every story you label = one row in the cost-by-user table. Every spec generation has a dollar amount you can show to anyone. Quarterly reviews start writing themselves.

3. Three-piece scope: visible, configurable, doctrine

Visible

sdlc shows up as a fourth row in the obs Cartridges tab alongside chatbot, obs-app, and substrate. MTD spend, invocation count, budget, status, retention, and access all populate. Real-time cost attribution by token-log query, no waiting for Cost Explorer activation.

Diff: two lines in cartridges/administrative/obs/lambda/cartridges.js. Add 'sdlc' to APP_OWNERS. Add 'sdlc': '/aws/lambda/ai-sandbox-sdlc-golden-spec' to COST_LOG_GROUPS. The merge logic already handles cartridges with no Bedrock activity by showing $0 until the first invocation.

Configurable

The operator clicks the sdlc row in the Cartridges modal and sees, in addition to the standard Budget / Access / Retention / Notes sections, a new Trigger config section showing one row per agent. Each row is editable; model and prompt travel together because the right prompt depends on the model (Opus reasons over more context, Haiku rewards tighter instructions).

Plus, on the same section:

• Repo allowlist. Day one: PayCargoDevOps/ai-sandbox only. Expandable to multiple PayCargoDevOps repos.
• Last 7 fires with their issue links, model used, token counts, and dollar cost.
• "Test fire" button on each agent row: invokes the handler against a synthetic issue body so the operator can preview output without labelling a real issue.

State lives in DDB under agent_session_id="sdlc-agent-config", one item per agent. The Lambda reads at cold start and caches for 15 minutes (same pattern the schedules manifest uses, Step.6.k). Operator edits land within 15 minutes without redeploying anything.

Doctrine

The cartridge is a first-class member of the platform.

• Folder: cartridges/engineering/code-agents/. Owned by the engineering vibe-scripter cohort per Step 6.d. Not under global/ because these are engineering's productivity tools (finance won't use golden-spec; HR won't use code-review), even though they read PayCargo-wide repos.
• Manifest: cartridges/engineering/code-agents/cartridge.tf declares app_id, owner, data classification, retention, supported labels, log group ARN, trigger endpoint, source repo URL.
• Env composition: module "sdlc_cartridge" {} block in substrate/environments/ai-sandbox/main.tf alongside chatbot_cartridge and observability_app.
• App tag: every resource gets App = "sdlc".
• CODEOWNERS: /cartridges/engineering/code-agents/ @engineering-vibe-scripters (today fronted by @mmbtang until the team exists as a GitHub team).
• Documentation: this doc (6.l). Tree diagram in 6.d updated to show sdlc as the second cartridge under global/.

4. Architecture

The handler is a two-turn pipe: a planner Bedrock call decides which repo files matter for this specific issue, the Lambda fetches those files via GitHub REST, then a writer Bedrock call generates the spec with that context loaded. Repo-aware generation without an AgentCore tool-use loop. Bedrock itself never holds the GitHub PAT; both calls receive only assembled text.

Why the planner sees the file tree but not file contents

The cost optimization is real. A 200-entry file tree is roughly 4 KB of tokens; reading 10 actual files is often 40-80 KB. Doing both reads in one turn would burn the input-token budget on files the model wasn't going to reference. Letting the model pick first, with only the index in front of it, keeps the writer turn focused and the total bill close to single-turn cost (~2x, not 10x).

Bedrock never holds GitHub credentials

The PAT lives in Secrets Manager, fetched by the Lambda on cold start and cached in module scope. Bedrock receives only assembled text. There is no path for the model to call GitHub directly (that's the AgentCore tool-use pattern, not this one). CloudTrail shows SecretsManager:GetSecretValue per cold start; CloudWatch shows the exact GitHub API calls the Lambda made between turns. Full audit trail.

5. Files we create

cartridges/engineering/code-agents/
├── README.md                  — purpose, supported labels, how to add agents
├── cartridge.tf                — platform manifest (app_id, owner, retention)
├── auth.tf                     — IAM role + permission boundary
├── backend.tf                  — Lambda + API GW + Secrets Manager refs
├── outputs.tf
├── variables.tf
├── versions.tf
└── lambda/
    ├── handler.js               — main webhook handler (~250 LOC zero-npm)
    ├── github-client.js         — minimal GitHub REST wrapper (~80 LOC)
    ├── verify-signature.js      — HMAC-SHA256 webhook verify (~30 LOC)
    └── prompts/
        └── golden-spec.md       — copied verbatim from paycargo-ai/agents/golden-spec/

Plus three small edits outside the cartridge:

• substrate/environments/ai-sandbox/main.tf: new module "sdlc_cartridge" block.
• cartridges/administrative/obs/lambda/cartridges.js: APP_OWNERS, COST_LOG_GROUPS, plus Opus 4.6 row in BEDROCK_PRICING_USD_PER_M_TOKENS.
• .github/CODEOWNERS: route the new folder to the owning team.

6. Cost model (Opus 4.6)

Opus 4.6 is the strongest Claude model in the family. The trade is cost: roughly 5x Sonnet 4.5 per token, 15x Haiku 4.5. golden-spec writes architecture-level specs, so the extra reasoning is worth it; if quality is good enough on Sonnet 4.5 for some agents (e.g. code-review on small diffs), we run those cheaper. The per-cartridge model is configurable from the obs modal, so the decision can land per-agent.

Per spec generation (~10K input + 4K output, typical golden-spec)

The planner turn is cheap (small input + tiny JSON output). The writer turn carries most of the spend because it pulls in actual repo file contents. Per-token breakdown is logged twice (once per turn) so the obs Cartridges tab can show the operator exactly where the bill landed; if planner cost ever creeps up, the dial is "show the model fewer tree entries up front."

Monthly fixed (paid at zero usage)

Five strategies, per-spec and at scale

The 2-turn-with-Opus row above is the baseline. The substrate already lets us pick from five strategies via the model router (Step 6.m). The operator changes route names in the obs Trigger config section; no code change.

Strategy E is roughly 88% cheaper than naive single-vendor. The point is not which row to pick; the point is that the substrate lets the operator pick D for executive-facing artifacts and E for routine work on the same agent, by editing a config. The economics flip from "cost of running agents" to "cost of running specifically the writer turn." Once the writer goes local in Phase 2 (Step 6.m trajectory), even that goes to electricity.

Three usage tiers (Strategy E default)

7. What it inherits from the substrate

8. Doctrine updates this cartridge surfaces

---
model: us.anthropic.claude-opus-4-6-<datestamp>-v1:0
max_output_tokens: 4000
---
You are golden-spec, an architect-level assistant. Given a GitHub issue,
write an implementation specification. Sections: Context, Approach,
Files to touch, Tests, Risks.
...

9. Phase 1.5 — local-inference handoff via the model router

Phase 1 ships golden-spec on cloud-only routes (Haiku scout, Opus or Sonnet writer). Phase 1.5 swaps the scout turns to a Mac Mini running Qwen 2.5 Coder via the model router substrate (Step 6.m). The cartridge code does not change. The agent's per-turn config flips one field: route: "scout-cloud" → route: "scout-local".

Network setup checklist (the only non-trivial part):

1. Mac Mini or Mac Studio at the office. Tailscale installed; assigned a stable Tailscale IP (e.g. 10.42.0.10).
2. Ollama (or vLLM, MLX, llama.cpp) running on the Mac, exposing the OpenAI-compatible API on port 11434.
3. Tailscale ACL: the AWS Lambda's Tailscale node identity is allowed to reach 10.42.0.10:11434. Nothing else on the local network is reachable.
4. A small Tailscale sidecar in the AI-sandbox account so Lambdas can join the Tailscale mesh. Lives in substrate/modules/platform/local-inference-mesh/. ~30 lines of TF.
5. A bearer token in Secrets Manager (secrets/local-inference-token) that the Mac Mini's reverse proxy enforces on every request. Belt and suspenders on top of the Tailscale ACL.
6. The network egress allowlist gains one entry: the Tailscale coordination server's domain. The Mac Mini itself is reached over the Tailscale mesh, not the public internet.
7. Route table entry for scout-local registered in the SSM manifest (Step 6.m, Section 2).
8. Operator flips the per-turn route in the obs Cartridges modal. Done.

What changes for golden-spec specifically: per-spec cost drops from $0.48 (Strategy C in the table above) to ~$0.48 (Strategy D, no change) because the writer turn still dominates. The interesting savings come from the Sonnet writer variant (Strategy E): with free scouts the writer can be Sonnet 4.5 without losing the quality benefits of multi-pass narrowing. Per-spec cost drops to ~$0.10. At 50 specs/day, that is $150/mo instead of $1,305/mo for naive single-vendor.

The fallback chain means Phase 1.5 does not raise availability risk. When the Mac Mini is unreachable, scout-local falls back to scout-cloud at $0.005-$0.03 per turn. The agent still runs. The obs Cartridges tab shows the fallback rate so the operator knows when the local backend is sick.

10. What's deferred

• The other 10 agents from paycargo-ai (code-review, qa, implement, impact, ai-intake, knowledge-base, react-migration, storybook, golden-spec-design, golden-spec-impl). Keep them on paycargo-ai's existing AgentCore setup. After golden-spec proves the doctrine, we choose per-agent: lift to the Forge with this pattern, lift to the Forge with the (future) AgentCore module, or leave on paycargo-ai and just observe.
• Knowledge base context injection. Ammar's agents/shared/knowledge/*.md (platform.md, payments.md, integrations.md, cpp.md) is rich context that improves agent output. The first version of this cartridge uses a slim version (just the system prompt + issue). When we want better quality, we copy the knowledge files into cartridges/engineering/code-agents/lambda/prompts/knowledge/ and prepend them to the system message.
• Multi-repo support. Day-1 only PayCargoDevOps/ai-sandbox is in the allowlist. Day-2 the cartridge.tf manifest takes a list of repo names and the webhook handler checks against it.
• The "knowledge-base" agent itself, which would maintain the knowledge files automatically. That's a separate cartridge (or a sub-agent of sdlc) when we're ready.
• The eventual decision: absorb paycargo-ai or keep it standalone. Defer until we have a month of data on golden-spec running on the Forge. If teams are happy with that one agent and the cost is acceptable, the absorb-vs-keep decision becomes a real cost-benefit conversation backed by real numbers.