Dedenne: The Plastic Labs AI Factory

Status: Draft Owner: Vineeth Last updated: 2026-06-05

Table of Contents

1. Problem Statement
2. Goals and Non-Goals
3. Current State
4. Part 1: Repo Hygiene and CLAUDE.md
5. Part 2: Team Skill Catalog
6. Part 3: Wiki Reorganization
7. Part 4: ADR Backfill
8. Part 5: Human-in-the-Loop Question System
9. Part 6: Dogfooding — Honcho as Memory, Linear as Command Center
10. Part 7: The Factory Floor — Execution Substrates, Credentials, and Autonomous Ops
11. Implementation Phases
12. Open Decisions
13. Acceptance Criteria

---

1. Problem Statement

Dedenne started as a personal workbench for writing specs with full context across Plastic Labs’ codebases. It works — but it works for one person. The near-term goal is to make it the centralized hub of agentic development for the engineering team: any engineer clones dedenne, opens Claude Code, and has (a) full company context, (b) ready-made skills for recurring workflows, and (c) a wiki that both humans and agents can navigate and trust.

The end state is bigger: Plastic Labs as an AI factory — agents at every step of the engineering loop, constantly optimizing, auditing, and enhancing our output. Four layers, each owned by a part of this spec:

Layer	Owns	Spec
Knowledge	Wiki + Honcho memory — what we know and why	Parts 3–6
Command	Linear — what should happen next, human-legible	Part 6
Execution	Where agents run: local sessions, resident agent, cloud agents, aurorus VMs	Parts 2, 6, 7
Trust	What agents may touch: 1Password-provisioned credentials, access tiers	Part 7

The hub (Parts 1–5) is the foundation; the factory floor (Parts 6–7) is what it’s for.

Three gaps stand in the way:

1. The repo doesn’t present itself as a team tool. CLAUDE.md describes a personal spec workbench; the root has accumulated loose working artifacts (screening briefs, CSV dumps, zips, one-off scripts); .claude/skills/ contains a single irrelevant vendored skill; there is no onboarding path for a second engineer.
2. Recurring workflows are re-derived from scratch every session. Updating costs, checking spend trends, triaging Sentry, sweeping Linear, reviewing PRs, monitoring open-source activity on honcho — each is done ad hoc, with the prompt and the data-source knowledge living in someone’s head.
3. The wiki is good prose but a weak knowledge base. projects/ covers only Honcho and Groudon (the engineering index links to projects/kyogre, which doesn’t exist). Honcho’s ADRs are a single append-only file; Groudon has zero ADRs despite carrying the most institutional “why” (one-tenant-one-instance, shared Supabase schema, the placeholder pool, Xatu’s pipeline shape). When an agent can’t find the why, it either hallucinates one or asks a human mid-session — there’s no durable way for it to ask and for the answer to become permanent context.

2. Goals and Non-Goals

Goals

• A new engineer (or a fresh agent session) goes from git clone --recurse-submodules to productive context in one sitting, guided by CLAUDE.md.
• A catalog of dedenne-local skills (.claude/skills/) covering the team’s recurring operational workflows, each with documented data sources, auth prerequisites, and a safe-by-default mutation policy.
• A wiki information architecture where every active project has a home, every page has machine-readable frontmatter, and the org’s architectural decisions are captured as discrete, citable ADRs.
• Backfilled ADRs for Honcho and Groudon, produced by an agent pipeline that mines history and asks humans instead of inventing intent, via a versioned question queue.
• The hub dogfoods Honcho: hub agents use Honcho as their memory layer, Linear acts as the team’s command center with durable knowledge projected into the wiki, and the whole loop doubles as a standing eval of our own product.
• A factory floor: a substrate matrix for where agents run (local → resident → cloud → aurorus VMs), 1Password-provisioned scoped credentials as the trust layer, tiered devops agents, and chaos testing that turns past incidents into a standing resilience regression suite.

Non-Goals

• Packaging skills as an external plugin/marketplace. Skills are dedenne-local; dedenne is the working directory for these workflows. Promotion to a plugin (like the existing honcho plugin) is a possible later step, deliberately deferred.
• Replacing Linear, Sentry, or billing dashboards — skills read from and summarize these systems; they are not new UIs.
• Rewriting the overnight audit agent (agent/). It stays as-is; this spec only repositions it within the hub’s documentation.
• New services or infrastructure. Everything here is markdown, skills, and conventions.

3. Current State

Area	State
CLAUDE.md	Accurate on architecture, silent on team usage, skills, MCP integrations, hygiene rules
Repo root	~15 loose working artifacts (briefs, CSVs, zips, scripts, scratch notes) tracked or untracked at root
.claude/skills/	One vendored skill (remotion-best-practices), unrelated to the hub’s purpose
Integrations available	Linear MCP, Sentry MCP, Honcho plugin (memory + CLI), gh, fly; not inventoried anywhere
Wiki projects/	honcho/ (rich), groudon/ (good ops docs, no ADRs); missing: kyogre, excadrill, minccino, machamp, metagross, dedenne
ADRs	Honcho: one append-only adr.md (last substantial entry: Peer Paradigm era). Groudon: none
Specs	Healthy convention (projects/<p>/specs/, done/, .vN history) — keep as-is

