| 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:
- Scaffolds wrapper modules per stack —
init subcommand emits
into the project from templates/<stack-id>/.
- Wires trace propagation middleware —
init writes the
middleware files and edits the entry-point file.
- Validates existing projects —
scan subcommand walks the
project against scan/checklist.md and emits a confidence-ranked
report.
- 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.
