diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index ea709d0..b13570b 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -597,7 +597,7 @@ "./platform-engineering" ], "strict": false, - "description": "Infrastructure as code, CI/CD, container orchestration, service networking — methodology and reference patterns for building and operating internal developer platforms." + "description": "Use this skill when building or operating internal developer platforms: infrastructure as code, CI/CD, container orchestration, service networking, secrets, and observability. Do not use it to define release process, promotion, rollout, or rollback policy; use release-engineering for that delivery model." }, { "name": "product-design-and-ux", diff --git a/agent-evals-and-observability/SKILL.md b/agent-evals-and-observability/SKILL.md index aa633d5..8f17c39 100644 --- a/agent-evals-and-observability/SKILL.md +++ b/agent-evals-and-observability/SKILL.md @@ -24,7 +24,7 @@ Evaluation asks whether behavior meets a defined criterion on a declared dataset 3. Select complementary graders that observe the claimed property. Use deterministic checks for observable mechanics; use execution/environment checks for state and side effects; use human, model-judge, pairwise/ranking, domain, and safety review where appropriate. 4. Run the candidate and baseline under comparable conditions. Preserve run configuration, stochastic repeats where variability affects the decision, failures/timeouts, and trajectory evidence. 5. Report a multidimensional profile and uncertainty. Use paired comparisons where possible; inspect slices, missingness, base rates, confounders, effect sizes, and multiple comparisons. Non-significance is not equivalence. -6. Apply a risk-tiered release gate: hard safety, privacy, authorization, and side-effect invariants cannot be averaged away. Record authority, insufficient-evidence outcomes, rollback, and follow-up. +6. Apply a risk-tiered release gate: hard safety, privacy, authorization, and side-effect invariants cannot be averaged away. Record authority, insufficient-evidence outcomes, rollback, and follow-up. Load [release-engineering](../release-engineering/SKILL.md) when this evidence must be incorporated into artifact promotion, deployment, rollback, or a broader release train. 7. Instrument production with minimized, redacted telemetry. Feed verified incidents and near misses into cases after consent, transformation, and contamination review. Stop when the supported decision, evidence gaps, residual risks, and responsible owner are recorded. Escalate rather than infer a pass when required evidence is unavailable or conflicts. diff --git a/api-design-and-evolution/SKILL.md b/api-design-and-evolution/SKILL.md index 95052d3..0e3a9fe 100644 --- a/api-design-and-evolution/SKILL.md +++ b/api-design-and-evolution/SKILL.md @@ -19,12 +19,14 @@ Start with the consumer job, domain meaning, authority boundary, and failure mod then choose the interface style and contract format. Keep facts, assumptions, and policy decisions distinguishable. -## When To Use +## When to use Use for a new or changed REST/HTTP API, GraphQL schema, RPC operation, event or message contract, webhook, or streaming interface. Use it before implementation and again whenever consumer-visible behavior changes. +## When not to use + Do not use this as an ADR template, a complete product-discovery method, a security assessment, or an implementation test plan. Hand those concerns to [adr-authoring](../adr-authoring/SKILL.md), @@ -67,7 +69,10 @@ assessment, or an implementation test plan. Hand those concerns to and [references/evolution-and-deprecation.md](references/evolution-and-deprecation.md). Review the contract using [templates/contract-review.md](templates/contract-review.md). Test provider conformance, consumer expectations, compatibility diffs, examples, - negative cases, and the deployed boundary. + negative cases, and the deployed boundary. Load + [release-engineering](../release-engineering/SKILL.md) for release sequencing, + artifact promotion, progressive exposure, and coordinated rollback after the + compatibility policy is defined. ## Reference Guide diff --git a/bundles/neckbeard/SKILL.md b/bundles/neckbeard/SKILL.md index 8fac59d..6b7275f 100644 --- a/bundles/neckbeard/SKILL.md +++ b/bundles/neckbeard/SKILL.md @@ -32,6 +32,8 @@ Load neckbeard when a request is a non-trivial software change — a bug to diagnose, a feature to build, a refactor, a review, a release to verify — and you need a bounded, stage-aware way to carry it to a defensible "done." +## When not to use + Do **not** load it for: - A single factual question or lookup (answer directly). - A one-line edit whose contract is already fully specified (just do it, but @@ -124,7 +126,8 @@ When a stage has a specialist skill, load it and follow it. The full table with | Test strategy, regression testing, CI quality gates | `qa-methodology` | | Docs / README / API reference | `technical-documentation` | | Verification verdicts and evidence | `verification-methodology` | -| Reliability, incident response, operational recovery, delivery | `site-reliability-engineering` | +| Release planning, versioning, pipeline promotion, readiness, rollout, or rollback design | `release-engineering` | +| Reliability, incident response, or operational recovery | `site-reliability-engineering` | If a specialist skill is not installed, neckbeard's stage references provide a minimal fallback method — but note in the ledger that the specialist was absent. diff --git a/bundles/neckbeard/references/routing-table.md b/bundles/neckbeard/references/routing-table.md index 0e4d473..987f464 100644 --- a/bundles/neckbeard/references/routing-table.md +++ b/bundles/neckbeard/references/routing-table.md @@ -25,7 +25,8 @@ ledger around it. | Test strategy, regression testing, or CI quality gates | `qa-methodology` | Ledger, boundary verification | | Writing or reviewing docs, README, API reference | `technical-documentation` | Ledger | | Producing a pass/conditional/blocked verdict with evidence | `verification-methodology` | Ledger boundary rules | -| Reliability objectives, incident response, operational recovery, or delivery | `site-reliability-engineering` | Contract, ledger, rollback evidence | +| Release planning, versioning, pipeline promotion, readiness, rollout, or rollback design | `release-engineering` | Contract, ledger, rollback evidence | +| Reliability objectives, incident response, or operational recovery | `site-reliability-engineering` | Contract, ledger, rollback evidence | | Architecture decision records | `adr-authoring` | Decision-record template, ledger | | Code review, refactoring, or implementation quality assessment against classic engineering principles | `programming-principles` | Contract, ledger, boundary verification | diff --git a/llms.txt b/llms.txt index 005e31b..55e2740 100644 --- a/llms.txt +++ b/llms.txt @@ -67,7 +67,7 @@ - [org-design](org-design/SKILL.md): CHRO methodology — organizational design (team topologies, span of control, reporting structures), talent strategy (make-vs-buy, skill taxonomies, succession planning), compensation frameworks (market benchmarking, equity design, leveling), culture architecture (values codification, rituals, psychological safety), organizational health metrics (eNPS, retention risk, engagement surveys), DEI strategy (inclusive design, equitable systems, belonging). - [pace-plan](pace-plan/SKILL.md): Build, coordinate, operate, troubleshoot, exercise, and improve an authorized Primary, Alternate, Contingency, and Emergency communications plan. Use for resilient emergency-communications paths and their ownership, triggers, check-ins, tests, and corrective actions. Do not use for generic incident status messaging, frequency or channel planning, radio programming, or unauthorized transmission and activation. - [peertube](peertube/SKILL.md): Browse PeerTube federated video from the terminal: view videos and channels, search across instances, check server stats, and manage your account. Uses OAuth2 authentication with token persistence. Use when the user mentions PeerTube, federated video, decentralized video platforms, or browsing/uploading to a PeerTube instance. -- [platform-engineering](platform-engineering/SKILL.md): Infrastructure as code, CI/CD, container orchestration, service networking — methodology and reference patterns for building and operating internal developer platforms. +- [platform-engineering](platform-engineering/SKILL.md): Use this skill when building or operating internal developer platforms: infrastructure as code, CI/CD, container orchestration, service networking, secrets, and observability. Do not use it to define release process, promotion, rollout, or rollback policy; use release-engineering for that delivery model. - [product-design-and-ux](product-design-and-ux/SKILL.md): Define user-facing product behavior from validated evidence and approved scope. Use for information architecture, task flows, state and recovery models, interface contracts, usability-study plans, interaction-pattern tradeoffs, or engineering UX handoffs. Use after product discovery and product decisions; route WCAG/ARIA conformance work to web-accessibility and formal software specifications to spec-driven-development. - [product-discovery](product-discovery/SKILL.md): Discover product requirements from human stakeholders — map who to talk to, ask questions that surface hidden assumptions, detect gaps in real time, resolve conflicts, and translate conversations into structured SDD specs. Phase 0 upstream of Spec-Driven Development. - [product-methodology](product-methodology/SKILL.md): Product management frameworks for translating validated evidence into prioritized backlogs, decisions, specifications, and stakeholder communications. Covers RICE, MoSCoW, opportunity solution trees, decision logs, spec drafting, and audience-specific stakeholder communication. diff --git a/platform-engineering/SKILL.md b/platform-engineering/SKILL.md index 5690cae..53d5908 100644 --- a/platform-engineering/SKILL.md +++ b/platform-engineering/SKILL.md @@ -1,8 +1,10 @@ --- name: platform-engineering -description: Infrastructure as code, CI/CD, container orchestration, service networking - — methodology and reference patterns for building and operating internal developer - platforms. +description: >- + Use this skill when building or operating internal developer platforms: infrastructure + as code, CI/CD, container orchestration, service networking, secrets, and + observability. Do not use it to define release process, promotion, rollout, or + rollback policy; use release-engineering for that delivery model. license: MIT metadata: tags: '' @@ -26,7 +28,11 @@ Load this skill when the task involves: | Observability strategy | Prometheus rules, Grafana dashboards-as-code, Loki logging, tracing | | Secret management design | Vault, SOPS, External Secrets Operator patterns | | Cloud architecture assessment | Multi-cloud patterns, provider foundations, cost governance | -| Deployment pipeline review | End-to-end delivery pipeline audit, release engineering patterns | +| Deployment pipeline review | Delivery-platform architecture; load [release-engineering](../release-engineering/SKILL.md) when defining the release model, promotion gates, rollout, or rollback policy | + +## When not to use + +Use [release-engineering](../release-engineering/SKILL.md) to define release process, promotion, rollout, or rollback policy. This skill builds and operates the delivery platform that implements those decisions. ## Loading Order @@ -85,4 +91,5 @@ The profile using this skill produces artifact pyramids. The response to any cal - `tailscale` — mesh networking and ACL policies - `implementation-planning` — work breakdown and dependency ordering - `mermaid-diagrams` — architecture diagram generation -- `site-reliability-engineering` — sister domain (post-deployment reliability) +- `site-reliability-engineering` — sister domain for post-deployment reliability +- `release-engineering` — release process, artifact promotion, readiness, rollout, and rollback policy; this skill owns the delivery platform that implements those decisions diff --git a/qa-methodology/SKILL.md b/qa-methodology/SKILL.md index 95e09cc..3488482 100644 --- a/qa-methodology/SKILL.md +++ b/qa-methodology/SKILL.md @@ -116,6 +116,7 @@ Route to the named sibling skill instead: - [spec-driven-development](../spec-driven-development/SKILL.md) — writing specs, running the SDD pipeline, gate verdict format, revision loops - [agent-evals-and-observability](../agent-evals-and-observability/SKILL.md) — eval framework governance, statistical comparisons, telemetry and privacy controls, grader implementation - [verification-methodology](../verification-methodology/SKILL.md) — collecting evidence and rendering verdicts against explicit pass/fail criteria +- [release-engineering](../release-engineering/SKILL.md) — composing test evidence into release-candidate readiness, promotion, go/no-go, production rollout, and rollback decisions; QA owns test strategy and gate semantics - [systematic-debugging](../systematic-debugging/SKILL.md) — root-cause analysis of production incidents, bug reproduction, fault localization - [secure-software-engineering](../secure-software-engineering/SKILL.md) — security implementation, threat modeling, secure defaults, dependency evaluation diff --git a/release-engineering/SKILL.md b/release-engineering/SKILL.md index 2e1ad2e..73c8227 100644 --- a/release-engineering/SKILL.md +++ b/release-engineering/SKILL.md @@ -98,6 +98,11 @@ Senior-to-principal release engineering methodology: designing and operating the | `scripts/release_plan_scaffold.py` | Scaffolding a release plan document from flags or a git range | | `evals/evals.json` | Running output-quality evals for this skill (schema v1, 8 cases) | +## Adjacent Skills + +- Use [qa-methodology](../qa-methodology/SKILL.md) to define test strategy, regression scope, flake policy, and quality-gate semantics. This skill combines the resulting evidence with operational and governance evidence for a release decision. +- For AI-agent releases, use [agent-evals-and-observability](../agent-evals-and-observability/SKILL.md) to design and interpret behavioral, trajectory, and model-regression evidence before incorporating it into a release gate. + ## Scripts | Script | Invocation | Purpose | diff --git a/secure-software-engineering/SKILL.md b/secure-software-engineering/SKILL.md index ebe8b56..69db531 100644 --- a/secure-software-engineering/SKILL.md +++ b/secure-software-engineering/SKILL.md @@ -43,7 +43,7 @@ Loop to the affected phase when evidence contradicts an assumption or a design c | Designing logs, audit events, monitoring, or forensic evidence | [references/secure-logging-audit.md](references/secure-logging-audit.md) | | Sharing infrastructure or data across tenants | [references/multi-tenant-isolation.md](references/multi-tenant-isolation.md) | | Reviewing a change or defining a security review gate | [references/secure-code-review.md](references/secure-code-review.md) | -| Preparing artifacts, exceptions, rollback, or response for release | [references/release-evidence.md](references/release-evidence.md) | +| Preparing artifacts, exceptions, rollback, or response for release | [references/release-evidence.md](references/release-evidence.md); load [release-engineering](../release-engineering/SKILL.md) to carry those controls and evidence through build, registry, promotion, and deployment gates | | Learning from an incident, near miss, or escaped defect | [references/incident-learning.md](references/incident-learning.md) | | Designing an LLM, RAG pipeline, model integration, or agent tool | [references/ai-llm-security.md](references/ai-llm-security.md) | diff --git a/site-reliability-engineering/SKILL.md b/site-reliability-engineering/SKILL.md index 60a19f6..6269b02 100644 --- a/site-reliability-engineering/SKILL.md +++ b/site-reliability-engineering/SKILL.md @@ -24,7 +24,9 @@ A comprehensive methodology for designing, operating, and improving reliable pro | "Do a reliability review" | Architecture review against SRE principles, risk assessment | | "I need an incident commander" | Incident command framework, role cards, communication templates | | "Automate this operational task" | Toil assessment, automation decision tree, runbook pattern | +## When not to use +Use [release-engineering](../release-engineering/SKILL.md) to plan releases, compose promotion and rollback gates, or coordinate a release train. Use [systematic-debugging](../systematic-debugging/SKILL.md) to find the cause of a specific failure. ## Reference Files @@ -38,7 +40,7 @@ A comprehensive methodology for designing, operating, and improving reliable pro | Monitoring & Alerting | `references/monitoring-alerting.md` | Observability design, alert rules | | On-Call Best Practices | `references/oncall-best-practices.md` | Rotation design, team sizing | | Toil Elimination | `references/toil-elimination.md` | Automation prioritization, ops review | -| Release Engineering | `references/release-engineering.md` | Deployment pipeline design | +| Release Engineering | [release-engineering](../release-engineering/SKILL.md) | Release planning, promotion, progressive delivery, and rollback design; use the local reference only for SRE-specific integration context | | Effective Troubleshooting | `references/troubleshooting.md` | Debugging methodology | | Senior SRE Role Blueprint | `references/senior-sre-blueprint.md` | Role definition, KPI framework | | SRE Communication Guide | `references/sre-communication-guide.md` | Stakeholder updates, incident communication |