4. Part 1: Repo Hygiene and CLAUDE.md

4.1 Workspace layout rules

• Create scratch/ (gitignored) as the designated home for working artifacts: screening briefs in progress, CSV pulls, one-off scripts, data dumps. Nothing transient lives at root.
• Sweep existing root clutter into scratch/ (or delete; owner decides item-by-item — several current artifacts like lock_monitoring.sql and the deriver-resilience notes look like they belong in the wiki, not in scratch).
• Rule of thumb, encoded in CLAUDE.md: if it’s worth keeping, it goes in the wiki; if it’s not, it goes in scratch/; root is for structure only.

4.2 CLAUDE.md updates

Reframe from personal workbench to team hub. Additions:

1. “Working here” section — clone instructions (--recurse-submodules), submodule update cadence (git submodule update --remote --merge, commit bumps weekly or when starting significant work), the scratch/ rule.
2. Integration inventory — a table of what agents can reach and what auth each needs: Linear MCP (issue triage, drafting), Sentry MCP (error review), Honcho plugin (team memory + honcho CLI), gh (PRs, OSS audit), fly (instance state, read-only by default). This is the single place a session learns what it’s allowed to touch.
3. Skill catalog section — one line per skill (Part 2), so the agent knows the catalog exists without loading every SKILL.md.
4. Wiki conventions pointer — frontmatter schema, ADR process, question-queue process (Parts 3–5), so agents writing to the wiki follow the IA instead of inventing structure.
5. Operational guardrails — mutations to external systems (Linear issues, Sentry assignments, anything billing) default to dry-run output with exact commands for the human to run; skills that write to the wiki commit but never push without review.
6. Drift fixes — wiki section list updated as Part 3 lands; repos/aurorus added to the repo-layout table and pokedex when the submodule lands (Part 7).

5. Part 2: Team Skill Catalog

5.1 Conventions (apply to every skill)

• One directory per skill under .claude/skills/<name>/ with a SKILL.md (frontmatter: name, description with explicit trigger phrases).
• Read-only by default. Skills that can mutate external state take an explicit --execute; without it they print a dry-run plan with exact CLI commands.
• Every skill documents: data sources, auth prerequisites, expected runtime, output destination (stdout report / wiki page / Linear draft).
• Reports that have durable value (spend trends, OSS audit) write dated pages into the wiki under engineering/reports/<topic>/YYYY-MM.md rather than vanishing in the terminal.

5.2 Catalog

Skill	Purpose	Sources	Writes
/update-costs	Refresh projects/groudon/costs.md and the platform cost model	Fly billing, GCP/BigQuery billing export, Supabase, Turbopuffer, LLM provider invoices (CSV drops into scratch/ accepted as input)	Wiki (costs pages), dated
/spend-trends	Spend report vs ~$60k/mobaselineandthe$2/M-input-token unit-economics target; month-over-month deltas, anomaly callouts	Same as /update-costs + Xatu usage data	Wiki report page
/sentry-triage	New / regressed / high-volume issues across honcho, groudon, kyogre; cluster by root cause; propose priorities	Sentry MCP	Stdout; Linear drafts with --execute
/linear-sweep	Cycle status, stale in-progress issues, untriaged inbox, draft well-formed tickets (team/label conventions encoded in the skill)	Linear MCP	Stdout; issue creation behind --execute
/code-review	Review a PR in any submodule with that repo’s conventions loaded (each submodule’s agent doc is the rubric source)	gh, submodules	PR review comments behind --execute
/oss-audit	Community activity on plastic-labs/honcho: new issues/PRs/discussions, first-time contributors, response-time SLA breaches, stale PRs; draft maintainer replies	gh	Stdout + wiki report; replies behind --execute
/wiki-gardener	Lint the wiki: broken links, missing/invalid frontmatter, stale last-verified dates, orphan pages, open question count (Part 5)	wiki/	Wiki fixes as a reviewable commit
/adr-backfill	Mine a project’s history and draft ADRs (Part 4)	git log, merged PRs, specs/done/, Linear, wiki ops docs	Draft ADRs + question queue entries
/integration-watch	Track releases/changelogs of integration partners; detect breaking changes and new capabilities affecting Honcho’s integrations; propose fixes/features an agent can implement (see 5.4)	Web (changelogs, release feeds, docs diffs), gh releases, watch-list state file	Wiki report + Linear proposal drafts; implementation PRs behind --execute
/linear-wiki-sync	Project Linear work state into the wiki, promote wiki-labeled Linear docs, report drift, maintain back-links (see 9.3)	Linear MCP, wiki/	Wiki frontmatter + promoted pages as reviewable commits
/gtm-audit	Check GTM surfaces (docs site, website claims, pricing page, onboarding flow) against shipped reality; surface funnel/usage anomalies	Web/browse, PostHog, docs	Wiki report; Linear drafts
/adr-audit	Detect drift between accepted ADRs and current code/infra; propose status flips (accepted → superseded) with evidence	repos/, wiki adr/	Wiki report + proposed ADR edits
/test-health	Test-suite health across repos: flaky tests, coverage drift, CI duration trends	gh (Actions), Ivysaur runs	Wiki report
/eval-research	Auto-research for eval and prompt/harness optimization: new papers, techniques, and model releases relevant to memory benchmarks; propose concrete Excadrill/Minccino/Machamp experiments	Web search, arXiv, Excadrill registry	Wiki report + experiment proposals as Linear drafts

