Production Upgrade

Production Upgrade

Run a risk-adjusted, evidence-bound modernization from discovery through a pre-release maintainer checkpoint. The workflow is complete without a specific model, subagent implementation, or task tracker, but it must honor stronger project requirements when they exist.

Overview

The quality bar comes from the Databricks rebuild: understand real operator pain, decide architecture before implementation, move load-bearing logic into deterministic code, preserve compatibility intentionally, and prove safety with negative and adversarial evidence. Match the depth to risk rather than matching another project's document count.

When to use

Use for a legacy artifact, broad rewrite, breaking migration, unsafe integration, or production-readiness claim. Do not trigger for a small typo, isolated bug fix, routine dependency bump, or read-only status question unless the user explicitly requests the full upgrade workflow.

Prerequisites

• Target repository or artifact and its project instructions.
• Authority to research and prepare local changes. Publication, deployment, merge, destructive cleanup, and external messaging remain separate approvals.
• Current primary sources for externally defined contracts.

The pre-authorized Read, Write, and Edit capabilities apply only to local, scoped implementation files. Network, shell, task-tracker, subagent, install, and publication capabilities remain behind host and project approval.

Orchestration

Use five focused roles. When the host supports isolated subagents, dispatch the role packets under references/roles and have the coordinator reconcile their evidence. Otherwise execute the same packets sequentially in the main context. A same-identity or inline review is self-review, never independent.

Instructions

1. Recover context and establish authority

1. Read repository instructions, architecture owners, generated-file rules, current status, worktrees, active reviews, and existing task state.
2. If the repository uses Beads, follow references/beads-workflow.md: prime, search, create or reuse, claim before mutation, and attach receipts. Project policy can make Beads mandatory.
3. Preserve dirty work and contributor authorship. Isolate broad changes in a branch or worktree when available.
4. Record the exact initial revision and the actions currently authorized.

2. Research before designing

1. Audit the existing artifact, every active and retired capability, consumers, package identities, installation paths, and known defects.
2. Research current primary sources for product, API, protocol, security, and runtime contracts. Add community or issue evidence for real operator pain when accessible and appropriate.
3. Build a pain catalog: symptom, trigger, root cause, blast radius, current workaround, evidence, and the right agent primitive. Record source gaps rather than filling them with assumptions.
4. Compare at least one relevant production benchmark for methodology, then explain where narrower or deeper treatment is justified by risk.

3. Decide scope and safety

1. Consolidate capabilities around distinct operator outcomes, not quotas.
2. Write an architecture decision covering adopted, modified, and rejected alternatives; authority boundaries; compatibility; migration; rollback; and explicit non-goals.
3. Threat-model inputs, outputs, credentials, network destinations, file paths, dependencies, retries, mutations, reviewers, evidence, and publication.
4. Make offline or read-only behavior the default. Unknown contracts, statuses, fields, destinations, or permissions fail closed.
5. Put deterministic classification, arithmetic, validation, transformation, and policy decisions in reviewed scripts. Use model reasoning for synthesis and ambiguity, not for load-bearing calculations.

4. Plan and implement

1. Define measurable acceptance gates before editing. Include structure, behavior, security, migration, provenance, and release evidence.
2. Implement the smallest complete design. Keep the portable core independent of host adapters and avoid infrastructure that does not add verified capability.
3. Preserve IDs or provide a machine-readable migration map. Breaking behavior requires an explicit major-version decision and user-facing migration path.
4. Never generate plaintext secrets, remote-pipe installers, unbounded retries, silent destructive actions, fabricated provider responses, or blanket scanner waivers.