diff --git a/docs/superpowers/plans/2026-05-13-shipping-launch-safe-automation.md b/docs/superpowers/plans/2026-05-13-shipping-launch-safe-automation.md new file mode 100644 index 00000000..a22a3b0b --- /dev/null +++ b/docs/superpowers/plans/2026-05-13-shipping-launch-safe-automation.md @@ -0,0 +1,150 @@ +# Shipping Launch Safe Automation Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) +> or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax +> for tracking. + +**Goal:** Improve `shipping-and-launch` so agents automatically perform safe launch-preparation work while +stopping for approval before risky or externally visible actions. + +**Architecture:** Modify only the existing `plugins/me/skills/shipping-and-launch/SKILL.md` skill. Add an +automation policy, execution workflow, decision categories, and `/ship` relationship near the top while +preserving the existing launch checklist, feature flag, staged rollout, monitoring, and rollback reference +content. + +**Tech Stack:** Markdown skill file with YAML frontmatter, bstack `me` plugin conventions, markdownlint, BATS. + +--- + +## File Structure + +- Modify: `plugins/me/skills/shipping-and-launch/SKILL.md` — add safe automation behavior and clarify handoff to `/ship`. +- No README change planned because the lifecycle summary already describes this skill accurately. + +### Task 1: Add safe automation policy + +**Files:** + +- Modify: `plugins/me/skills/shipping-and-launch/SKILL.md` + +- [ ] **Step 1: Read the existing skill** + +Run: `sed -n '1,120p' plugins/me/skills/shipping-and-launch/SKILL.md` +Expected: YAML frontmatter, overview, when-to-use, and pre-launch checklist are visible. + +- [ ] **Step 2: Insert automation policy after Overview** + +Add a new `## Automation Policy` section after the Overview paragraph. The section must say the agent +should first do safe, read-only or local reversible work automatically, then stop for approval before risky +actions. + +Include these auto-allowed bullets: + +```markdown +The agent may do these without asking first: + +- Inspect git status, diffs, recent commits, changed files, and PR/CI status. +- Run local read-only or reversible verification such as tests, lint, type checks, builds, audits, and focused smoke checks. +- Draft launch artifacts: rollout plan, rollback plan, monitoring checklist, post-launch verification checklist, and release notes. +- Identify missing owners, dashboards, feature flags, environment variables, documentation, or runbooks. +- Classify findings as `AUTO-COMPLETED`, `NEEDS_APPROVAL`, `BLOCKED`, or `READY_FOR_SHIP_REVIEW`. +``` + +Include these approval-required bullets: + +```markdown +The agent must ask before doing these: + +- Push branches, create or merge PRs, tag releases, or publish packages. +- Deploy to staging or production, trigger release workflows, or change infrastructure. +- Modify feature flags, production configuration, secrets, environment variables, DNS, SSL, or databases. +- Send external notifications, Slack messages, GitHub comments, status page updates, or customer-facing announcements. +- Execute rollback, destructive commands, data migrations, or irreversible cleanup. +``` + +- [ ] **Step 3: Keep existing checklist content intact** + +Do not remove the existing `## The Pre-Launch Checklist` section or its subsections. Only add the new policy before it. + +- [ ] **Step 4: Verify policy presence** + +Run: `grep -n "Automation Policy\|AUTO-COMPLETED\|NEEDS_APPROVAL\|BLOCKED\|READY_FOR_SHIP_REVIEW\|must ask" plugins/me/skills/shipping-and-launch/SKILL.md` +Expected: The new section and all decision labels are present. + +### Task 2: Add execution workflow and `/ship` handoff + +**Files:** + +- Modify: `plugins/me/skills/shipping-and-launch/SKILL.md` + +- [ ] **Step 1: Insert execution workflow after Automation Policy** + +Add a new `## Execution Workflow` section after `## Automation Policy`. + +The workflow must contain these steps: + +```markdown +1. Identify the launch type, changed files, blast radius, and whether production systems are affected. +2. Run safe automatic checks first: local verification, CI/PR status reads, dependency/security audits when available, and documentation checks. +3. Draft the launch artifacts that can be prepared locally: rollout stages, rollback triggers and procedure, monitoring targets, owners, and post-launch checks. +4. Categorize every item into `AUTO-COMPLETED`, `NEEDS_APPROVAL`, `BLOCKED`, or `READY_FOR_SHIP_REVIEW`. +5. Stop on `BLOCKED` items and report the exact evidence. +6. Ask before any `NEEDS_APPROVAL` action. +7. When preparation is complete and the change is production-bound, hand off to `/ship` for the final GO/NO-GO decision. +``` + +- [ ] **Step 2: Add decision category definitions** + +Add a `## Decision Categories` section after the execution workflow. + +Use these definitions: + +```markdown +- `AUTO-COMPLETED`: Safe checks or drafts the agent completed locally with evidence. +- `NEEDS_APPROVAL`: Risky, externally visible, shared-state, or hard-to-reverse actions that require user approval. +- `BLOCKED`: A launch blocker such as failing tests, missing rollback path, unknown owner, missing monitoring, unresolved security risk, or unverifiable production impact. +- `READY_FOR_SHIP_REVIEW`: Launch preparation is complete enough for `/ship` to run specialist review and produce GO/NO-GO. +``` + +- [ ] **Step 3: Add relationship to `/ship`** + +Add a short `## Relationship to /ship` section after decision categories. + +The section must say: + +```markdown +Use `shipping-and-launch` to prepare launch artifacts and perform safe automatic checks. Use `/ship` when the question is whether the current change is ready to go live. `/ship` performs the specialist fan-out review and final GO/NO-GO synthesis; this skill prepares the evidence that `/ship` consumes. +``` + +- [ ] **Step 4: Verify workflow and handoff presence** + +Run: `grep -n "Execution Workflow\|Decision Categories\|Relationship to /ship\|READY_FOR_SHIP_REVIEW\|GO/NO-GO" plugins/me/skills/shipping-and-launch/SKILL.md` +Expected: The workflow, category definitions, and `/ship` relationship are present. + +### Task 3: Validate formatting and repository checks + +**Files:** + +- Modify: `plugins/me/skills/shipping-and-launch/SKILL.md` + +- [ ] **Step 1: Run markdownlint for the changed skill and plan** + +Run: `pre-commit run markdownlint --files plugins/me/skills/shipping-and-launch/SKILL.md docs/superpowers/plans/2026-05-13-shipping-launch-safe-automation.md` +Expected: PASS. If it fails for line length or blank-line formatting, fix only formatting in those files and rerun. + +- [ ] **Step 2: Run project tests** + +Run: `bats tests/` +Expected: PASS. If BATS is unavailable or tests fail, report the exact failure and do not claim full verification. + +- [ ] **Step 3: Check diff scope** + +Run: `git diff -- plugins/me/skills/shipping-and-launch/SKILL.md docs/superpowers/plans/2026-05-13-shipping-launch-safe-automation.md` +Expected: Diff only contains the shipping-and-launch safe automation policy/workflow and this implementation plan. + +## Self-Review + +- Spec coverage: The plan covers safe automation, approval gates, execution workflow, decision categories, + `/ship` handoff, existing content preservation, and verification. +- Placeholder scan: No TBD/TODO/later placeholders remain. +- Type consistency: This plan edits Markdown only; all decision category names are consistent across tasks. diff --git a/plugins/me/skills/shipping-and-launch/SKILL.md b/plugins/me/skills/shipping-and-launch/SKILL.md index 870323c3..9cceab59 100644 --- a/plugins/me/skills/shipping-and-launch/SKILL.md +++ b/plugins/me/skills/shipping-and-launch/SKILL.md @@ -7,7 +7,58 @@ description: Prepares production launches. Use when preparing to deploy to produ ## Overview -Ship with confidence. The goal is not just to deploy — it's to deploy safely, with monitoring in place, a rollback plan ready, and a clear understanding of what success looks like. Every launch should be reversible, observable, and incremental. +Ship with confidence. The goal is not just to deploy — it's to deploy safely, with monitoring in place, +a rollback plan ready, and a clear understanding of what success looks like. Every launch should be +reversible, observable, and incremental. + +## Automation Policy + +Act first on safe read-only checks and local reversible work. Automatically inspect git status, diffs, +recent commits, changed files, PR status, and CI status before asking the user for context when those +checks can answer the question. + +Automatically run local verification when appropriate, including tests, lint, type checks, builds, +audits, and focused smoke checks. Automatically draft rollout plans, rollback plans, monitoring +checklists, post-launch verification checklists, and release notes for user review. + +Automatically identify missing owners, dashboards, feature flags, environment variables, documentation, +and runbooks. Classify findings as `AUTO-COMPLETED`, `NEEDS_APPROVAL`, `BLOCKED`, or +`READY_FOR_SHIP_REVIEW` so the user can quickly see what is done, what needs a decision, what is +blocked, and what is ready for final ship review. + +You must ask for approval before any operation that changes shared or external state: push, PR creation, +merge, release tagging, package publishing, staging or production deploys, release workflows, +infrastructure changes, feature flag changes, production config changes, secrets, environment variables, +DNS, SSL, databases, external notifications, Slack messages, GitHub comments, status page updates, +customer announcements, rollbacks, destructive commands, data migrations, or irreversible cleanup. + +## Execution Workflow + +1. Identify the launch type, changed files, blast radius, and whether production systems are affected. +2. Run safe automatic checks first: local verification, CI/PR status reads, dependency/security audits when + available, and documentation checks. +3. Draft launch artifacts that can be prepared locally: rollout stages, rollback triggers/procedure, + monitoring targets, owners, and post-launch checks. +4. Classify every item as `AUTO-COMPLETED`, `NEEDS_APPROVAL`, `BLOCKED`, or `READY_FOR_SHIP_REVIEW`. +5. If any `BLOCKED` items exist, stop and report the exact evidence. +6. Ask the user before taking any `NEEDS_APPROVAL` action. +7. When preparation is complete and the change is production-bound, hand off to `/ship` for the final GO/NO-GO decision. + +## Decision Categories + +- `AUTO-COMPLETED`: Safe checks or drafts completed locally with evidence. +- `NEEDS_APPROVAL`: Risky, externally visible, shared-state, or hard-to-reverse actions that require user + approval. +- `BLOCKED`: Launch blocker such as failing tests, missing rollback path, unknown owner, missing + monitoring, unresolved security risk, or unverifiable production impact. +- `READY_FOR_SHIP_REVIEW`: Launch preparation is complete enough for `/ship` to run specialist review and + produce GO/NO-GO. + +## Relationship to /ship + +`shipping-and-launch` prepares launch artifacts and performs safe automatic checks. Use `/ship` when +deciding whether the current change can go live. `/ship` performs specialist fan-out review and final +GO/NO-GO synthesis. This skill prepares the evidence that `/ship` consumes. ## When to Use @@ -93,7 +144,7 @@ return null; **Feature flag lifecycle:** -``` +```text 1. DEPLOY with flag OFF → Code is in production but inactive 2. ENABLE for team/beta → Internal testing in production environment 3. GRADUAL ROLLOUT → 5% → 25% → 50% → 100% of users @@ -102,6 +153,7 @@ return null; ``` **Rules:** + - Every feature flag has an owner and an expiration date - Clean up flags within 2 weeks of full rollout - Don't nest feature flags (creates exponential combinations) @@ -111,7 +163,7 @@ return null; ### The Rollout Sequence -``` +```text 1. DEPLOY to staging └── Full test suite in staging environment └── Manual smoke test of critical flows @@ -153,6 +205,7 @@ Use these thresholds to decide whether to advance, hold, or roll back at each st ### When to Roll Back Roll back immediately if: + - Error rate increases by more than 2x baseline - P95 latency increases by more than 50% - User-reported issues spike @@ -163,7 +216,7 @@ Roll back immediately if: ### What to Monitor -``` +```text Application metrics: ├── Error rate (total and by endpoint) ├── Response time (p50, p95, p99) @@ -226,7 +279,7 @@ app.use((err: Error, req: Request, res: Response, next: NextFunction) => { In the first hour after launch: -``` +```text 1. Check health endpoint returns 200 2. Check error monitoring dashboard (no new error types) 3. Check latency dashboard (no regression) @@ -263,6 +316,7 @@ Every deployment needs a rollback plan before it happens: - Redeploy previous version: < 5 minutes - Database rollback: < 15 minutes ``` + ## See Also - For security pre-launch checks, see `references/security-checklist.md`