Existing capabilities are referenced, not duplicated: the honcho plugin already covers queue/memory introspection (honcho-cli); the audit agent covers overnight code audits.

5.4 /integration-watch (detail)

The most autonomous skill in the catalog — it closes the loop from external change to proposed (or shipped) code — so it gets explicit stages with escalation gates between them.

Watch list — a versioned config (.claude/skills/integration-watch/watchlist.yaml), one entry per partner surface:

- name: vercel-ai-sdk
  sources:
    - https://github.com/vercel/ai/releases        # gh API, no scraping needed
    - https://ai-sdk.dev/docs/...                  # docs pages worth diffing
  ours: wiki/.../honcho/integrations/ai-sdk-spec.md, sdks/typescript
  concern: provider interface changes, middleware/streaming API changes

Initial entries: Vercel AI SDK, MCP spec revisions, Anthropic/OpenAI/Gemini SDKs (the src/llm/ backends pin these), Cloudflare Workers runtime (Kyogre), bot frameworks we ship integration guides for. Anyone can add an entry; the skill validates the file on each run.

Pipeline (per run):

1. Fetch & diff — pull each source, compare against the last-seen state (content hashes + release tags stored in a state file committed alongside the watchlist). No state change → no output, exit quietly.
2. Classify — for each change, decide: breaking (our integration will break or already has), opportunity (new capability worth supporting — a new streaming protocol, a new tool-use shape), or noise. Classification must cite the changelog line/diff hunk and the affected file in our code.
3. Propose — for breaking/opportunity items, produce a structured proposal: what changed, evidence links, affected Honcho/SDK surface, sketch of the fix or feature, estimated blast radius. Written as a dated wiki report (engineering/reports/integration-watch/) and, with --execute, drafted as Linear issues tagged for triage.
4. Implement (gated) — a proposal marked auto-implementable (mechanical compat fixes: renamed import, bumped peer dep, signature change with an obvious mapping) can be handed to an implementation agent: branch in the affected repo, apply the fix, run that repo’s test suite, open a draft PR linking the proposal. Never merges. Anything judgment-shaped (API design, new feature surface) stops at the Linear proposal — a human promotes it to implementation.

Guardrails:

• Stage 4 never runs without --execute, and only on proposals the classifier marked mechanical and a human hasn’t vetoed in Linear.
• The proposal, not the PR, is the primary artifact — a wrong proposal costs a triage glance; a wrong auto-PR costs review trust.
• Runs on a weekly cadence with the other recurring skills (Phase 4); the state file keeps re-runs idempotent.

5.3 Rollout waves

• Wave 1 (read-only reporters): /sentry-triage, /linear-sweep, /oss-audit, /spend-trends, /integration-watch stages 1–3 (watch → classify → propose). Low risk, immediate daily value, exercises every integration.
• Wave 2 (mutating, dry-run-gated): /update-costs, /code-review, Linear/reply execution paths in wave-1 skills.
• Wave 3: /adr-backfill + /wiki-gardener at full scale, once Part 3’s conventions exist for them to enforce; /integration-watch stage 4 (auto-implementation of mechanical fixes) last — it’s the highest-autonomy capability in the catalog and should inherit trust earned by the earlier waves.

6. Part 3: Wiki Reorganization

6.1 Information architecture

Standardize engineering/projects/<codename>/ for every active project in the pokedex:

projects/<codename>/
├── index.md          # What it is, repo link, status, key people, links below
├── architecture.md   # How it works (diagrams encouraged)
├── adr/              # One decision per file (see 6.3)
│   └── questions.md  # Open question queue for this project (Part 5)
├── runbook.md        # Ops: deploy, debug, common failures (where applicable)
└── specs/            # Existing convention, unchanged
    └── done/

Create missing project dirs: kyogre/, excadrill/, minccino/, machamp/, metagross/, dedenne/ (this spec is its first artifact). Xatu stays under groudon/ (it lives in that repo) but gets its own architecture section and ADRs in Groudon’s tree. Existing Honcho/Groudon pages are mapped into this structure, not rewritten — e.g., groudon/honcho-debugging.md becomes/feeds groudon/runbook.md.

6.2 Conventions for agents and humans

• Frontmatter schema on every page: title, date (created), last-verified (a human or gardener attests the content is still true), optional status (draft/current/superseded), tags.
• Every directory has an index.md that links its children with one-line descriptions — agents navigate by reading indexes, not by globbing.
• Stable slugs — renames break agent citations and Quartz links; prefer additive edits.
• Facts near the top, narrative below — agents (and skimming humans) should get the load-bearing claims in the first screen.
• /wiki-gardener enforces all of the above mechanically.

6.3 ADR format

Move from append-only monolith to one decision per file: adr/NNNN-short-slug.md.

