observability

name	observability
version	0.13.0
implements_spec	0.3.2
description	Generate or audit an observability wrapper that satisfies AgenticApps core spec §10 for the project's tech stack. Three subcommands: `init` (greenfield scaffold — detect stacks, materialise wrapper + middleware + policy behind consent gates, wire the entry file, write the `observability:` metadata block, smoke-verify), `scan` (brownfield validate → .scan-report.md; flags `--since-commit <ref>` for §10.9 delta scans and `--update-baseline` for `.observability/baseline.json`), and `scan-apply` (apply high-confidence findings with per-file consent, regenerating the baseline). Use when adding or auditing logging, tracing, error capture, spans, or Sentry/OTLP/Axiom destinations, or when wiring a §10 observability wrapper into a new or existing service. Per-stack templates and the full per-subcommand procedure live in this skill's body and ./init, ./scan, ./scan-apply, ./templates. Host-neutral — /observability on Claude, $observability on Codex.

observability — AgenticApps observability scaffolder + auditor

This skill implements the generator obligation in core spec §10.7 for AgenticApps projects (cparx, fx-signals, agenticapps-dashboard, and future projects). It is a Claude Code skill: when invoked, you (the agent) follow the procedure prompts below using the Read, Grep, Write, and Edit tools.

Dispatch

The skill takes one positional argument (the subcommand) and delegates to a sub-skill prompt:

Subcommand	Sub-skill prompt	Purpose
init	./init/INIT.md	Greenfield scaffold + wiring (9 phases, 3 consent gates; shipped v0.3.1, closes #26).
scan	./scan/SCAN.md	Walk project, produce .scan-report.md.
scan-apply	./scan-apply/APPLY.md	Apply high-confidence findings with consent.

If the subcommand is omitted, default to scan (the safest no-op operation; produces a report without modifying anything).

Routing-table structural invariant: every Sub-skill prompt path in the table above MUST exist on disk inside this skill directory. This is a contractual invariant — slash-discovery loads the skill via the symlink at ~/.claude/skills/observability (per migration 0002 Step 4 / migration 0012), and dispatch resolves the routed paths relative to the skill root. A missing routed path means the subcommand is unrunnable. The mechanical Q8 check enforced during phase planning (introduced phase 15; codified in .planning/'s gsd-review prompt template per the PLAN v2 lesson) is:

grep -oiE '\./[a-zA-Z/_-]+\.md' observability/SKILL.md | sort -u | while read rel; do
  abs="observability/${rel#./}"
  [ -f "$abs" ] && echo "  OK $rel" || echo "  MISSING $rel"
done

All three routed dispatch paths (./init/INIT.md, ./scan/SCAN.md, ./scan-apply/APPLY.md) resolve as of v0.3.1. The ./init/INIT.md path was historically MISSING at v0.3.0 (issue #26); shipping that file structurally closes #26 and is the load-bearing piece of this version bump. ./enforcement/README.md is referenced in this skill's top-level description as documentation but is not a routed dispatch target — it is outside the invariant's scope by design.

Resolution rules

Per spec §10.7.1 (added v0.2.1), all target paths in this skill are resolved against the language module root, not the project root. The init and scan procedures detect module roots by scanning for path_root manifest files declared in each stack's templates/<stack-id>/meta.yaml.

Stack templates

The per-stack code templates live at ./templates/<stack-id>/. Each contains meta.yaml (detection signals + target paths + parameters), the wrapper module, the middleware, env-additions docs, and a contract test fixture.

Currently shipped:

Stack ID	Manifest	Purpose
ts-cloudflare-worker	package.json	Cloudflare Workers (fetch, scheduled, queue).
ts-cloudflare-pages	package.json	Cloudflare Pages Functions.
ts-supabase-edge	supabase/config.toml	Supabase Edge Functions (Deno).
ts-react-vite	package.json	React + Vite SPA frontends.
go-fly-http	go.mod	Go HTTP services on Fly.io (chi, std net/http).

Conformance with spec §10.7

This skill satisfies §10.7's four generator-obligation requirements:

1. Scaffolds wrapper modules per stack — init subcommand emits into the project from templates/<stack-id>/.
2. Wires trace propagation middleware — init writes the middleware files and edits the entry-point file.
3. Validates existing projects — scan subcommand walks the project against scan/checklist.md and emits a confidence-ranked report.
4. Apply only with consent — scan-apply shows per-file diffs and requires explicit confirmation; never auto-applies.

When to invoke

User intent	Subcommand
New project; wire observability from scratch	init
Existing project; check conformance, no changes	scan
Existing project; apply scan-found high-confidence gaps	scan-apply
Migration framework upgrade (per ADR-0013)	init then scan

The Claude Code workflow integration lives in migrations-fragment.md and is consumed by the migrations framework (per ADR-0013) when adopting spec v0.2.x in an existing project.