agenticapps-eu/agenticapps-observability/agenticapps-observability

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:

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:

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>/.

1. Wires trace propagation middleware — init writes the

middleware files and edits the entry-point file.

1. Validates existing projects — scan subcommand walks the

project against scan/checklist.md and emits a confidence-ranked report.

1. Apply only with consent — scan-apply shows per-file diffs and

requires explicit confirmation; never auto-applies.

When to invoke

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.