---
title: "ADR-0007: Gateway re-mints Honcho JWTs"
status: draft | accepted | superseded
date: <decision date if known, else "backfilled YYYY-MM-DD">
confidence: high | medium | low      # backfilled ADRs only
---
## Context        — what problem existed, what constraints applied
## Decision       — what was decided
## Consequences   — what it costs us / enables, known follow-ups
## Sources        — PRs, commits, specs, Linear issues, wiki pages cited
## Open questions — links into adr/questions.md (must be empty for `accepted`)

Honcho’s existing adr.md is preserved as the historical log and linked from adr/index.md; its content seeds the first backfilled entries.

7. Part 4: ADR Backfill

7.1 Pipeline

For each project (Groudon first — largest gap, freshest institutional memory; then Honcho):

1. Mine — /adr-backfill walks git history, merged PR descriptions, specs/done/, wiki ops docs, and Linear for decision-shaped events (schema choices, service boundaries, dependency adoptions, reversals).
2. Draft — one ADR per decision into adr/ with status: draft, a confidence rating, and every claim cited in Sources. The agent never asserts intent it cannot cite. Where the what is clear but the why is not, the why is phrased as a hypothesis and flagged.
3. Ask — unresolved-intent items become entries in the project’s question queue (Part 5). A draft with open blocking questions cannot be promoted.
4. Review & accept — a human reviews the draft (answers queued questions in the same pass), flips status: accepted. Acceptance is a deliberate human act, always.

7.2 Initial backfill targets

• Groudon: one-tenant-one-instance on Fly; shared Supabase Postgres with single groudon schema; placeholder instance pool; gateway JWT re-minting and routing model; Xatu as CloudEvents → Redpanda → S3/Stripe (vs. direct Stripe reporting); health-service recovery model.
• Honcho: entries the monolith already narrates (Peer Paradigm, metamessage removal) split into discrete ADRs; then queue/work-unit structure, deriver batching (“minimal deriver”), session-scoping and search strategy, LLM-layer refactor (sources: specs/done/llm-client-refactor.md), embedding decoupling (MessageEmbedding.sync_state).

8. Part 5: Human-in-the-Loop Question System

The mechanism that lets agents ask instead of invent — versioned in git, async-friendly, usable by background runs.

8.1 The question queue

One questions.md per project (projects/<p>/adr/questions.md), structured entries:

## Q-GRDN-0003: Why does the gateway re-mint Honcho JWTs instead of passing through?
- status: open            # open | answered | wont-answer
- asked: 2026-06-05 (adr-backfill)
- blocking: [[0007-gateway-jwt]]
- context: Gateway validates the tenant API key, then constructs a fresh
  Honcho JWT per request (groudon/gateway/auth.py). Pass-through of a
  long-lived instance token would be simpler. Hypotheses: (a) per-request
  scoping limits blast radius of a leaked token; (b) instance JWTs predate
  the gateway and rotating them per-tenant was operationally painful.
- answer:                 # human fills in; agent incorporates and flips status

Rules:

• Questions carry evidence and competing hypotheses, never bare “why?” — the human should be able to answer in one or two sentences.
• Each question links the draft(s) it blocks; each draft’s Open Questions section links back.
• Agents batch questions per run rather than dribbling them.
• In an interactive session, the agent may ask via AskUserQuestion directly — but must record the answer into the queue file afterward, so the knowledge is durable rather than trapped in one transcript.
• Answered questions stay in the file (status flipped) — the queue doubles as a decision-context archive.

8.2 Surfacing

• /wiki-gardener reports open-question counts per project and ages; stale open questions (>2 weeks) get escalated in its summary.
• An engineer can answer by editing the file directly, or conversationally (“answer the open groudon questions”) with the agent applying answers and updating affected drafts.

9. Part 6: Dogfooding — Honcho as Memory, Linear as Command Center

The hub shouldn’t just use agents — it should run on the products we sell. The three pieces below compose into one loop:

flowchart LR
    L[Linear<br/>command center] -->|agent-labeled issues,<br/>cron, webhooks| H[Resident agent<br/>'hermes']
    H -->|runs dedenne skills| O[Outputs]
    O -->|status, drafts, results| L
    O -->|knowledge as PRs| W[Wiki<br/>canonical knowledge]
    H <-->|peer memory| M[(Honcho<br/>plastic-labs workspace)]
    C[Claude Code sessions<br/>interactive, per-engineer] <-->|peer memory| M
    C -->|specs, ADRs, reports| W
    W -->|ingested context| M

Linear commands. Agents execute. The wiki receives knowledge. Honcho remembers intent. Ordered below from committed design to experiment.

9.1 Honcho as the hub’s memory (committed)

Hub sessions already run with the Honcho plugin (peer claude, engineers as peers). Make it load-bearing:

