@givolt/i3-composer-agent 0.0.0-stage → 0.6.12

package/rebrand/templates/README.md

@@ -0,0 +1,178 @@
+# i3 Composer Agent
+
+**Intelligence. Integration. Innovation.**
+
+Production-grade engineering skills, lifecycle commands, and specialist personas
+for AI coding agents. This is the engineering-skill product in the i3 Composer
+family; the GSD-derived workflow product is maintained separately.
+
+Based on [Agent Skills](https://github.com/addyosmani/agent-skills) by Addy Osmani
+(MIT). See [NOTICE.md](NOTICE.md) for attribution and the upstream baseline.
+
+## Prepare the complete plugin with npx
+
+The npm package is `@givolt/i3-composer-agent`. The plugin and marketplace ID is
+`i3-composer-agent`. Skill IDs and workflow behavior retain their upstream names.
+
+Once the package is published, run this in the project where you want to use it:
+
+```bash
+npx @givolt/i3-composer-agent --codebuddy
+# Or prepare a bundle for another host:
+npx @givolt/i3-composer-agent --codex
+npx @givolt/i3-composer-agent --claude
+```
+
+The CLI prepares a persistent `./i3-composer-agent/` directory with all 25 skills,
+9 commands, 4 personas, and shared references. It prints the native registration
+commands; run those in the selected host to enable the plugin.
+
+### CodeBuddy / Claude Code
+
+```text
+/plugin marketplace add ./i3-composer-agent
+/plugin install i3-composer-agent@i3-composer-agent
+```
+
+Use the absolute directory printed by the CLI if the host has a different
+working directory. See [CodeBuddy setup](docs/codebuddy-setup.md).
+
+### Codex
+
+```bash
+codex plugin marketplace add ./i3-composer-agent
+codex plugin add i3-composer-agent@i3-composer-agent
+```
+
+Start a new Codex session. Invoke the existing skills by name, using `/skills`
+or `$spec-driven-development` in CLI/IDE. This conversion preserves Codex's
+skill adapter; lifecycle slash-command adaptation is a separate task.
+See [Codex setup](docs/codex-setup.md).
+
+### Bundle options
+
+```bash
+npx @givolt/i3-composer-agent --extract --dir /path/to/i3-composer-agent
+npx @givolt/i3-composer-agent --codebuddy --dir /path/to/plugin --dry-run
+npx @givolt/i3-composer-agent --codebuddy --dir /path/to/plugin --force
+```
+
+An existing directory is refused unless `--force` targets an i3 Composer Agent
+bundle. Replacement keeps the previous directory as a backup. No repository
+AGENTS.md or CLAUDE.md is copied into the target project.
+
+## Commands
+
+Hosts supporting Claude-compatible plugin commands load these workflows.
+Use the namespaced form, for example `/i3-composer-agent:spec`.
+
+| Command | Workflow |
+| --- | --- |
+| `/i3-composer-agent:spec` | Define objectives, constraints, and acceptance criteria |
+| `/i3-composer-agent:plan` | Write ordered, verifiable tasks |
+| `/i3-composer-agent:build` | Implement the next task with verification |
+| `/i3-composer-agent:build auto` | Execute the approved plan with per-task verification |
+| `/i3-composer-agent:test` | Test-first development and regression checks |
+| `/i3-composer-agent:constraints` | Establish a written quality bar |
+| `/i3-composer-agent:review` | Review code quality and correctness |
+| `/i3-composer-agent:webperf` | Audit web performance |
+| `/i3-composer-agent:code-simplify` | Simplify code without changing behavior |
+| `/i3-composer-agent:ship` | Review launch readiness and rollback |
+
+## All 25 Skills
+
+The commands above are entry points. The pack includes 25 skills total — 24 lifecycle skills plus the `using-agent-skills` meta-skill. Each skill is a structured workflow with steps, verification gates, and anti-rationalization tables. You can also reference any skill directly.
+
+### Meta - Discover which skill applies
+
+| Skill | What It Does | Use When |
+|-------|-------------|----------|
+| [using-agent-skills](skills/using-agent-skills/SKILL.md) | Maps incoming work to the right skill workflow and defines shared operating rules | Starting a session or deciding which skill applies |
+
+### Define - Clarify what to build
+
+| Skill | What It Does | Use When |
+|-------|-------------|----------|
+| [interview-me](skills/interview-me/SKILL.md) | One-question-at-a-time interview that extracts what the user actually wants instead of what they think they should want, until ~95% confidence | The ask is underspecified, or the user invokes "interview me" / "grill me" |
+| [idea-refine](skills/idea-refine/SKILL.md) | Structured divergent/convergent thinking to turn vague ideas into concrete proposals | You have a rough concept that needs exploration |
+| [spec-driven-development](skills/spec-driven-development/SKILL.md) | Write a PRD covering objectives, commands, structure, code style, testing, and boundaries before any code | Starting a new project, feature, or significant change |
+| [constraint-driven-development](skills/constraint-driven-development/SKILL.md) | Interviews you for a quality bar with sane default thresholds, writes CONSTRAINTS.md, places each check by cost, and catches agents silencing checks or skipping tests to get green | No standards are written down, or an agent is producing more than anyone reads |
+
+### Plan - Break it down
+
+| Skill | What It Does | Use When |
+|-------|-------------|----------|
+| [planning-and-task-breakdown](skills/planning-and-task-breakdown/SKILL.md) | Decompose specs into small, verifiable tasks with acceptance criteria and dependency ordering | You have a spec and need implementable units |
+
+### Build - Write the code
+
+| Skill | What It Does | Use When |
+|-------|-------------|----------|
+| [incremental-implementation](skills/incremental-implementation/SKILL.md) | Thin vertical slices - implement, test, verify, commit. Feature flags, safe defaults, rollback-friendly changes | Any change touching more than one file |
+| [test-driven-development](skills/test-driven-development/SKILL.md) | Red-Green-Refactor, test pyramid (80/15/5), test sizes, DAMP over DRY, Beyonce Rule, browser testing | Implementing logic, fixing bugs, or changing behavior |
+| [context-engineering](skills/context-engineering/SKILL.md) | Feed agents the right information at the right time - rules files, context packing, MCP integrations | Starting a session, switching tasks, or when output quality drops |
+| [source-driven-development](skills/source-driven-development/SKILL.md) | Ground every framework decision in official documentation - verify, cite sources, flag what's unverified | You want authoritative, source-cited code for any framework or library |
+| [doubt-driven-development](skills/doubt-driven-development/SKILL.md) | Adversarial fresh-context review of every non-trivial decision in-flight - CLAIM → EXTRACT → DOUBT → RECONCILE → STOP, with optional user-authorized cross-model escalation | Stakes are high (production, security, irreversible), working in unfamiliar code, or a confident output is cheaper to verify now than to debug later |
+| [frontend-ui-engineering](skills/frontend-ui-engineering/SKILL.md) | Component architecture, design systems, state management, responsive design, WCAG 2.1 AA accessibility | Building or modifying user-facing interfaces |
+| [api-and-interface-design](skills/api-and-interface-design/SKILL.md) | Contract-first design, Hyrum's Law, One-Version Rule, error semantics, boundary validation | Designing APIs, module boundaries, or public interfaces |
+
+### Verify - Prove it works
+
+| Skill | What It Does | Use When |
+|-------|-------------|----------|
+| [browser-testing-with-devtools](skills/browser-testing-with-devtools/SKILL.md) | Chrome DevTools MCP for live runtime data - DOM inspection, console logs, network traces, performance profiling | Building or debugging anything that runs in a browser |
+| [debugging-and-error-recovery](skills/debugging-and-error-recovery/SKILL.md) | Five-step triage: reproduce, localize, reduce, fix, guard. Stop-the-line rule, safe fallbacks | Tests fail, builds break, or behavior is unexpected |
+
+### Review - Quality gates before merge
+
+| Skill | What It Does | Use When |
+|-------|-------------|----------|
+| [code-review-and-quality](skills/code-review-and-quality/SKILL.md) | Five-axis review, change sizing (~100 lines), severity labels (Nit/Optional/FYI), review speed norms, splitting strategies | Before merging any change |
+| [code-simplification](skills/code-simplification/SKILL.md) | Chesterton's Fence, Rule of 500, reduce complexity while preserving exact behavior | Code works but is harder to read or maintain than it should be |
+| [security-and-hardening](skills/security-and-hardening/SKILL.md) | OWASP Top 10 prevention, auth patterns, secrets management, dependency auditing, three-tier boundary system | Handling user input, auth, data storage, or external integrations |
+| [performance-optimization](skills/performance-optimization/SKILL.md) | Measure-first approach - Core Web Vitals targets, profiling workflows, bundle analysis, anti-pattern detection | Performance requirements exist or you suspect regressions |
+
+### Ship - Deploy with confidence
+
+| Skill | What It Does | Use When |
+|-------|-------------|----------|
+| [git-workflow-and-versioning](skills/git-workflow-and-versioning/SKILL.md) | Trunk-based development, atomic commits, change sizing (~100 lines), the commit-as-save-point pattern | Making any code change (always) |
+| [ci-cd-and-automation](skills/ci-cd-and-automation/SKILL.md) | Shift Left, Faster is Safer, feature flags, quality gate pipelines, failure feedback loops | Setting up or modifying build and deploy pipelines |
+| [deprecation-and-migration](skills/deprecation-and-migration/SKILL.md) | Code-as-liability mindset, compulsory vs advisory deprecation, migration patterns, zombie code removal | Removing old systems, migrating users, or sunsetting features |
+| [documentation-and-adrs](skills/documentation-and-adrs/SKILL.md) | Architecture Decision Records, API docs, inline documentation standards - document the *why* | Making architectural decisions, changing APIs, or shipping features |
+| [observability-and-instrumentation](skills/observability-and-instrumentation/SKILL.md) | Structured logging, RED metrics, OpenTelemetry tracing, symptom-based alerting - instrument as you build | Adding telemetry, or shipping anything that runs in production |
+| [shipping-and-launch](skills/shipping-and-launch/SKILL.md) | Pre-launch checklists, feature flag lifecycle, staged rollouts, rollback procedures, monitoring setup | Preparing to deploy to production |
+
+---
+
+## Personas and shared references
+
+The four original personas remain in [agents/](agents/): code reviewer, security
+auditor, test engineer, and web performance auditor. Shared checklists remain in [references/](references/).
+Their relative layout is preserved across npm packaging and bundle extraction.
+
+## Other hosts
+
+The existing [host guides](docs/other-hosts.md) describe additional integrations.
+Prepare the complete local bundle first and use its path in host-specific setup.
+Per-skill installation is separate and may omit the shared references, command
+wrappers, and personas.
+
+## Development and release
+
+```bash
+npm run rebrand:check
+npm run validate
+npm test
+node scripts/run-evals.js --min-rank1 95
+npm pack --pack-destination /path/to/release-directory
+```
+
+[npx](https://docs.npmjs.com/cli/npm-exec/) runs the package executable;
+`npm pack` builds a tarball and `npm publish` publishes it.
+Local preparation does not establish registry publication or model behavior.
+See [brand maintenance](rebrand/MAINTENANCE.md) for source/release separation.
+
+## License
+
+MIT. Original copyright and license are retained in [LICENSE](LICENSE).

package/rebrand/templates/codebuddy-setup.md

@@ -0,0 +1,41 @@
+# Using i3 Composer Agent with CodeBuddy
+
+Prepare the complete plugin inside the project where you want to use it:
+
+```bash
+npx @givolt/i3-composer-agent --codebuddy
+```
+
+In the CodeBuddy chat, register the prepared directory and install the plugin:
+
+```text
+/plugin marketplace add ./i3-composer-agent
+/plugin install i3-composer-agent@i3-composer-agent
+```
+
+Use the absolute directory printed by the CLI if CodeBuddy has a different
+working directory. Choose the intended installation scope in CodeBuddy's native
+plugin manager. Reload plugins or start a new session after installation.
+
+CodeBuddy supports the existing `.claude-plugin/plugin.json` compatibility
+manifest. It declares `.claude/commands/` and `commands/`, preserving the nine
+original lifecycle commands and their workflow content.
+
+```text
+/i3-composer-agent:spec
+/i3-composer-agent:plan
+/i3-composer-agent:build
+/i3-composer-agent:build auto
+/i3-composer-agent:review
+/i3-composer-agent:ship
+```
+
+Skill IDs, persona names, artifact paths, and workflow gates retain their
+upstream behavior. The plugin namespace changes to `i3-composer-agent`.
+
+The bundle includes all skills and shared `references/`. Installing individual
+skills is a different distribution method and does not install the command
+wrappers or persona definitions.
+
+The CLI prepares files and prints registration commands. Actual host discovery
+and model execution should be verified after registering the plugin.

package/rebrand/templates/codex-setup.md

@@ -0,0 +1,34 @@
+# Using i3 Composer Agent with Codex
+
+Prepare the complete plugin inside the project where you want to use it:
+
+```bash
+npx @givolt/i3-composer-agent --codex
+```
+
+The CLI copies a persistent `./i3-composer-agent/` bundle and prints these
+native registration commands. Run them to enable the plugin:
+
+```bash
+codex plugin marketplace add ./i3-composer-agent
+codex plugin add i3-composer-agent@i3-composer-agent
+```
+
+Start a new Codex session after registration. All 25 existing skills keep their
+original IDs. In CLI/IDE, use `/skills` or `$spec-driven-development`; in chat,
+explicitly request the relevant skill from i3 Composer Agent.
+
+The adapter in `.codex-plugin/plugin.json` points at the unchanged `skills/`
+layout. Shared checklists remain under `references/`, so skill-relative links
+resolve inside the complete plugin bundle.
+
+The short lifecycle commands (`/spec`, `/plan`, `/build`, `/ship`) remain
+available in hosts that load the Claude-compatible command manifest. Codex
+lifecycle-command adaptation is separate from this brand conversion. Native
+Codex `/plan` switches planning mode; it is not the plugin's planning wrapper.
+
+Do not preload `using-agent-skills/SKILL.md` into always-on context: Codex routes
+skills natively. The meta-skill can remain installed and explicitly invoked.
+
+For local source testing, replace `./i3-composer-agent` above with the absolute
+path to the branded checkout. The CLI does not modify existing plugin settings.

package/references/accessibility-checklist.md

@@ -0,0 +1,160 @@
+# Accessibility Checklist
+
+Quick reference for WCAG 2.1 AA compliance. Use alongside the `frontend-ui-engineering` skill.
+
+## Table of Contents
+
+- [Essential Checks](#essential-checks)
+- [Common HTML Patterns](#common-html-patterns)
+- [Testing Tools](#testing-tools)
+- [Quick Reference: ARIA Live Regions](#quick-reference-aria-live-regions)
+- [Common Anti-Patterns](#common-anti-patterns)
+
+## Essential Checks
+
+### Keyboard Navigation
+- [ ] All interactive elements focusable via Tab key
+- [ ] Focus order follows visual/logical order
+- [ ] Focus is visible (outline/ring on focused elements)
+- [ ] Custom widgets have keyboard support (Enter to activate, Escape to close)
+- [ ] No keyboard traps (user can always Tab away from a component)
+- [ ] Skip-to-content link at top of page - visible (at least) on keyboard focus
+- [ ] Modals trap focus while open, return focus on close
+
+### Screen Readers
+- [ ] All images have `alt` text (or `alt=""` for decorative images)
+- [ ] All form inputs have associated labels (`<label>` or `aria-label`)
+- [ ] Buttons and links have descriptive text (not "Click here")
+- [ ] Icon-only buttons have `aria-label`
+- [ ] Page has one `<h1>` and headings don't skip levels
+- [ ] Dynamic content changes announced (`aria-live` regions)
+- [ ] Tables have `<th>` headers with scope
+
+### Visual
+- [ ] Text contrast ≥ 4.5:1 (normal text) or ≥ 3:1 (large text, 18px+)
+- [ ] UI components contrast ≥ 3:1 against background
+- [ ] Color is not the only way to convey information
+- [ ] Text resizable to 200% without breaking layout
+- [ ] No content that flashes more than 3 times per second
+
+### Forms
+- [ ] Every input has a visible label
+- [ ] Required fields indicated (not by color alone)
+- [ ] Error messages specific and associated with the field
+- [ ] Error state visible by more than color (icon, text, border)
+- [ ] Form submission errors summarized and focusable
+- [ ] Known fields use autocomplete (for example `type="email" autocomplete="email"`)
+
+### Content
+- [ ] Language declared (`<html lang="en">`)
+- [ ] Page has a descriptive `<title>`
+- [ ] Links distinguish from surrounding text (not by color alone)
+- [ ] Touch targets ≥ 44x44px on mobile
+- [ ] Meaningful empty states (not blank screens)
+
+## Common HTML Patterns
+
+### Buttons vs. Links
+
+```html
+<!-- Use <button> for actions -->
+<button onClick={handleDelete}>Delete Task</button>
+
+<!-- Use <a> for navigation -->
+<a href="/tasks/123">View Task</a>
+
+<!-- NEVER use div/span as buttons -->
+<div onClick={handleDelete}>Delete</div>  <!-- BAD -->
+```
+
+### Form Labels
+
+```html
+<!-- Explicit label association -->
+<label htmlFor="email">Email address</label>
+<input id="email" type="email" required />
+
+<!-- Implicit wrapping -->
+<label>
+  Email address
+  <input type="email" required />
+</label>
+
+<!-- Hidden label (visible label preferred) -->
+<input type="search" aria-label="Search tasks" />
+```
+
+### ARIA Roles
+
+```html
+<!-- Navigation -->
+<nav aria-label="Main navigation">...</nav>
+<nav aria-label="Footer links">...</nav>
+
+<!-- Status messages -->
+<div role="status" aria-live="polite">Task saved</div>
+
+<!-- Alert messages -->
+<div role="alert">Error: Title is required</div>
+
+<!-- Modal dialogs -->
+<dialog aria-modal="true" aria-labelledby="dialog-title">
+  <h2 id="dialog-title">Confirm Delete</h2>
+  ...
+</dialog>
+
+<!-- Loading states -->
+<div aria-busy="true" aria-label="Loading tasks">
+  <Spinner />
+</div>
+```
+
+### Accessible Lists
+
+```html
+<ul role="list" aria-label="Tasks">
+  <li>
+    <input type="checkbox" id="task-1" aria-label="Complete: Buy groceries" />
+    <label htmlFor="task-1">Buy groceries</label>
+  </li>
+</ul>
+```
+
+## Testing Tools
+
+```bash
+# Automated audit
+npx axe-core          # Programmatic accessibility testing
+npx pa11y             # CLI accessibility checker
+
+# In browser
+# Chrome DevTools → Lighthouse → Accessibility
+# Chrome DevTools → Elements → Accessibility tree
+
+# Screen reader testing
+# macOS: VoiceOver (Cmd + F5)
+# Windows: NVDA (free) or JAWS
+# Linux: Orca
+```
+
+## Quick Reference: ARIA Live Regions
+
+| Value | Behavior | Use For |
+|-------|----------|---------|
+| `aria-live="polite"` | Announced at next pause | Status updates, saved confirmations |
+| `aria-live="assertive"` | Announced immediately | Errors, time-sensitive alerts |
+| `role="status"` | Same as `polite` | Status messages |
+| `role="alert"` | Same as `assertive` | Error messages |
+
+## Common Anti-Patterns
+
+| Anti-Pattern | Problem | Fix |
+|---|---|---|
+| `div` as button | Not focusable, no keyboard support | Use `<button>` |
+| Missing `alt` text | Images invisible to screen readers | Add descriptive `alt` |
+| Color-only states | Invisible to color-blind users | Add icons, text, or patterns |
+| Autoplaying media | Disorienting, can't be stopped | Add controls, don't autoplay |
+| Custom dropdown with no ARIA | Unusable by keyboard/screen reader | Use native `<select>` or proper ARIA listbox |
+| Removing focus outlines | Users can't see where they are | Style outlines, don't remove them |
+| Empty links/buttons | "Link" announced with no description | Add text or `aria-label` |
+| `tabindex > 0` | Breaks natural tab order | Use `tabindex="0"` or `-1` only |

package/references/definition-of-done.md

@@ -0,0 +1,67 @@
+# Definition of Done
+
+A standing, project-wide bar that every change must clear before it counts as done. Unlike acceptance criteria, which vary per task and answer "did we build the right thing?", the Definition of Done is the same every time and answers "is this finished to our standard?". Use it as the final gate in `planning-and-task-breakdown`, `incremental-implementation`, and `shipping-and-launch`.
+
+## Definition of Done vs. Acceptance Criteria
+
+| | Acceptance Criteria | Definition of Done |
+|---|---|---|
+| Scope | Specific to one task or spec | Applies to every increment |
+| Changes | Different for each item | Fixed and reused |
+| Answers | "Did we build *this thing*?" | "Is it *ready*?" |
+| Owner | Defined when planning the task | Defined once for the project |
+| Example | "User can reset password via email link" | "Tests pass, no regressions, docs updated" |
+
+The two are complementary. A task is done only when **its** acceptance criteria are met **and** the standing Definition of Done is satisfied. Skipping either leaves work that looks finished but is not.
+
+## The Standing Checklist
+
+Apply this to every change before declaring it done.
+
+### Correctness
+- [ ] All acceptance criteria for the task are met
+- [ ] Code runs and behaves as intended, verified at runtime, not just compiled or typechecked
+- [ ] New behavior is covered by tests that fail without the change and pass with it
+- [ ] Existing tests still pass; no regressions introduced
+- [ ] Edge cases and error paths are handled, not just the happy path
+
+### Quality
+- [ ] Code reveals intent through naming and structure; no comments needed to explain *what* it does
+- [ ] No duplicated business logic
+- [ ] No dead code, debug output, or commented-out blocks left behind
+- [ ] Changes are scoped to the task; no unrelated refactors snuck in
+- [ ] Linting and formatting pass
+
+The depth behind these items lives in `code-review-and-quality` (the five-axis review) and `code-simplification` (reducing complexity without changing behavior).
+
+### Integration
+- [ ] Change works with the rest of the system, not just in isolation
+- [ ] Database migrations, config changes, and feature flags are accounted for
+- [ ] Backward compatibility considered for any public interface or API change
+
+### Documentation
+- [ ] Public interfaces, APIs, and user-facing behavior are documented
+- [ ] Architectural decisions worth preserving are recorded (see `documentation-and-adrs`)
+- [ ] Documentation describes the current state in timeless language, not the change history
+
+### Ship-readiness
+- [ ] Security implications reviewed for any untrusted input, auth, or data handling (see `security-and-hardening`)
+- [ ] Observability in place for new critical paths (logs, metrics, traces) (see `observability-and-instrumentation`)
+- [ ] Rollback path exists for anything risky (see `shipping-and-launch`)
+- [ ] The human has reviewed and approved before merge or deploy
+
+## How to Apply
+
+- **Per task**: confirm the Correctness and Quality sections before checking the task off.
+- **Per feature**: confirm Integration and Documentation before considering the feature complete.
+- **Per release**: the full checklist is the floor; `shipping-and-launch` adds the deploy-specific gates on top.
+
+Tailor the list to the project once, then reuse it unchanged. A Definition of Done that is renegotiated every sprint is not a Definition of Done.
+
+## Red Flags
+
+- "It's done, I just haven't run it yet": unverified work is not done.
+- "Tests pass" used as a synonym for done while docs, regressions, or runtime verification are skipped.
+- A different bar applied depending on deadline pressure.
+- Acceptance criteria treated as the whole bar, with no standing quality floor.
+- "Done" declared before human review on changes that need it.

package/references/observability-checklist.md

@@ -0,0 +1,92 @@
+# Observability Checklist
+
+Quick reference for instrumenting production code. Use alongside the `observability-and-instrumentation` skill.
+
+## Table of Contents
+
+- [On-Call Questions (Start Here)](#on-call-questions-start-here)
+- [Structured Logging](#structured-logging)
+- [Metrics](#metrics)
+- [Distributed Tracing](#distributed-tracing)
+- [Alerting](#alerting)
+- [Dashboards](#dashboards)
+- [Verify the Telemetry](#verify-the-telemetry)
+- [Pre-Launch Gate](#pre-launch-gate)
+
+## On-Call Questions (Start Here)
+
+Telemetry without a question is noise. Before instrumenting anything:
+
+- [ ] 2–4 questions an on-call engineer will ask about this feature are written down
+- [ ] Every signal below maps to one of those questions
+- [ ] Each question is matched to the right signal type: metrics say **that** something is wrong, traces say **where**, logs say **why**
+
+## Structured Logging
+
+- [ ] Logs are structured (JSON) with stable event names — not free-form strings
+- [ ] Every log line carries a correlation/request ID, generated or accepted at the system boundary
+- [ ] Correlation ID is propagated on every outbound call and async boundary (HTTP headers, queue metadata)
+- [ ] Any log stream written by more than one entry point (scheduler, replay endpoint, manual run) carries an entry-point field, set where the run starts and propagated alongside the correlation ID
+- [ ] Log levels are consistent: `error` = invariant broken, someone may act; `warn` = degraded but handled; `info` = significant business event; `debug` = off in production
+- [ ] No secrets, tokens, passwords, or unredacted PII in any log line (hard rule from `security-and-hardening`)
+- [ ] Fields are allowlisted — no whole request/response bodies, no auth headers
+- [ ] External service calls logged with metadata only: endpoint, status, latency, attempt count, sanitized identifiers
+- [ ] Actual log output spot-checked: structured fields, not `[object Object]`
+
+## Metrics
+
+- [ ] **RED** instrumented for every endpoint and every external dependency: Rate, Errors, Duration
+- [ ] **USE** instrumented for every resource (queues, pools, hosts): Utilization, Saturation, Errors
+- [ ] Latency is a histogram; p50/p95/p99 queryable — never an average
+- [ ] All labels come from small, fixed sets (route template, status class, provider name)
+- [ ] No unbounded label values: no user IDs, tenant IDs, emails, raw URLs, request IDs, or error message text
+- [ ] Status codes grouped by class (`5xx`, not `503`)
+- [ ] Queue depth and processing duration tracked for every worker/queue
+
+## Distributed Tracing
+
+- [ ] OpenTelemetry (or equivalent) initialized at service startup, before other imports
+- [ ] Auto-instrumentation enabled for HTTP, gRPC, and DB clients
+- [ ] Trace context propagated on every outbound call (W3C `traceparent`/`tracestate`) and extracted from every inbound request
+- [ ] Context survives async boundaries — queue messages carry trace metadata
+- [ ] Manual spans only around meaningful internal units of work, with the attributes on-call will filter by
+- [ ] No secrets or PII as span attributes
+- [ ] Head-based sampling at a low default rate; 100% of errors kept if tail sampling is available
+
+## Alerting
+
+- [ ] Every alert is symptom-based (error rate, p99 latency, queue age) — causes (CPU, disk, restarts) go to dashboards, not pagers
+- [ ] Every alert is actionable; "ignore it, it self-heals" alerts are deleted
+- [ ] Every alert links to a runbook — minimum three lines: what it means, first query to run, escalation path
+- [ ] Thresholds and durations justified by an SLO or historical data, not guesses
+- [ ] Two severities only: **page** (user-facing, act now) and **ticket** (degradation, act this week)
+- [ ] Each new alert test-fired once: it reached the right channel and the runbook link works
+- [ ] No alerts that fire daily and get acknowledged without action
+
+## Dashboards
+
+- [ ] Service health dashboard exists: error rate, latency p99, traffic, saturation
+- [ ] Dependency health panel shows per-service error rates and latency
+- [ ] Dashboard answers the on-call questions from the top of this checklist — not "everything except the answer"
+- [ ] Default time range is sensible (1h–6h, not 30d)
+
+## Verify the Telemetry
+
+Instrumentation is code; it can be wrong:
+
+- [ ] Forced an error in staging → found it in the logs by correlation ID
+- [ ] Sent test traffic → metric series appear with expected labels and sane values
+- [ ] Followed one request end-to-end in the tracing UI → no broken spans
+- [ ] An induced failure was diagnosed from telemetry alone, without reading the source
+
+## Pre-Launch Gate
+
+Before a feature ships to production, all of the following are true:
+
+- [ ] Structured logs flowing to the log aggregator
+- [ ] RED metrics visible in dashboards for every new endpoint and dependency
+- [ ] At least one symptom-based alert configured, with runbook, test-fired
+- [ ] A request can be traced across every service it touches
+- [ ] On-call knows where the runbooks are
+
+For launch-day monitoring sequence and rollback triggers, see the `shipping-and-launch` skill.