diff --git a/plugins/me/skills/ship/SKILL.md b/plugins/me/skills/ship/SKILL.md index 155870c2..361db91b 100644 --- a/plugins/me/skills/ship/SKILL.md +++ b/plugins/me/skills/ship/SKILL.md @@ -1,173 +1,107 @@ --- name: ship -description: Use when the user asks to "ship", "launch", "release", "deploy", "출시", "런치", "배포", or wants help running a production launch — pre-launch checks, staged rollout, monitoring, rollback. Curates launch tasks based on change risk and walks through them one task at a time. +description: Use when asked to "ship", "launch", "release", or "is this ready to go live?". Reviews the current change as a shipping candidate and reports readiness without executing deploy commands. allowed-tools: - Bash - Read - Glob - Grep - - TaskCreate - - TaskUpdate - - TaskList --- -# /ship: Launch Task Runner +# /ship: Review shipping readiness -`/ship` is a stepwise launch helper. It curates launch tasks for the current change and walks through them one task at a time with the user. +You are a shipping readiness reviewer. `/ship` is a launch gate, not a deploy executor. -`/ship` does NOT: -- run deploy commands -- merge PRs or push to remote -- replace `/qa` or `/e2e` (it consumes their evidence) -- bypass the gate when evidence is missing +## What `/ship` does -## The phases +- Reviews the current change as a shipping candidate +- Identifies blockers and warnings +- Assesses rollout, rollback, and monitoring readiness +- Produces a short readiness report with next actions -Always run these in order. Do not skip phases. Do not collapse phases. +## What `/ship` does NOT do -``` -SCOPE → GATE → CLASSIFY → PLAN → EXECUTE → WRAP -``` +- Do not invent or run deploy commands +- Do not replace `/qa` +- Do not create or merge PRs +- Do not take ownership of versioning or release automation -### 1. SCOPE +## Relationship to `/qa` and `/e2e` -Gather evidence about the current change. Read, do not assume: +- `/qa` provides default behavior verification +- `/e2e` provides cross-boundary flow verification when needed +- `/ship` consumes that verification evidence and judges release readiness -- `git status` and `git diff main...HEAD` (or current base branch) -- recent `/qa` or `/e2e` evidence in the conversation or repo -- the user's one-line description of the change +`/ship` does not re-verify feature behavior that belongs to `/qa` or `/e2e`. -If you cannot read the diff, say so and stop. Do not proceed on user testimony alone. This rule is not waived by user permission, simulation/test context, "trust me it's small", or time pressure. The way to unblock is to provide diff text or fix tool access — not to skip SCOPE. +## Candidate under review -### 2. GATE +Default to the current working change. -Block the launch if any of these are true. Do not proceed to CLASSIFY: +Use whatever evidence is available in the repository to understand scope: +- current branch state +- `main...HEAD` diff when available +- recent `/qa` or `/e2e` verification evidence -- no test or verification evidence at all -- the change touches money, auth, or data integrity AND has no `/qa` evidence -- rollback path is completely unknown AND the change is not trivially revertible -- the user is invoking `/ship` under sunk-cost or deadline pressure on a risky change +If the scope is unclear, say so and downgrade the decision. -Sunk cost ("90% done"), deadline ("30 min left"), and authority ("the lead said to merge it") are NOT readiness signals. State this directly when refusing. +## Required review areas -If gated, report: -- one sentence on why -- the smallest set of evidence needed to unblock -- stop. Do not create tasks. +Review the change across these areas: -### 3. CLASSIFY +1. **Pre-launch** — Is the scope clear? Is there test or verification evidence? Is required review or operator context present? +2. **Rollout** — Could this be introduced safely? Is there a feature flag, kill switch, or another way to limit blast radius when appropriate? +3. **Rollback** — Could the team explain how to recover if the launch goes badly? +4. **Monitoring** — Are there logs, metrics, alerts, or explicit watchpoints that would reveal success or failure? -Assign exactly one risk class to the change. Read `references/curation-rules.md` for criteria. +For concrete examples and decision patterns, read `ship/references/ship-checklist.md`. -- **low** — docs, internal tools off by default, additive UI to <10 internal users -- **standard** — user-facing feature, API change, observable behavior change -- **risky** — payment/auth/data migration/permissions/billing, broad user impact, irreversible +## Decision rules -State the class explicitly, in one word, with one sentence of evidence: "Class: standard — adds a new public endpoint exposed to all users." +Choose one outcome: -If unclear between two classes, pick the higher one. +- **Ready** — No blockers found. Basic rollout, rollback, and monitoring expectations are covered. +- **Conditionally ready** — Not blocked, but the launch needs explicit follow-up before or during release. +- **Not ready** — A critical gate is missing. -### 4. PLAN +Default to **Not ready** when core evidence is missing. -Build the task list from `references/curation-rules.md` based on the class. Each class has a default task set. Add change-specific tasks if the diff reveals them (DB migration, new env var, new dependency). +## Output format -Present the task list to the user as a numbered preview — task **titles only**, plus the playbook section reference where details live. Do NOT inline the playbook content (rollout thresholds, checklist items, rollback templates) at PLAN time. Long expanded previews invite "looks fine, just go" rubber-stamping. Keep the preview scannable. Ask: "Proceed with these N tasks? You can add, remove, or reorder." +Always report using these sections: -Do NOT call TaskCreate yet. Wait for explicit user approval. +### Decision -**Handling task removal requests in PLAN edit:** +Ready / Conditionally ready / Not ready -The user may push back on the task list ("skip canary, drop 1-week watch"). Do not bulk-accept and do not bulk-refuse. Triage per item: +### Blocking issues -1. Does removing this task effectively *downgrade the class* (e.g., risky → standard by deleting feature flag + canary)? If yes, refuse — they should re-classify, not edit. -2. Can the *purpose* be preserved by a different mechanism (e.g., small population → "team window 72h" instead of "5% canary")? If yes, propose the variant. -3. Is the task purely tracking metadata (e.g., "feature flag cleanup task") that can be absorbed into another task without losing the underlying rule (owner + expiration date)? If yes, absorb and confirm. -4. Is the user's argument empirical (e.g., "5% of 50/day = 2.5 users, statistically meaningless")? Engage with the argument, do not refuse mechanically. The goal is the underlying intent (blast-radius limiting, observability, reversibility), not the literal task wording. +List only items that must be resolved before shipping. -State the per-item decision explicitly when responding. +### Warnings -### 5. EXECUTE +List risks that do not fully block launch. -After approval, call TaskCreate once with all tasks set to `pending`. +### Readiness by area -Then loop: -1. Pick the first `pending` task. Set it to `in_progress` via TaskUpdate. -2. Show the task content and what evidence/action satisfies it. -3. Wait for the user to confirm done OR provide evidence OR say "skip with reason". -4. Mark `completed` (or `cancelled` with reason). Move to next. -5. If the user reports a blocker, stop the loop and report. Do not auto-mark remaining tasks. +- Pre-launch: pass / weak / fail +- Rollout: pass / weak / fail +- Rollback: pass / weak / fail +- Monitoring: pass / weak / fail -Only one task is `in_progress` at a time. Even when the user batch-confirms ("tasks 1, 2, 3 done"), call TaskUpdate per task, not all at once. The pacing IS the discipline. +### Next actions -**Handling phase backtrack (mid-EXECUTE scope discovery):** +Give the smallest set of actions needed to improve readiness. -If the user reveals new scope mid-EXECUTE ("oh wait, there's also a migration"), SCOPE evidence is now stale. Do not silently amend. Triage: +## Red flags -1. Pause the current `in_progress` task. Do not mark it completed or cancelled yet. -2. Re-classify if the new scope changes the class (e.g., schema migration entering the picture). -3. Per completed task, decide: *falsified* (claim is now false — e.g., "scope confirmation" against an incomplete diff) or *narrow-but-true* (claim still holds for what was checked, just incomplete coverage). Reopen falsified ones; augment narrow ones with follow-up tasks. -4. Add change-specific tasks for the newly discovered scope. -5. Resume EXECUTE only after the user confirms the reset shape. +Do not mark a change as Ready if any of these are true: -Do not full-reset by default. Surgical reopen + augment is correct when most prior work is still factually true. +- there is no test or verification evidence +- rollback is unknown +- monitoring signals are unknown +- required QA or review clearly has not happened -### 6. WRAP +## Verification expectations -When all tasks are `completed` or explicitly resolved: - -- short summary: what class, how many tasks, what was skipped and why -- watch window: when to check monitoring (e.g., "first hour after deploy") -- feature flag cleanup date if any flag was introduced - -## What to do at each task - -`launch-playbook.md` is the source of task content (pre-launch checks, feature flag steps, staged rollout thresholds, monitoring, rollback templates). When executing a task, point the user to the relevant section. Do not paraphrase the playbook inline. - -## Boundaries with `/qa` and `/e2e` - -- `/qa` and `/e2e` produce verification evidence -- `/ship` consumes that evidence at GATE and SCOPE -- `/ship` does NOT re-run feature behavior tests - -If a task requires QA evidence and none exists, the task is blocked. Tell the user to run `/qa` and return. - -## Output discipline - -- Do not produce a single-shot readiness report. The output IS the phased walk-through. -- Do not pre-fill task completion. The user confirms each task. -- Do not summarize `launch-playbook.md` inline at PLAN time. Show task titles, link to the playbook section. - -## Red flags — stop and reset - -- Generating tasks before SCOPE evidence -- Calling TaskCreate before user approval at PLAN -- Multiple tasks `in_progress` simultaneously -- Marking tasks `completed` without user confirmation -- Filling all 4 readiness areas (pre-launch/rollout/rollback/monitoring) for a low-risk change -- Reporting `Conditionally ready` when the actual answer is `Ready` (safety bias) -- Any output resembling the old single-shot `Decision/Blocking/Warnings/Readiness/Next actions` format - -If any of these occur, stop. Restart from the phase where the rule was broken. - -## References - -| File | When to read | -|---|---| -| `references/curation-rules.md` | At CLASSIFY and PLAN — risk class criteria and default task sets | -| `references/launch-playbook.md` | At EXECUTE — full procedure content for each task (checklist items, rollout thresholds, rollback template) | - -## Common rationalizations - -| Excuse | Reality | -|---|---| -| "Change is small, no need for tasks" | Even low class has 3-5 tasks. Lightness comes from classification, not from skipping the format. | -| "Asking for approval breaks the flow" | Tasks created without approval get rejected. A 5-second review reduces friction. | -| "Already done it all, mark them all completed at once" | Bulk completion = single-shot regression. One-task-at-a-time confirmation IS the skill. | -| "Payment change but I'm out of time — just this once" | Sunk cost is not a readiness input. GATE blocks. | -| "Let me just inline the playbook content" | Playbook is the source. No inline summary. Link/reference only. | -| "Tools unavailable, judge from user testimony" | SCOPE requires tool calls. If unavailable, stop. | -| "Simulation/test context, so SCOPE bypass is fine" | Same rule. Simulation is not a SCOPE exemption. Stop. | -| "Detailed PLAN preview is more helpful" | Detailed previews get rubber-stamped with "all good". Titles + section links only. | -| "User just confirmed 1, 2, 3 — let me batch-update" | Pacing IS the discipline. One TaskUpdate per task, even on batch confirms. | -| "User wants to skip canary entirely — they have a point" | Engage with the empirical argument, but preserve the *purpose*. Propose a variant (team window, absolute-N canary), don't drop the goal. | -| "Scope changed mid-flight, easier to start over" | Falsified vs narrow-but-true. Reopen the falsified, augment the narrow. Don't throw out true work. | +Ground every judgment in repository evidence. If you cannot verify a claim, say that directly and lower the readiness decision. diff --git a/plugins/me/skills/ship/references/curation-rules.md b/plugins/me/skills/ship/references/curation-rules.md deleted file mode 100644 index de682644..00000000 --- a/plugins/me/skills/ship/references/curation-rules.md +++ /dev/null @@ -1,109 +0,0 @@ -# Curation Rules - -Risk classification and default task sets for `/ship`. Used at CLASSIFY and PLAN phases. - -## Classes - -### low - -Criteria — ALL must hold: -- no user-facing runtime behavior change OR change limited to <10 internal users -- no money, auth, permissions, or data integrity touched -- trivially revertible (single commit `git revert`) -- no DB migration, no schema change, no new external dependency - -Examples: -- README/docs typo, comment fixes -- internal admin UI additive elements (filter dropdown, column toggle) -- dev tool changes that don't affect production -- test-only changes - -### standard - -Default class when not clearly low or risky. Criteria — any one is enough: -- user-facing feature or copy change -- public API surface change (new endpoint, new field, behavior change) -- new external dependency -- observable performance characteristic change - -Examples: -- new feature for end users -- new public REST/GraphQL endpoint -- changing default values, copy, or layout for users -- adding a third-party SDK - -### risky - -Criteria — any one triggers risky: -- payment, billing, or money flow -- authentication, authorization, session, permissions -- data migration, schema change, irreversible writes -- broad blast radius (>50% of users, core flow) -- security-sensitive change -- deadline pressure on a non-trivial change - -Examples: -- adding fields to checkout -- changing how sessions are stored -- migrating users to a new table -- modifying rate limiting on auth endpoints - -If between classes, pick the higher one. "Conditionally" thinking belongs here, not in classification. - -## Default task sets - -Each class has a baseline task set. Add change-specific tasks discovered during SCOPE (DB migration, new env var, etc.). - -### low (3 tasks) - -1. Confirm scope from diff matches user description -2. Confirm a one-line revert path exists (commit hash to revert) -3. Merge — no further launch ceremony required - -### standard (8 tasks) - -1. Confirm scope from diff matches user description -2. `/qa` evidence present and passing for the changed paths -3. Identify rollback path (revert command or feature flag off) -4. Identify one success signal to watch (metric, log, dashboard) -5. Identify one failure signal to watch (error rate, alert) -6. If user-facing: behind a feature flag OR justified why not -7. Deploy to staging and verify smoke flow -8. Deploy to production; monitor watch window for first hour - -### risky (full playbook) - -Use full `launch-playbook.md`. Minimum task set: - -1. Confirm scope from diff matches user description -2. `/qa` evidence present for changed paths AND adjacent critical paths -3. Pre-launch checklist (security, performance, accessibility, infra) — section by section -4. Feature flag in place; OFF by default -5. Rollback plan written: trigger conditions, steps, time-to-rollback -6. Monitoring watchpoints defined: error rate baseline, P95 latency baseline, business metric -7. Deploy to staging; full smoke test -8. Deploy to production with flag OFF; verify health -9. Enable for team only; 24h watch -10. Canary 5% with rollout decision thresholds (advance/hold/rollback) -11. Gradual increase 25% → 50% → 100% with monitoring at each step -12. Watch window 1 week after 100% -13. Feature flag cleanup with owner and date - -## Adding change-specific tasks - -During SCOPE, look for these and add tasks: - -| Found in diff | Add task | -|---|---| -| New `migrations/` file | Verify migration is reversible OR document why not | -| New `process.env.X` reference | Confirm env var set in production | -| New entry in `package.json` dependencies | `npm audit` shows no high/critical | -| New public route/handler | Rate limiting decision | -| Auth/session change | Session invalidation plan | -| Removed code path | Confirm no callers (grep), confirm not in feature flags | - -## When to refuse classification - -If the user has not provided a one-line description AND the diff is empty or unreadable, refuse to classify. Run SCOPE again or stop. - -If the change spans multiple unrelated concerns (e.g., auth fix + UI tweak + new feature), ask the user to split before shipping. Do not classify a mixed change. diff --git a/plugins/me/skills/ship/references/launch-playbook.md b/plugins/me/skills/ship/references/launch-playbook.md deleted file mode 100644 index ec10e640..00000000 --- a/plugins/me/skills/ship/references/launch-playbook.md +++ /dev/null @@ -1,173 +0,0 @@ -# Launch Playbook - -Source content for `/ship` tasks. Read sections at EXECUTE phase. Adapted from [addyosmani/agent-skills](https://github.com/addyosmani/agent-skills) `shipping-and-launch` (MIT). - -Do not summarize this playbook inline in `/ship` output. Point the user to the relevant section by name. - -## Pre-launch checklist - -### Code quality -- All tests pass (unit, integration, e2e) -- Build succeeds with no warnings -- Lint and type checking pass -- Code reviewed and approved -- No TODO comments that should be resolved before launch -- No `console.log` debugging statements in production code -- Error handling covers expected failure modes - -### Security -- No secrets in code or version control -- `npm audit` shows no critical or high vulnerabilities -- Input validation on all user-facing endpoints -- Authentication and authorization checks in place -- Security headers configured (CSP, HSTS, etc.) -- Rate limiting on authentication endpoints -- CORS configured to specific origins (not wildcard) - -### Performance -- Core Web Vitals within "Good" thresholds -- No N+1 queries in critical paths -- Images optimized (compression, responsive sizes, lazy loading) -- Bundle size within budget -- Database queries have appropriate indexes -- Caching configured for static assets and repeated queries - -### Accessibility -- Keyboard navigation works for all interactive elements -- Screen reader can convey page content and structure -- Color contrast meets WCAG 2.1 AA (4.5:1 for text) -- Focus management correct for modals and dynamic content -- Error messages are descriptive and associated with form fields -- No accessibility warnings in axe-core or Lighthouse - -### Infrastructure -- Environment variables set in production -- Database migrations applied (or ready to apply) -- DNS and SSL configured -- CDN configured for static assets -- Logging and error reporting configured -- Health check endpoint exists and responds - -### Documentation -- README updated with any new setup requirements -- API documentation current -- ADRs written for any architectural decisions -- Changelog updated -- User-facing documentation updated (if applicable) - -## Feature flag lifecycle - -``` -1. DEPLOY with flag OFF → Code in production but inactive -2. ENABLE for team/beta → Internal testing in production -3. GRADUAL ROLLOUT → 5% → 25% → 50% → 100% -4. MONITOR at each stage → Error rates, performance, feedback -5. CLEAN UP → Remove flag and dead path after rollout -``` - -Rules: -- Every flag has an owner and an expiration date -- Clean up flags within 2 weeks of full rollout -- Don't nest feature flags -- Test both flag states (on and off) in CI - -## Staged rollout sequence - -``` -1. DEPLOY to staging - └── Full test suite + manual smoke test of critical flows - -2. DEPLOY to production (flag OFF) - └── Health check + verify no new errors - -3. ENABLE for team (flag ON for internal users) - └── 24-hour monitoring window - -4. CANARY (flag ON for 5% of users) - └── 24-48 hour monitoring window - └── Advance only if all thresholds pass - -5. GRADUAL increase (25% → 50% → 100%) - └── Same monitoring at each step - -6. FULL rollout (flag ON for all users) - └── Monitor for 1 week - └── Clean up feature flag -``` - -## Rollout decision thresholds - -| Metric | Advance | Hold and investigate | Roll back | -|---|---|---|---| -| Error rate | Within 10% of baseline | 10–100% above baseline | >2x baseline | -| P95 latency | Within 20% of baseline | 20–50% above baseline | >50% above baseline | -| Client JS errors | No new error types | New errors at <0.1% sessions | New errors at >0.1% sessions | -| Business metrics | Neutral or positive | Decline <5% (may be noise) | Decline >5% | - -## Roll back immediately if - -- Error rate increases by more than 2x baseline -- P95 latency increases by more than 50% -- User-reported issues spike -- Data integrity issues detected -- Security vulnerability discovered - -## What to monitor - -``` -Application: -├── Error rate (total and by endpoint) -├── Response time (p50, p95, p99) -├── Request volume -├── Active users -└── Key business metrics - -Infrastructure: -├── CPU and memory -├── DB connection pool -├── Disk space -├── Network latency -└── Queue depth - -Client: -├── Core Web Vitals (LCP, INP, CLS) -├── JS errors -├── API error rates from client -└── Page load time -``` - -## Post-launch verification (first hour) - -1. Health endpoint returns 200 -2. Error monitoring shows no new error types -3. Latency dashboard shows no regression -4. Critical user flow works end-to-end -5. Logs are flowing and readable -6. Rollback mechanism verified ready - -## Rollback plan template - -```markdown -## Rollback Plan for [Feature/Release] - -### Trigger conditions -- Error rate > 2x baseline -- P95 latency > [X]ms -- User reports of [specific issue] - -### Rollback steps -1. Disable feature flag (if applicable) - OR -1. Deploy previous version: `git revert && git push` -2. Verify rollback: health check, error monitoring -3. Communicate: notify team - -### Database considerations -- Migration [X] has a rollback: `` -- Data inserted by new feature: [preserved / cleaned up] - -### Time to rollback -- Feature flag: < 1 minute -- Redeploy previous version: < 5 minutes -- Database rollback: < 15 minutes -``` diff --git a/plugins/me/skills/ship/references/ship-checklist.md b/plugins/me/skills/ship/references/ship-checklist.md new file mode 100644 index 00000000..0ada618f --- /dev/null +++ b/plugins/me/skills/ship/references/ship-checklist.md @@ -0,0 +1,63 @@ +# Ship Checklist + +Reference material for `/ship`. Read this when you need concrete examples while assessing shipping readiness. This file supports the core skill; it does not change the `/ship` contract. + +## Pre-launch checks + +Use these to decide whether the change is basically ready to leave the branch: + +- The change scope can be described in one or two sentences. +- The relevant tests or verification steps are named and have recent evidence. +- Any required review, approval, or human sign-off is explicit. +- Any launch notes or operator context are written down somewhere discoverable. + +## Rollout readiness + +Use these to assess whether the release can be introduced safely: + +- A staged rollout is possible, or the change is clearly low-risk enough not to need one. +- A feature flag, kill switch, or config gate exists when exposure risk is meaningful. +- The change does not require an all-at-once cutover without justification. + +## Rollback readiness + +Use these to assess whether the team can recover quickly: + +- A rollback path can be explained in plain language. +- Irreversible schema or data changes are identified explicitly. +- The first action to take during a bad launch is known. + +## Monitoring readiness + +Use these to assess whether post-launch behavior is observable: + +- There is at least one success signal to watch. +- There is at least one failure signal to watch. +- The relevant logs, metrics, or alerts are named. +- The launch is not blind; someone could tell within minutes if it went wrong. + +## Blocking issue examples + +These usually mean `/ship` should report **Not ready**: + +- No test or verification evidence is available. +- No rollback path can be described. +- Monitoring signals are completely unknown. +- Required QA or review has clearly not happened. + +## Warning examples + +These usually mean `/ship` should report **Conditionally ready** rather than **Ready**: + +- The change is large and rollout strategy is weak. +- A feature flag would help but is not strictly required. +- Monitoring exists but the exact watchpoints are not written down. +- The launch can proceed, but only with explicit human attention. + +## Suggested decision language + +Use short, direct language: + +- **Ready** — No blockers found. Basic rollout, rollback, and monitoring expectations are covered. +- **Conditionally ready** — No hard blocker, but the ship needs explicit follow-up before or during launch. +- **Not ready** — One or more critical gates are missing; shipping now would be unsafe. diff --git a/tests/me/me-specific.bats b/tests/me/me-specific.bats index c30768c8..cef353a5 100644 --- a/tests/me/me-specific.bats +++ b/tests/me/me-specific.bats @@ -39,8 +39,7 @@ load ../helpers/bats_helper @test "me: ship skill exists with required files" { [ -f "${PROJECT_ROOT}/plugins/me/skills/ship/SKILL.md" ] - [ -f "${PROJECT_ROOT}/plugins/me/skills/ship/references/curation-rules.md" ] - [ -f "${PROJECT_ROOT}/plugins/me/skills/ship/references/launch-playbook.md" ] + [ -f "${PROJECT_ROOT}/plugins/me/skills/ship/references/ship-checklist.md" ] } @test "me: ship skill has proper frontmatter" {