• Workspace topology — one plastic-labs workspace. Peers: each engineer, claude (interactive sessions), hermes (resident agent, 9.2). Recurring skill runs are sessions, so memory accrues per-workflow as well as per-peer. This dogfoods multi-peer sessions and observation settings on a real, daily workload.
• Intent capture compounds — when a question-queue entry (Part 5) is answered, the session ingests the Q+A into Honcho. /adr-backfill queries dialectic first (“do we know why the gateway re-mints JWTs?”) and only escalates to the question queue on a miss. Intent answered once is never asked twice. The wiki stays canonical (the queue file is still written); Honcho is the recall path.
• Company-state peer — a plastic-labs-co peer whose global representation is built by ingesting the artifacts skills already produce: spend reports, OSS audits, Linear cycle snapshots, accepted ADRs. “What’s the state of the company?” becomes a dialectic query instead of a context-stuffing exercise. This dogfoods arbitrary-data ingestion and global representations — the exact pattern we tell customers to use.
• Standing eval — every skill that queries dialectic logs hit/miss quality (did recall surface the right context, at which reasoning tier, at what cost). Misses become honcho issues. The hub turns into a continuous, honest eval of our own memory product on knowledge-work traffic — a workload profile our benchmarks (Excadrill) don’t currently cover. Default reports to low dialectic tiers; reserve high/max for ADR-intent recall where a miss costs a human interruption.

9.2 Resident agent as kickoff point (design)

An always-on agent — working name hermes — deployed adjacent to our Honcho deployment (candidate hosts: a Fly machine next to the API, or Porygon/Varoom), acting as the hub’s executor when no engineer has a terminal open:

• Triggers: Linear issues labeled agent:<skill> (the command-center contract, 9.3), cron (weekly /oss-audit, /spend-trends, /integration-watch), and webhooks (Sentry alert spike → /sentry-triage).
• Execution: clones/holds a dedenne checkout, runs the relevant skill headless, posts results back to the triggering Linear issue, and opens wiki changes as PRs — never direct pushes.
• Memory: participates in the plastic-labs workspace as peer hermes. Engineers’ interactive sessions can recall what hermes did and learned, and vice versa — cross-agent memory through Honcho rather than through transcript archaeology. This is the strongest dogfood in the spec: it’s exactly the multi-agent memory story we pitch.
• Authorization: inherits the skill catalog’s gates — --execute paths require the label to be applied by a human (the label is the approval), and anything outside the catalog is refused. Hermes runs skills; it does not freelance.

9.3 Linear command center + wiki sync (committed)

Linear becomes the team’s command surface without letting knowledge rot there. One ownership rule, enforced mechanically:

Linear owns work state. The wiki owns knowledge. Sync is projection + drift detection — never bidirectional merge.

A new skill, /linear-wiki-sync (run by hermes on cadence, or manually):

• Status projection — Linear project/initiative status is projected into wiki project index.md frontmatter (linear-project:, status:, current-cycle:). Humans and agents reading the wiki see live work state without leaving it.
• Document promotion — Linear documents labeled wiki get promoted into wiki pages with provenance frontmatter (source: linear-doc <id>, synced: <date>). After promotion the wiki copy is canonical; the Linear doc gets a banner link pointing home. PRDs and RFC discussions stop dying in Linear.
• Drift report — claims the wiki makes about work state (“kubernetes migration: in progress”) checked against Linear reality; mismatches land in the gardener summary.
• Back-links — every accepted ADR and shipped spec is linked into the Linear issues that produced it, so ticket archaeology always leads to the durable artifact.
• The agent queue — agent:<skill> labeled issues form hermes’ work queue (9.2). Filing a Linear issue is dispatching an agent; the issue thread is the run log a non-technical teammate can read.

9.4 LLM-wiki agent (experiment)

The wiki splits into two kinds of pages, declared in frontmatter:

• Narrative pages (authored: human) — ADRs, specs, design discussions. Humans own them; acceptance remains a human act.
• Generated pages (authored: agent) — fact-shaped pages regenerated from ground truth whenever sources change: the system map, infra/integration inventories, costs, the pokedex status column. The wiki agent owns these; the gardener flags (and eventually reverts) manual edits with a pointer to the generator instead.

The experiment: pick 2–3 fact-shaped pages, give the wiki agent their source-of-truth recipe (which code, configs, Linear projects, billing exports to read), run regeneration on cadence for a month. Success: generated pages catch drift faster than humans did, and nobody hand-edits them in frustration. Failure: regeneration churns prose without catching real drift, or humans route around it. Graduate or kill on that evidence; if it works, the company-state peer (9.1) ingests generated pages as its freshest signal.

10. Part 7: The Factory Floor — Execution Substrates, Credentials, and Autonomous Ops

Parts 1–6 give agents knowledge, workflows, memory, and a command channel. The factory floor is where they actually run, what they’re allowed to touch, and the aggressive workloads (devops, chaos) that only become safe once substrates and credentials are right.

10.1 Execution substrates

No single substrate fits every workload. The factory runs on a matrix, and every skill declares which substrates it may run on:

Substrate	What it is	Best for	Trust ceiling
Local session	Claude Code on an engineer’s machine	Interactive work: specs, reviews, debugging	Engineer’s own credentials; human watching
Resident agent (hermes)	Always-on, adjacent to our Honcho deploy (9.2)	Cadenced skills, Linear-queue dispatch	Catalog skills only; --execute = human label
Cloud agents	Claude Code cloud sessions; evaluate Devin, Codex cloud as comparators	Parallel ticket burn-down, /integration-watch stage-4 implementation runs, audit-agent sweeps at fleet scale	Sandboxed repo access; no infra credentials
Aurorus VMs	Azure VM environments via jumpboxes (repos/aurorus, to be added as a submodule)	Workloads needing network position or isolation: chaos runs, load tests (Loudred), devops agents touching private networks, untrusted/heavy jobs	Scoped per-VM credentials from 1Password (10.2); torn down after run

Cloud agent evaluation (a deliberate, written bake-off, not an ambient adoption): score Claude Code cloud sessions vs. Devin vs. Codex cloud on — repo/secret access model, MCP support (Linear/Sentry from inside the sandbox), cost per completed task, reviewability of output (draft PRs with legible history), and how well they consume our CLAUDE.md/skills conventions. The bake-off task is real: a batch of agent:-labeled Linear issues from the mechanical end of the backlog. Output: a wiki report and a recommendation ADR.

Aurorus gives the factory its self-hosted heavy substrate: spin up a VM, agent enters via jumpbox, does its work with injected scoped credentials, environment is destroyed. Adding it to dedenne means: submodule under repos/aurorus, pokedex entry, projects/aurorus/ wiki dir with runbook, and a CLAUDE.md row in the repo-layout table. Open security questions in §12.

10.2 Credential provisioning via 1Password

The trust layer. Agents never hold long-lived secrets; they’re provisioned at task start and scoped to the task:

• Vault-per-tier — 1Password vaults map to access tiers (10.3): agents-observability (Sentry, Logflare, PostHog, fly read tokens), agents-staging, agents-prod-gated. A substrate gets a service account bound to the vaults its tier permits — nothing broader.
• Injection, not storage — skills resolve secrets at runtime via op run -- <command> / op read op://vault/item/field. No secrets in ~/.dedenne configs (the audit agent migrates to this), no .env files in checkouts, nothing in repos. Dry-run output shows the op references, never values.
• Short-lived where possible — prefer minting ephemeral tokens (fly tokens, scoped GitHub installation tokens, Honcho scoped JWTs) over reading static keys; the static key stays in the vault, only the derived short-lived token reaches the agent.
• Audit trail for free — 1Password service-account event logs answer “which agent read which credential when,” which is the question every autonomous-ops incident review starts with.

Agent identity: capabilities minted at creation. Long-lived shared secrets in vaults are the floor; the ceiling is per-agent identity. When an agent instance is created (a hermes deploy, a cloud session, an aurorus VM run), a provisioner mints it a token set from a declared capability manifest — and that token set is its permissions, so scoping can’t drift from reality:

# capability manifest → minted tokens, stored as a per-instance vault item
dedenne agent mint --name chaos-runner-07 \
  --caps gh:honcho:push-pr,honcho:plastic-labs:read,fly:staging:deploy \
  --ttl 8h --dry-run     # prints what would be minted and from which issuer

Per system, the mintable scoped option:

System	Mechanism	Typical agent scope
GitHub	GitHub App installation token (1h TTL, per-repo, per-permission — fine-grained PATs can’t be minted via API, so a plastic-labs-agents App is the issuer)	contents:write + pull_requests:write on named repos: push agent/* branches, open PRs, never merge
Honcho	Scoped JWT via the existing /v3/keys endpoint — workspace/peer/session-scoped. This is a dogfood: our own key-scoping feature provisions our own agents	Workspace plastic-labs, read-only or peer-scoped write
Linear	Team-scoped API key / actor tokens	Single team, issue create/comment, no project admin
Fly	fly tokens create org/app-scoped deploy tokens	Named staging apps only (T1)

Lifecycle: mint at creation → store as a vault item named for the instance → inject via op run → revoke at teardown (the provisioner owns both ends; an aurorus VM teardown that skips revocation is a bug, and short TTLs are the backstop). The capability manifest lives next to the skill/substrate config in git, so “what could this agent touch?” is answerable by reading a YAML file, and diffs to it get human review like any code change.

10.3 DevOps agents and access tiers

DevOps agents are skills + substrate + tier, not a new species. Three tiers, enforced by which vault the substrate’s service account can reach:

Tier	May touch	Example workloads
T0 — Observe	Sentry, logs, metrics, fly status, DB read replicas	/sentry-triage, spend reports, incident timelines, queue-depth checks
T1 — Staging-mutate	Staging/dev instances, placeholder-pool instances, scratch tenants	Deploy-to-staging, migration rehearsal, chaos runs (10.4), restarting a wedged dev deriver
T2 — Prod-mutate (gated)	Production, behind a human approval per action	Instance recovery beyond what Groudon’s health service automates, scaling actions, coordinated deploys

T2 actions follow the established pattern: the agent produces the exact commands (fly machine restart <id> --app <app>, dry-run output first) and a human — or a human-applied Linear label — pulls the trigger. Groudon’s health service already automates a slice of T2 recovery; devops agents extend the playbook around it rather than replacing it, and every T2 runbook the agents follow lives in the relevant project’s wiki runbook.md so humans can execute the same steps by hand.

10.4 Chaos engineering for Honcho environments

The factory’s auditing instinct pointed at resilience. A /chaos-run skill (T1, aurorus or disposable Fly environments only):

1. Provision a disposable Honcho environment — real schema, seeded workload, with Muk (mock OpenAI) and Piplup (mock Fly API) standing in for external dependencies so faults are injectable and runs are cheap.
2. Inject from a fault library, one fault per run: kill the deriver mid-batch, saturate the connection pool (the Supavisor advisory-lock incident, reproduced on purpose), drop Redis, wedge an LLM provider (Muk returns 529s/timeouts), partition the queue’s Postgres, crash an instance during provisioning (Piplup).
3. Observe recovery against written expectations: does the work unit re-claim without ordering violations? Does the health service recover the instance? What do queue depth and error rates do, and how long until steady state?
4. Report — findings as a dated wiki report; deviations from expected recovery become Linear issues with reproduction recipes; recurring runs make it a regression suite for resilience, the same way tests are for correctness.

The fault library starts from incidents we’ve actually had (each past incident becomes a permanent chaos scenario — institutional memory as executable tests) and grows from /sentry-triage clusters. Loudred load profiles can layer on top to chaos-test under load.

10.5 The report plane

The factory’s “constant auditing” promise is only real if every checked action leaves a structured trace and gaps are impossible to miss. Three pieces:

1. Structured reports. Every recurring skill writes its output as engineering/reports/<skill>/YYYY-MM-DD.md with machine-readable frontmatter:

skill: adr-audit
run: 2026-06-12 (hermes, T0)
status: findings        # ok | findings | failed
metrics: { adrs-checked: 14, drift-found: 2 }
findings:
  - severity: medium
    summary: "ADR-0004 says pgvector-only; turbopuffer is now default in prod"
    linear: DEV-2104

Prose below the frontmatter for humans; the frontmatter is what digests, trends, and the company-state peer consume.

2. The audit register. One wiki page (engineering/reports/register.md) listing every regular checked action — GTM audit, ADR audit, backlog audit (/linear-sweep), integration/plugin monitoring (/integration-watch), test health, eval research, chaos runs, spend trends, OSS audit — with cadence, owning skill, last run, last status. The gardener flags overdue entries: a check that didn’t run is itself a finding. Adding a row to the register is how a new recurring audit becomes real.

3. The factory digest. A /factory-report skill (run weekly by hermes) rolls up everything since the last digest: what ran and what silently didn’t, new findings by severity with Linear links, trend deltas (spend vs. baseline, OSS responsiveness, test flakiness, dialectic hit rate from 9.1), open-question and stale-draft counts. Published as a wiki report, posted as a Linear status update, ingested by the company-state peer — so “how’s the factory running?” is answerable by reading one page or asking one dialectic query.

/eval-research deserves a note: it’s the factory pointed at the ML loop. It watches for new memory-benchmark papers, prompting/harness techniques, and model releases, then proposes concrete, runnable experiments — an Excadrill registry entry, a Minccino recipe variation, a Machamp config — rather than literature summaries. Proposals land as Linear drafts for 3un01a/ML review; accepted ones become tracked experiments whose results feed back into the next digest.

11. Implementation Phases

Phase	Work	Effort
0	Root sweep into scratch/, gitignore, CLAUDE.md rewrite (Part 1)	~half day
1	Wiki IA: project dir scaffolding, frontmatter schema, index pages, ADR template, map existing pages into structure (Part 3)	~1 day
2	Wave-1 skills (read-only reporters) + /wiki-gardener v0 (lint only)	~1–2 days
3	/adr-backfill + question queue; run Groudon backfill end-to-end as the pilot; human review cycle. Honcho memory wired in: Q+A ingestion + dialectic-first recall (9.1)	~2 days agent time + review
4	Honcho backfill; wave-2 mutating skills; /linear-wiki-sync; recurring cadence (weekly /oss-audit, /spend-trends, gardener via cron/loop)	ongoing
5	Resident agent (hermes) deployed with the agent:<skill> Linear queue (9.2–9.3); company-state peer; LLM-wiki experiment on 2–3 generated pages (9.4)	~2–3 days + 1-month experiment window
6	Factory floor: 1Password vault-per-tier setup + op run migration (10.2); agent-identity provisioner (dedenne agent mint) with the GitHub App as first issuer; aurorus submodule + wiki dir; cloud-agent bake-off on real Linear backlog (10.1); first /chaos-run scenario (the Supavisor advisory-lock reproduction) end-to-end (10.4)	~1.5 weeks spread out + bake-off window
7	Report plane: structured-report frontmatter adopted by all recurring skills, audit register page, /factory-report weekly digest; second-ring audits (/gtm-audit, /adr-audit, /test-health, /eval-research) onboarded one at a time via register rows	ongoing

Phase 3 is the proving ground: if the question queue produces answerable questions and accepted ADRs for Groudon, the system works. Phase 5 only starts once the skills it would automate have proven themselves under human operation. Within Phase 6, credentials (10.2) land first — no T1+ workload runs on any substrate until secrets come from scoped vaults.

12. Open Decisions

1. Submodule bump cadence — weekly cron vs. manual-on-demand. Stale submodules silently poison agent context; a weekly bump PR is probably right.
2. Report retention — do dated spend/OSS reports accumulate forever under engineering/reports/, or does the gardener prune to last N + yearly rollups?
3. Skill promotion path — criteria for graduating a dedenne-local skill to the plastic-labs plugin so it works inside honcho/groudon checkouts directly (deferred per Non-Goals, but the bar should be written down when the first candidate appears).
4. Linear team conventions — /linear-sweep and /sentry-triage need the canonical team/label/priority mapping encoded once; where does that live (skill body vs. wiki page the skill reads)?
5. Resident agent host and runtime — Fly machine adjacent to the Honcho API vs. Porygon/Varoom; Claude Code headless vs. a Hermes-native runtime. Decide when Phase 5 starts; the skill catalog is runtime-agnostic by design so this can stay open.
6. Honcho workspace topology — one plastic-labs workspace for everything vs. separate workspaces for hub memory and the company-state peer. One workspace is the better dogfood (multi-peer observation settings get real exercise) but mixes concerns; decide before 9.1 ingestion starts.
7. Dialectic spend budget for the hub — recall-on-every-backfill-question is the right dogfood but has a real cost curve ($0.001–$0.50/query across tiers); set a monthly cap and a default tier per skill before hermes runs unattended.
8. Aurorus security posture — jumpbox access model for agents (who mints the SSH/Tailscale path, session recording or not), VM egress policy (can a chaos VM reach anything but its targets?), and teardown guarantees. Needs a short security review before the first agent-driven run; the answers belong in projects/aurorus/runbook.md.
9. Cloud agent vendor — resolved by the 10.1 bake-off, recorded as an ADR. Until then, no standing cloud-agent fleet; one-off cloud sessions are fine.
10. 1Password service-account blast radius — one service account per substrate vs. per skill-tier pair. Per-substrate is simpler; per-pair gives cleaner audit attribution. Decide when creating the vaults (10.2).
11. Agent identity issuer granularity — one plastic-labs-agents GitHub App for all agents (simple, but PRs are attributed to one bot) vs. per-substrate Apps (cleaner attribution in review history). Same question echoes for Linear actor tokens. Decide when the provisioner is built.
12. /gtm-audit scope — “GTM surfaces vs. shipped reality” needs a concrete checklist (docs claims? pricing page? onboarding funnel metrics from PostHog? competitor positioning?) and an owner on the growth side before it joins the register. Currently the fuzziest skill in the catalog — scope it at kickoff, not mid-build.

13. Acceptance Criteria

• A new engineer clones dedenne, follows CLAUDE.md, and a fresh Claude session can correctly answer: “how does tenant provisioning work?”, “what’s our current cloud spend trend?”, “what ADRs govern the queue design?” — citing wiki pages, not improvising.
• Repo root contains only structural directories and documented files; scratch/ absorbs working artifacts.
• Every active pokedex project has projects/<codename>/index.md; the engineering index has no dead links.
• ≥ 5 accepted ADRs for Groudon and ≥ 5 for Honcho, each with cited sources, produced through the backfill + question-queue pipeline.
• Question queue demonstrated end-to-end: agent asks → human answers in-file → agent updates draft → human accepts.
• Wave-1 skills runnable by any team member with the auth checklist in CLAUDE.md; every mutating path demonstrates its dry-run output.
• /integration-watch demonstrated end-to-end on one real partner change: detected → classified with citations → Linear proposal → (if mechanical) draft PR passing the target repo’s test suite.
• Memory dogfood proven: an ADR-intent question answered once in the queue is later recalled via dialectic by a different session (different peer) without re-asking the human.
• Command-center loop proven: a human applies agent:<skill> to a Linear issue → hermes runs the skill → results post to the issue → durable knowledge lands in the wiki via PR.
• /linear-wiki-sync drift report runs on cadence with zero unexplained mismatches after the first reconciliation pass.
• LLM-wiki experiment has a written graduate/kill verdict backed by the month’s edit history.
• No agent workload above T0 reads a secret from anywhere but a scoped 1Password vault; op event logs can attribute every credential read to a substrate and run.
• Cloud-agent bake-off completed on real backlog issues with a written recommendation ADR.
• First chaos scenario (Supavisor advisory-lock reproduction) runs end-to-end on a disposable environment: provision → inject → observe → wiki report, with at least one expectation-vs-reality finding filed.
• Aurorus onboarded: submodule, pokedex entry, wiki dir with runbook, and its security open decision (#8) resolved before first agent run.
• Agent identity demonstrated end-to-end: dedenne agent mint provisions a capability-scoped token set from a manifest, the agent pushes an agent/* branch and opens a PR with it, and teardown revokes everything — verified by the token no longer working.
• Audit register live with every recurring check listed; gardener flags an intentionally-skipped run as overdue (tested, not assumed).
• Two consecutive weekly /factory-report digests published, each consumed three ways: wiki page, Linear status update, company-state peer ingestion.
• /eval-research produces at least one proposal that the ML side accepts and runs as a tracked Excadrill/Minccino/Machamp experiment.