{ "catalog": "ai-atoms", "version": "0.1.0", "built_at": "2026-05-28T15:20:32+00:00", "atoms": [ { "schema": "https://ai-atoms.com/schemas/hook-v1.json", "type": "hook", "id": "hook/audit-command", "version": "1.0.0", "name": "Audit Command Wrapper", "description": "PostToolUse hook that records every wrapped command invocation (git, gh, etc.) to the audit log. Makes the appearance side of the audit trail reliable — absence of an audit line for an expected command is itself visible during forensic review. Records WRAPPED_CMD, WRAPPED_ARGV, WRAPPED_EXIT, and WRAPPED_DURATION.", "event": "PostToolUse", "language": "python", "trigger": { "type": "always" }, "blocking": false, "side_effects": [ "appends invocation record to ~/.ai/audit/interactions/.jsonl" ], "authored_by": "convergent-systems-key", "tags": [ "audit", "logging", "governance", "commands", "claude-code" ], "lifecycle": "stable", "platforms": [ "linux", "macos", "windows" ], "platform_notes": "Logic is cross-platform. Wiring: use 'ai hooks run audit-command' in settings.json — the ai binary discovers Python on each OS. Reads env vars WRAPPED_CMD etc. — set by the ai command wrappers on all platforms." }, { "schema": "https://ai-atoms.com/schemas/hook-v1.json", "type": "hook", "id": "hook/audit-logger", "version": "1.0.0", "name": "Interaction Audit Logger", "description": "Appends a JSONL record to ~/.ai/audit/interactions/.jsonl for every Claude Code hook event: SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop, SessionEnd, SubagentStop, PreCompact. Non-blocking. Implements Common.md §5.2.", "event": "PreToolUse", "language": "python", "trigger": { "type": "always" }, "blocking": false, "side_effects": [ "writes to ~/.ai/audit/interactions/.jsonl" ], "authored_by": "convergent-systems-key", "tags": [ "audit", "logging", "governance", "claude-code" ], "lifecycle": "stable", "platforms": [ "linux", "macos", "windows" ], "platform_notes": "Logic is cross-platform. Wiring: use 'ai hooks run audit-logger' in settings.json — the ai binary discovers Python on each OS. Writes to ~/.ai/audit/ — path resolves correctly cross-platform via Python pathlib." }, { "schema": "https://ai-atoms.com/schemas/hook-v1.json", "type": "hook", "id": "hook/branch-guard", "version": "1.0.0", "name": "Branch Guard", "description": "Prevents direct mutations to protected branches (main, release/*). Intercepts git commit, merge, rebase, cherry-pick, revert, am, pull, and push operations when the current HEAD is a protected branch. Requires explicit approval per Common.md §2.2.", "event": "PreToolUse", "language": "python", "trigger": { "type": "tool-name", "pattern": "Bash" }, "blocking": true, "side_effects": [ "blocks tool call with explanation", "emits protected-branch warning" ], "authored_by": "convergent-systems-key", "tags": [ "git", "governance", "branch-protection", "claude-code" ], "lifecycle": "stable", "platforms": [ "linux", "macos", "windows" ], "platform_notes": "Logic is cross-platform. Wiring: use 'ai hooks run branch-guard' in settings.json — the ai binary discovers Python on each OS. Inspects git command strings — git works cross-platform. Python shebang ignored on Windows; invoked via 'ai hooks run'." }, { "schema": "https://ai-atoms.com/schemas/hook-v1.json", "type": "hook", "id": "hook/checkpoint-tick", "version": "1.0.0", "name": "Checkpoint Tick", "description": "30-minute background tick that writes a HANDOFF.md so context-window resets don't lose state. Implements Common.md §U10 (handoff + checkpoint) and §U13 (context-window discipline). If more than 30 minutes have elapsed since the last tick, invokes the /checkpoint skill or emits a minimal HANDOFF.md template at cwd. Updates the timestamp on every run.", "event": "Stop", "language": "python", "trigger": { "type": "always" }, "blocking": false, "side_effects": [ "writes HANDOFF.md at cwd", "updates ~/.config/aiConstitution/checkpoints//.last-tick" ], "authored_by": "convergent-systems-key", "tags": [ "checkpoint", "handoff", "context-window", "continuity", "claude-code" ], "lifecycle": "stable", "platforms": [ "linux", "macos", "windows" ], "platform_notes": "Logic is cross-platform. Wiring: use 'ai hooks run checkpoint-tick' in settings.json — the ai binary discovers Python on each OS. Already contains sys.platform == 'win32' logic for config dir (%APPDATA%\\aiConstitution on Windows)." }, { "schema": "https://ai-atoms.com/schemas/hook-v1.json", "type": "hook", "id": "hook/destructive-gh-guard", "version": "1.0.0", "name": "Destructive GitHub CLI Guard", "description": "Blocks high-blast-radius, irreversible gh CLI operations per Common.md §2.2. Denies without explicit --force-i-mean-it confirmation: gh repo delete, gh release delete, gh secret delete, and gh auth logout. All other gh subcommands pass through.", "event": "PreToolUse", "language": "python", "trigger": { "type": "tool-name", "pattern": "Bash" }, "blocking": true, "side_effects": [ "blocks tool call with explanation and bypass instructions" ], "authored_by": "convergent-systems-key", "tags": [ "governance", "gh-cli", "destructive", "guard", "claude-code" ], "lifecycle": "stable", "platforms": [ "linux", "macos", "windows" ], "platform_notes": "Logic is cross-platform. Wiring: use 'ai hooks run destructive-gh-guard' in settings.json — the ai binary discovers Python on each OS. gh CLI available on all platforms. Python logic is cross-platform." }, { "schema": "https://ai-atoms.com/schemas/hook-v1.json", "type": "hook", "id": "hook/destructive-kubectl-guard", "version": "1.0.0", "name": "Destructive kubectl Guard", "description": "Blocks destructive kubectl operations per Common.md §2.2. Opt-in via command-wrappers.toml. Denies kubectl delete, kubectl drain, and kubectl cordon without the bypass env AI_ALLOW_DESTRUCTIVE_KUBECTL=1. All other kubectl subcommands pass through.", "event": "PreToolUse", "language": "python", "trigger": { "type": "tool-name", "pattern": "Bash" }, "blocking": true, "side_effects": [ "blocks tool call with explanation", "bypass via AI_ALLOW_DESTRUCTIVE_KUBECTL=1" ], "authored_by": "convergent-systems-key", "tags": [ "governance", "kubectl", "kubernetes", "destructive", "guard", "claude-code" ], "lifecycle": "stable", "platforms": [ "linux", "macos", "windows" ], "platform_notes": "Logic is cross-platform. Wiring: use 'ai hooks run destructive-kubectl-guard' in settings.json — the ai binary discovers Python on each OS. kubectl available on all platforms. Python logic is cross-platform." }, { "schema": "https://ai-atoms.com/schemas/hook-v1.json", "type": "hook", "id": "hook/destructive-terraform-guard", "version": "1.0.0", "name": "Destructive Terraform Guard", "description": "Blocks terraform destroy and terraform apply per Common.md §2.2. Opt-in via command-wrappers.toml. Requires explicit bypass via AI_ALLOW_DESTRUCTIVE_TERRAFORM=1. Prevents accidental infrastructure destruction or unreviewed applies. Other tofu/terraform subcommands (plan, init, validate, output) pass through.", "event": "PreToolUse", "language": "python", "trigger": { "type": "tool-name", "pattern": "Bash" }, "blocking": true, "side_effects": [ "blocks tool call with explanation", "bypass via AI_ALLOW_DESTRUCTIVE_TERRAFORM=1" ], "authored_by": "convergent-systems-key", "tags": [ "governance", "terraform", "tofu", "infrastructure", "destructive", "guard", "claude-code" ], "lifecycle": "stable", "platforms": [ "linux", "macos", "windows" ], "platform_notes": "Logic is cross-platform. Wiring: use 'ai hooks run destructive-terraform-guard' in settings.json — the ai binary discovers Python on each OS. tofu/terraform available on all platforms. Python logic is cross-platform." }, { "schema": "https://ai-atoms.com/schemas/hook-v1.json", "type": "hook", "id": "hook/no-verify-strip", "version": "1.0.0", "name": "No-Verify Strip", "description": "PreToolUse hook that strips --no-verify from git commit commands before they execute. Per Common.md §2.2 (no skipping hooks) and the governance SPEC §10.3. Default behavior: strip silently and log the bypass attempt to the audit pipeline. The bypass can be allowed per-project via allowNoVerifyBypass=true in settings, which removes this hook from the preHooks list.", "event": "PreToolUse", "language": "python", "trigger": { "type": "tool-name", "pattern": "Bash" }, "blocking": false, "side_effects": [ "removes --no-verify flag from git commit argv", "logs bypass attempt to audit pipeline" ], "authored_by": "convergent-systems-key", "tags": [ "git", "governance", "hooks", "audit", "no-verify", "claude-code" ], "lifecycle": "stable", "platforms": [ "linux", "macos", "windows" ], "platform_notes": "Logic is cross-platform. Wiring: use 'ai hooks run no-verify-strip' in settings.json — the ai binary discovers Python on each OS. Modifies git argv in-process — cross-platform. Invoked via 'ai hooks run'." }, { "schema": "https://ai-atoms.com/schemas/hook-v1.json", "type": "hook", "id": "hook/op-redact", "version": "1.0.0", "name": "1Password & Secret Redactor", "description": "PreToolUse hook that redacts 1Password references and secret-shaped values from Claude Code tool-use payloads before they execute. Unlike secret-block which denies, this hook redacts in-place and always exits 0 — it never blocks the tool call. Patterns: GitHub tokens (gho_/ghp_/ghu_/ghs_/ghr_), Bearer tokens, op:// references, OpenAI sk- keys, PEM blocks. Writes a violation record on detection. Implements Common.md §4 (non-overridable secret handling).", "event": "PreToolUse", "language": "python", "trigger": { "type": "always" }, "blocking": false, "side_effects": [ "redacts secrets in-place in tool payload", "writes violation record to ~/.ai/audit/violations/-secret-detected.md", "outputs cleaned JSON to stdout" ], "authored_by": "convergent-systems-key", "tags": [ "security", "secrets", "redaction", "1password", "governance", "claude-code" ], "lifecycle": "stable", "platforms": [ "linux", "macos", "windows" ], "platform_notes": "Logic is cross-platform. Wiring: use 'ai hooks run op-redact' in settings.json — the ai binary discovers Python on each OS. Pure Python regex; no OS-specific calls. Works on all platforms." }, { "schema": "https://ai-atoms.com/schemas/hook-v1.json", "type": "hook", "id": "hook/secret-block", "version": "1.0.0", "name": "Secret Block", "description": "PreToolUse hook that denies Bash commands containing secret-shaped strings before they execute. Reads the canonical pattern set from hooks/patterns.json (plus patterns.local.json if present). Belt-and-suspenders alongside the secret-handling rules in Common.md §4. Emits a JSON permissionDecision deny on detection.", "event": "PreToolUse", "language": "python", "trigger": { "type": "tool-name", "pattern": "Bash" }, "blocking": true, "side_effects": [ "denies tool call with explanation when secret pattern detected" ], "authored_by": "convergent-systems-key", "tags": [ "security", "secrets", "governance", "patterns", "claude-code" ], "lifecycle": "stable", "platforms": [ "linux", "macos", "windows" ], "platform_notes": "Logic is cross-platform. Wiring: use 'ai hooks run secret-block' in settings.json — the ai binary discovers Python on each OS. Pure Python regex on stdin JSON. Works on all platforms." }, { "schema": "https://ai-atoms.com/schemas/hook-v1.json", "type": "hook", "id": "hook/secret-precommit", "version": "1.0.0", "name": "Secret Pre-commit Scanner", "description": "Git pre-commit hook and CI scanner that blocks commits containing secret-shaped strings. Two modes: (1) pre-commit — scans the staged diff (git diff --cached -U0) and aborts the commit on any match; (2) CI/range scan (--ci --base BASE --head HEAD) — scans the diff from BASE..HEAD for use in secret-scan.yml workflows. Reads canonical patterns from hooks/patterns.json.", "event": "PreToolUse", "language": "python", "trigger": { "type": "tool-name", "pattern": "Bash" }, "blocking": true, "side_effects": [ "aborts git commit on secret detection", "exits non-zero in CI scan mode on detection" ], "authored_by": "convergent-systems-key", "tags": [ "security", "secrets", "git", "pre-commit", "ci", "claude-code" ], "lifecycle": "stable", "platforms": [ "linux", "macos", "windows" ], "platform_notes": "Logic is cross-platform. Wiring: use 'ai hooks run secret-precommit' in settings.json — the ai binary discovers Python on each OS. Calls subprocess git diff — git is available cross-platform. Pre-commit mode uses 'exec python3' in the shim; Windows users should use 'ai hooks run' instead." }, { "schema": "https://ai-atoms.com/schemas/hook-v1.json", "type": "hook", "id": "hook/security-reminder", "version": "1.0.0", "name": "GitHub Actions Security Reminder", "description": "Fires when Claude Code edits a GitHub Actions workflow file. Non-blocking reminder about command injection risks, untrusted input in run: steps, and the SAFE pattern (env: with proper quoting vs direct ${{ expression }} interpolation).", "event": "PreToolUse", "language": "python", "trigger": { "type": "file-pattern", "pattern": ".github/workflows/*.yml" }, "blocking": false, "side_effects": [ "emits security guidance to stderr" ], "authored_by": "convergent-systems-key", "tags": [ "security", "github-actions", "ci", "claude-code" ], "lifecycle": "stable", "platforms": [ "linux", "macos", "windows" ], "platform_notes": "Logic is cross-platform. Wiring: use 'ai hooks run security-reminder' in settings.json — the ai binary discovers Python on each OS. Pure Python; writes to stderr. Works on all platforms." }, { "schema": "https://ai-atoms.com/schemas/hook-v1.json", "type": "hook", "id": "hook/worktree-guard", "version": "1.0.0", "name": "Worktree Placement Guard", "description": "Enforces canonical git worktree placement per Common.md §U17. Denies 'git worktree add' commands that target ad-hoc paths (../branch/, /tmp/, sibling dirs). Canonical paths: /.worktrees// for single-repo work, ~/.ai/worktrees// for cross-repo or persistent worktrees.", "event": "PreToolUse", "language": "python", "trigger": { "type": "tool-name", "pattern": "Bash" }, "blocking": true, "side_effects": [ "blocks non-canonical worktree creation with path guidance" ], "authored_by": "convergent-systems-key", "tags": [ "git", "worktree", "governance", "claude-code" ], "lifecycle": "stable", "platforms": [ "linux", "macos", "windows" ], "platform_notes": "Logic is cross-platform. Wiring: use 'ai hooks run worktree-guard' in settings.json — the ai binary discovers Python on each OS. Inspects git command strings via Python. Path separators handled by pathlib. Works on all platforms." }, { "schema": "https://ai-atoms.com/schemas/skill-v1.json", "type": "skill", "id": "skill/amendment-author", "version": "1.0.0", "name": "Amendment Author", "description": "Guided workflow for authoring and publishing governance amendments against the four canonical files (Constitution, Common, Code, Writing). Walks the full lifecycle: identify the violation or gap, draft the amendment stub, review it against the governance model, apply it to the governance file, and optionally publish it as a versioned amendment atom. Triggers on: /amendment-author, 'author an amendment', 'create an amendment', 'propose a governance change'.", "system_prompt_fragment": "Guide the user through authoring a governance amendment. Step 1 IDENTIFY: ask 'What rule was violated or what gap needs addressing?' Accept a violation file path, free-text description, or override audit log reference. Step 2 LOCATE: find the relevant section in the governance file (Constitution/Common/Code/Writing). Step 3 DRAFT: write the amendment using the strengthen-only rule (amendments may never weaken a parent rule). Step 4 REVIEW: apply the amendment to a local copy and verify no conflicts. Step 5 APPLY: edit the governance file, bump its version, add a changelog entry tagged with the date. Step 6 PUBLISH (optional): create a versioned amendment atom in amendment-atoms. End each step with Did/Next/Blocked/Artifact.", "applicable_domains": [ "governance", "meta", "atoms" ], "invocation_contract": { "inputs": [ { "name": "violation_or_gap", "type": "string", "description": "Violation file path, audit log reference, or free-text description of what needs addressing.", "required": true }, { "name": "target_file", "type": "string", "description": "Which governance file to amend (Constitution/Common/Code/Writing). Inferred if not provided.", "required": false } ], "outputs": [ { "name": "amendment_text", "type": "string", "description": "The drafted amendment text ready to apply." }, { "name": "amended_file", "type": "string", "description": "Path to the updated governance file." } ], "side_effects": [ "edits governance file at ~/.ai/", "optionally creates amendment atom in amendment-atoms catalog" ] }, "authored_by": "convergent-systems-key", "tags": [ "governance", "amendment", "constitution", "meta", "lifecycle" ], "lifecycle": "stable", "invocation": [ "/amendment-author" ] }, { "schema": "https://ai-atoms.com/schemas/skill-v1.json", "type": "skill", "id": "skill/atom-publisher", "version": "1.0.0", "name": "Atom Publisher", "description": "Guided 5-step workflow for drafting, canonicalizing, verifying, and publishing a new atom to the appropriate *-atoms catalog. Supports skill, hook, persona, profile, plugin, amendment, and action atom types. Routes to the correct catalog based on type. Triggers on: /atom-publisher, 'publish an atom', 'create an atom', 'contribute an atom'.", "system_prompt_fragment": "Guide the user through publishing an atom. Step 1 IDENTIFY: ask what type of atom (skill/hook/persona/profile/amendment/plugin/action) and which catalog it belongs to. Step 2 DRAFT: produce the JSON payload conforming to the catalog's atom-v1.json schema. Required fields: schema, type, id, version, name, description. Step 3 CANONICALIZE: run the catalog's build-exports.py to validate the atom against its schema. Fix any errors. Step 4 VERIFY: confirm the atom is reachable at its canonical URL after building. Step 5 PR: open a PR against the catalog repo with the new atom file. End each step with Did/Next/Blocked/Artifact.", "applicable_domains": [ "atoms", "meta", "publishing" ], "invocation_contract": { "inputs": [ { "name": "atom_type", "type": "string", "description": "The class of atom to publish (skill, hook, persona, profile, amendment, etc.).", "required": true }, { "name": "atom_data", "type": "object", "description": "The atom payload fields. Can be partial — the skill will prompt for missing required fields.", "required": false } ], "outputs": [ { "name": "atom_json", "type": "string", "description": "The validated atom JSON ready to commit." }, { "name": "pr_url", "type": "string", "description": "URL of the opened PR against the catalog repo." } ], "side_effects": [ "creates atom JSON file in catalog repo", "opens PR against the catalog's GitHub repo" ] }, "authored_by": "convergent-systems-key", "tags": [ "atoms", "publishing", "meta", "workflow", "catalog" ], "lifecycle": "stable", "invocation": [ "/atom-publisher", "/atom-publisher skill", "/atom-publisher hook", "/atom-publisher persona" ] }, { "schema": "https://ai-atoms.com/schemas/skill-v1.json", "type": "skill", "id": "skill/atom-state", "version": "1.0.0", "name": "Atom Fleet Status", "description": "Full fleet snapshot of all *-atoms.com catalog sites — deploy health, DNS, HTTPS reachability, atom_types per catalog with item counts, schema compliance, /ai/index.json, Terraform backend, sidenav, brand asset uniformity, builder script, federation field, and registry presence. Use when the user asks about the state of the atoms fleet, wants to verify deployments, asks for a fleet snapshot or schema compliance report, or before starting any cross-fleet work.", "system_prompt_fragment": "Run the atom fleet status check. For each *-atoms.com catalog site check: (1) deploy status from latest CI run, (2) DNS resolution (LIVE/NONE/STALE), (3) HTTPS apex response code, (4) /ai/index.json reachability, (5) schema spec_version compliance, (6) Terraform vs Wrangler backend, (7) deploy-after-merge gate, (8) open PR count, (9) Classes/Atoms counts. Report as a table grouped by catalog. Flag: Apex 000 but green deploy (DNS gap), /ai/ unreachable on live site, schema below v1.1.0, wrangler.toml present without Terraform, federation not convergent-systems.co.", "applicable_domains": [ "atoms", "devops", "fleet" ], "invocation_contract": { "inputs": [ { "name": "catalog", "type": "string", "description": "Optional: check a single catalog by name (e.g. brand-atoms). Omit for full fleet.", "required": false } ], "outputs": [ { "name": "fleet_table", "type": "string", "description": "ASCII table showing status of each catalog across all checks." }, { "name": "needs_attention", "type": "array", "description": "List of catalogs with actionable issues." } ], "side_effects": [] }, "authored_by": "convergent-systems-key", "tags": [ "atoms", "fleet", "status", "deploy", "dns", "compliance" ], "lifecycle": "stable", "invocation": [ "/atom-status", "/atom-status tree", "/atom-status tree " ] }, { "schema": "https://ai-atoms.com/schemas/skill-v1.json", "type": "skill", "id": "skill/brainstorming", "version": "1.0.0", "name": "Brainstorm Before Building", "description": "Explore user intent, requirements, and design space before writing any code. Surfaces constraints, alternatives, and tradeoffs. Must run before any creative work — features, components, new functionality, or behavior modifications. Prevents building the wrong thing.", "system_prompt_fragment": "Before writing any code or UI, run a brainstorming session. Ask: (1) What is the user actually trying to accomplish (not just what they asked for)? (2) What constraints exist (performance, compatibility, existing patterns)? (3) What are 2-3 distinct approaches? For each: pros, cons, implementation complexity, reversibility. (4) What could go wrong? (5) What's out of scope? Surface answers before proposing an approach. Let the user redirect before any implementation begins.", "applicable_domains": [ "code", "design", "planning" ], "authored_by": "convergent-systems-key", "tags": [ "brainstorm", "design", "planning", "requirements" ], "lifecycle": "stable" }, { "schema": "https://ai-atoms.com/schemas/skill-v1.json", "type": "skill", "id": "skill/checkpoint", "version": "1.0.0", "name": "Session Checkpoint", "description": "Capture a complete, resumable snapshot of in-flight work to ~/.ai/checkpoints/__/CHECKPOINT.md. Records branch, HEAD SHA, dirty files, active goal, decisions made, files in flight, last green state, next step, open questions, and a verify-on-resume list. Use before /clear, at context limits, or at phase boundaries.", "system_prompt_fragment": "Save a session checkpoint to ~/.ai/checkpoints/__/CHECKPOINT.md. Gather: (1) branch + HEAD SHA, (2) dirty files, (3) active goal from issue/plan, (4) decisions made this session with rationale, (5) files in flight with line ranges, (6) last green test/build command, (7) next step (one imperative sentence), (8) open questions blocking progress, (9) verify-on-resume list of assertions that must be re-checked against live state. MUST NOT contain secrets. Write timestamp file and update CHECKPOINT.md pointer.", "applicable_domains": [ "code", "session", "continuity" ], "authored_by": "convergent-systems-key", "tags": [ "checkpoint", "handoff", "continuity", "session" ], "lifecycle": "stable", "invocation": [ "/checkpoint", "/checkpoint auto", "/checkpoint show", "/checkpoint resume", "/checkpoint resume ", "/checkpoint list" ] }, { "schema": "https://ai-atoms.com/schemas/skill-v1.json", "type": "skill", "id": "skill/debug", "version": "1.0.0", "name": "Debug", "description": "Five-phase systematic debugging (reproduce → isolate → root cause → fix-with-regression-test → verify). Use when the user reports a bug, hits an error or failing test, or wants methodical investigation. Invocable as /debug, /debug \"\", /debug --error , /debug --test .", "system_prompt_fragment": "Debug using five phases — do not skip or reorder. Phase 1 REPRODUCE: if you cannot reproduce, the bug report is the deliverable; do not guess. Phase 2 ISOLATE: narrow to the smallest surface. Phase 3 ROOT CAUSE: name the root cause before proposing any fix. Phase 4 FIX + REGRESSION TEST: write a failing test first, then the minimal fix that makes it green. Phase 5 VERIFY: run the suite and cite the output. After fixing: 'Why was this not caught?' — name the gap. Apply the 3-cycle cap: after three failed attempts with the same approach, stop, name what is not working, propose an alternative, ask before continuing.", "applicable_domains": [ "code", "debug", "testing" ], "invocation_contract": { "inputs": [ { "name": "symptom", "type": "string", "description": "Description of the bug, error message, or unexpected behavior.", "required": true }, { "name": "error_log", "type": "string", "description": "Error log or stack trace (--error mode).", "required": false }, { "name": "test_name", "type": "string", "description": "Name of the failing test (--test mode).", "required": false } ], "outputs": [ { "name": "reproduction", "type": "string", "description": "Confirmed minimal reproduction case." }, { "name": "root_cause", "type": "string", "description": "Named root cause with evidence." }, { "name": "fix", "type": "string", "description": "Minimal fix addressing the root cause." }, { "name": "regression_test", "type": "string", "description": "Test that would have caught this bug." }, { "name": "gap_analysis", "type": "string", "description": "Why this was not caught and what closes the gap." } ], "side_effects": [ "may write files (regression test and fix)" ] }, "authored_by": "convergent-systems-key", "tags": [ "debug", "tdd", "root-cause", "regression", "five-phase" ], "lifecycle": "stable", "invocation": [ "/debug", "/debug \"\"", "/debug --error ", "/debug --test " ] }, { "schema": "https://ai-atoms.com/schemas/skill-v1.json", "type": "skill", "id": "skill/dispatching-parallel-agents", "version": "1.0.0", "name": "Dispatch Parallel Agents", "description": "Decompose a multi-task problem into independent units and dispatch subagents in parallel. Use when facing 2+ independent tasks with no shared state or sequential dependencies. Each agent gets a self-contained prompt with full context.", "system_prompt_fragment": "Decompose the work into independent tasks. For each task: (1) confirm it has no dependency on another task's output, (2) write a self-contained agent prompt with full context (the agent has no memory of this conversation), (3) specify what files to read/write and what to return. Dispatch all independent tasks in a single message as parallel tool calls. Wait for all to complete. Synthesize results — do not just concatenate agent outputs; identify conflicts and inconsistencies. Tasks with dependencies must be serialized; tasks without can be parallelized.", "applicable_domains": [ "code", "agents", "parallelism" ], "authored_by": "convergent-systems-key", "tags": [ "agents", "parallel", "subagent", "dispatch" ], "lifecycle": "stable" }, { "schema": "https://ai-atoms.com/schemas/skill-v1.json", "type": "skill", "id": "skill/hook-author", "version": "1.0.0", "name": "Hook Author", "description": "Guided workflow for authoring and installing governance hooks to the ~/.ai/hooks/ enforcement plane. Covers the full lifecycle: describe the behavior → write the script → validate → install → test. Supported events: PreToolUse, PostToolUse, Stop, SubagentStop, PreCompact, UserPromptSubmit. Triggers on: /hook-author, 'author a hook', 'create a hook', 'write a governance hook'.", "system_prompt_fragment": "Guide the user through authoring a governance hook. Step 1 DESCRIBE: ask what behavior the hook should enforce. Which event (PreToolUse/PostToolUse/Stop/etc.)? Blocking or non-blocking? What trigger pattern? Step 2 WRITE: implement the hook in Python following the _lib.py conventions in ~/.ai/hooks/. For blocking hooks: emit JSON {hookSpecificOutput: {permissionDecision: 'deny', permissionDecisionReason: '...'}}. For non-blocking: emit modified payload or nothing. Always exit 0. Step 3 VALIDATE: run --self-check to verify the hook loads without errors. Step 4 INSTALL: add to ~/.claude/settings.json hooks array. Step 5 TEST: trigger the hook manually and verify it behaves correctly. Also publish as a hook atom to ai-atoms. End each step with Did/Next/Blocked/Artifact.", "applicable_domains": [ "governance", "meta", "hooks", "claude-code" ], "invocation_contract": { "inputs": [ { "name": "behavior_description", "type": "string", "description": "What the hook should enforce or observe.", "required": true }, { "name": "event", "type": "string", "description": "The Claude Code event to hook into (PreToolUse, PostToolUse, Stop, etc.).", "required": false }, { "name": "blocking", "type": "boolean", "description": "Whether the hook should block execution on violation.", "required": false } ], "outputs": [ { "name": "hook_script", "type": "string", "description": "The Python hook script ready to install at ~/.ai/hooks/." }, { "name": "settings_entry", "type": "object", "description": "The settings.json hooks entry to wire the hook." } ], "side_effects": [ "writes Python script to ~/.ai/hooks/", "edits ~/.claude/settings.json to wire the hook" ] }, "authored_by": "convergent-systems-key", "tags": [ "governance", "hooks", "meta", "lifecycle", "claude-code" ], "lifecycle": "stable", "invocation": [ "/hook-author" ] }, { "schema": "https://ai-atoms.com/schemas/skill-v1.json", "type": "skill", "id": "skill/make-atoms", "version": "1.0.0", "name": "Make Atoms", "description": "Discover, fetch, or scaffold skill atoms via the atoms-discover skill. Routes to the atoms binary for ecosystem operations: finding atoms in convergent-systems-co catalogs, fetching atom JSON schemas, scaffolding new atom files, or checking whether an atom exists for a given capability.", "system_prompt_fragment": "Delegate to the atoms-discover skill for all atom ecosystem operations. For discovery: fetch the catalog from the relevant *-atoms.com/ai/index.json and search by type or name. For scaffolding: generate a compliant atom JSON using the catalog's schema. For checking: look up the atom at its canonical URL. Use the atoms binary (ai atoms ...) when available. Never confuse atom management with the ai CLI or ~/.ai/ directory.", "invocation": [ "/make atoms", "/make atoms discover", "/make atoms fetch ", "/make atoms scaffold " ], "applicable_domains": [ "atoms", "meta" ], "invocation_contract": { "inputs": [ { "name": "subcommand", "type": "string", "description": "discover | fetch | scaffold", "required": false }, { "name": "target", "type": "string", "description": "Atom slug or type for fetch/scaffold.", "required": false } ], "outputs": [ { "name": "result", "type": "string", "description": "Atom data, catalog listing, or scaffolded JSON." } ], "side_effects": [ "may write new atom JSON file when scaffolding" ] }, "tags": [ "atoms", "meta", "discovery", "scaffolding" ], "authored_by": "convergent-systems-key", "lifecycle": "stable" }, { "schema": "https://ai-atoms.com/schemas/skill-v1.json", "type": "skill", "id": "skill/make-build", "version": "1.0.0", "name": "Make Build", "description": "Commit staged changes, push the current branch, open a pull request, and merge after CI passes. Never pushes to main directly. Never squash-merges on non-release branches.", "system_prompt_fragment": "Run the build pipeline: (1) Stage and commit any uncommitted changes using Conventional Commits. (2) Push the branch to origin. (3) Open a GitHub PR with body generated from the branch commit log including 'Closes #' links for any issues referenced. (4) Wait for CI to pass. (5) Merge with a merge commit — no squash on non-release branches. Report: PR URL, CI status, merge SHA.", "invocation": [ "/make build" ], "applicable_domains": [ "code", "git", "delivery" ], "invocation_contract": { "inputs": [], "outputs": [ { "name": "pr_url", "type": "string", "description": "URL of the opened PR." }, { "name": "merge_sha", "type": "string", "description": "SHA of the merge commit after CI passes." } ], "side_effects": [ "commits to current branch", "pushes to origin", "opens PR", "merges PR after CI" ] }, "tags": [ "git", "pr", "ci", "merge", "delivery" ], "authored_by": "convergent-systems-key", "lifecycle": "stable" }, { "schema": "https://ai-atoms.com/schemas/skill-v1.json", "type": "skill", "id": "skill/make-doctor", "version": "1.0.0", "name": "Make Doctor", "description": "Health check for the AI governance stack and per-repo CI. Runs 'ai doctor', checks hook permissions, verifies CLAUDE.md constitution includes, confirms ~/.ai/memory/ and audit/ exist, and reports CI status on open PRs. Read-only unless --fix is explicitly requested.", "system_prompt_fragment": "Run the doctor pipeline: (1) Run 'ai doctor' and surface warnings or failures. (2) Verify hook files in ~/.ai/hooks/ are executable (0755). (3) Check ~/.claude/CLAUDE.md contains @~/.ai/Constitution.md (not stale four-file includes). (4) Verify ~/.ai/memory/ and ~/.ai/audit/ directories exist. (5) Check CI status on all open PRs in the current repo. Report each check as PASS/WARN/FAIL with remediation steps. Read-only except when --fix is explicitly requested.", "invocation": [ "/make doctor", "/make doctor --fix" ], "applicable_domains": [ "governance", "code", "devops" ], "invocation_contract": { "inputs": [ { "name": "fix", "type": "boolean", "description": "If true, auto-remediate WARN findings where safe to do so.", "required": false } ], "outputs": [ { "name": "health_report", "type": "string", "description": "Per-check PASS/WARN/FAIL report with remediation steps." } ], "side_effects": [ "may fix hook permissions and CLAUDE.md includes when --fix is passed" ] }, "tags": [ "governance", "health", "hooks", "audit", "ci" ], "authored_by": "convergent-systems-key", "lifecycle": "stable" }, { "schema": "https://ai-atoms.com/schemas/skill-v1.json", "type": "skill", "id": "skill/make-review", "version": "1.0.0", "name": "Make Review", "description": "Adversarial code reviewer sweep on the current branch diff against main. Hunts for stubs, placeholders, dead imports, unwired exports, and TODO/FIXME in production paths. Returns HIGH/MEDIUM/LOW findings with file:line citations. HIGH blocks merge.", "system_prompt_fragment": "Run the code reviewer sweep on the current branch diff (git diff main...HEAD --name-only). Hunt for: stubs (panic/not-implemented/empty bodies) — HIGH; placeholder values (REPLACE_ME, ) — HIGH; TODO/FIXME in non-test production files — MEDIUM; unwired exports (zero non-test callers) — MEDIUM; dead imports — LOW; commented-out code blocks — LOW. Every MEDIUM or HIGH finding MUST include a file:line citation and a quoted code snippet. Return verdict: PASS | WARN | BLOCK.", "invocation": [ "/make review" ], "applicable_domains": [ "code", "review" ], "invocation_contract": { "inputs": [], "outputs": [ { "name": "findings", "type": "array", "description": "List of severity-tagged findings with file:line citations." }, { "name": "verdict", "type": "string", "description": "PASS | WARN | BLOCK" } ], "side_effects": [] }, "tags": [ "review", "code-quality", "stubs", "adversarial" ], "authored_by": "convergent-systems-key", "lifecycle": "stable" }, { "schema": "https://ai-atoms.com/schemas/skill-v1.json", "type": "skill", "id": "skill/make-status", "version": "1.0.0", "name": "Make Status", "description": "Sprint status snapshot: open PRs and their CI state, stale branches, sync gap between local and origin, and any uncommitted work. Read-only — does not modify any files.", "system_prompt_fragment": "Report sprint status across the repo set. (1) List all open PRs with CI status (green/red/pending) and draft state. (2) List local branches ahead of main with commit counts. (3) Show the sync gap — commits on origin/main not yet in local main. (4) Show uncommitted changes and stale worktrees. Format as a status board: Done / In-flight / Blocked / Next-up. Read-only.", "invocation": [ "/make status" ], "applicable_domains": [ "code", "git", "project" ], "invocation_contract": { "inputs": [], "outputs": [ { "name": "status_board", "type": "string", "description": "ASCII status board showing PRs, branches, and uncommitted work." } ], "side_effects": [] }, "tags": [ "status", "sprint", "git", "ci", "read-only" ], "authored_by": "convergent-systems-key", "lifecycle": "stable" }, { "schema": "https://ai-atoms.com/schemas/skill-v1.json", "type": "skill", "id": "skill/make-sync", "version": "1.0.0", "name": "Make Sync", "description": "Pull all repos in the workspace (primary + submodules) to their default branch heads. Fast-forward only — never rebases, never force-pulls, never touches non-default branches. Reports any repos where fast-forward failed due to divergence.", "system_prompt_fragment": "Sync all repos to their remote default branch. (1) Discover primary repo and all git submodules. (2) For each repo: git fetch --prune, then pull the default branch (main/master) with --ff-only. (3) Report any repos where --ff-only failed (diverged) without force-pulling. (4) Update submodule pointers in the parent repo if any changed. Never rebase, never force-pull, never touch non-default branches.", "invocation": [ "/make sync" ], "applicable_domains": [ "code", "git" ], "invocation_contract": { "inputs": [], "outputs": [ { "name": "sync_report", "type": "string", "description": "List of repos synced successfully and any that diverged." } ], "side_effects": [ "pulls default branch on all repos", "updates submodule pointers" ] }, "tags": [ "git", "sync", "submodules", "pull" ], "authored_by": "convergent-systems-key", "lifecycle": "stable" }, { "schema": "https://ai-atoms.com/schemas/skill-v1.json", "type": "skill", "id": "skill/make", "version": "1.0.0", "name": "Make — Unified Dispatcher", "description": "Dispatcher for the make skill suite. Reads the subcommand and invokes the matching skill immediately. Subcommands: work/sprint (PM + delivery team), clean (purge merged branches), build (commit+push+PR+merge), test (run test suite), status (sprint snapshot), sync (pull all repos), review (code reviewer sweep), doctor (governance health check), atoms (atom ecosystem ops).", "system_prompt_fragment": "Read the first word after /make and dispatch to the matching skill immediately. Do not summarize, plan, or ask clarifying questions — just dispatch.\n\nDispatch table:\n work / sprint → make-work\n clean → make-clean\n build → make-build\n test → make-test\n status → make-status\n sync → make-sync\n review → make-review\n doctor → make-doctor\n atoms → make-atoms\n\nIf the subcommand is unknown or missing, print the usage table and stop.", "invocation": [ "/make work", "/make sprint", "/make clean", "/make build", "/make test", "/make status", "/make sync", "/make review", "/make doctor", "/make atoms" ], "applicable_domains": [ "code", "delivery", "git", "project" ], "tags": [ "make", "dispatcher", "delivery", "workflow" ], "authored_by": "convergent-systems-key", "lifecycle": "stable" }, { "schema": "https://ai-atoms.com/schemas/skill-v1.json", "type": "skill", "id": "skill/memory-curator", "version": "1.0.0", "name": "Memory Curator", "description": "Guided workflow for reviewing, curating, and archiving AI memory entries at ~/.ai/memory/. Identifies stale entries, spots patterns that warrant governance amendments, and archives obsolete memories. Triggers on: /memory-curator, 'curate memory', 'review memory', 'clean up memory', 'audit my memories'.", "system_prompt_fragment": "Curate the memory store at ~/.ai/memory/. Step 1 INVENTORY: run 'ai memory list' and group by type (user, feedback, project, reference). Report total counts. Step 2 REVIEW: for each memory, check: is it still accurate? Is it still relevant? Is it duplicated? Does it contain secrets (violates Common.md §4)? Step 3 IDENTIFY STALE: flag memories older than 90 days for project/reference types; flag feedback memories that contradict current observed behavior. Step 4 IDENTIFY PATTERNS: if 3+ overrides or violations share a root cause, propose a governance amendment. Step 5 CURATE: archive stale entries (move to ~/.ai/memory/archive/), remove duplicates, add missing entries. End each step with Did/Next/Blocked/Artifact.", "applicable_domains": [ "meta", "governance", "memory" ], "invocation_contract": { "inputs": [ { "name": "filter_type", "type": "string", "description": "Optional: filter to a specific memory type (user/feedback/project/reference).", "required": false } ], "outputs": [ { "name": "inventory", "type": "string", "description": "Summary of memory entries by type with counts." }, { "name": "stale_list", "type": "array", "description": "Memory entries flagged for archiving." }, { "name": "amendment_proposals", "type": "array", "description": "Governance amendments warranted by patterns found." } ], "side_effects": [ "may archive memory files to ~/.ai/memory/archive/", "may remove duplicate memory files" ] }, "authored_by": "convergent-systems-key", "tags": [ "memory", "governance", "meta", "curation", "maintenance" ], "lifecycle": "stable", "invocation": [ "/memory-curator" ] }, { "schema": "https://ai-atoms.com/schemas/skill-v1.json", "type": "skill", "id": "skill/review-panel", "version": "1.0.0", "name": "Review Panel", "description": "Guided multi-panel review workflow. Selects review perspectives, runs each pass, aggregates scores, and writes a structured report artifact. Use when you need more than a single-pass review: governance files, PRs, prose drafts, or any artifact that benefits from multiple independent evaluation perspectives (architecture, correctness, documentation quality, adversarial edge cases, security).", "system_prompt_fragment": "Run a multi-panel review. Step 1 SELECT TARGET: confirm the artifact — a PR diff, a file path, or a governance document. Step 2 SELECT PANELS: choose 2-5 review perspectives appropriate to the artifact (e.g. architecture, security, correctness, documentation, adversarial). Step 3 RUN PASSES: for each panel, run an independent review pass and collect findings. Each finding must cite file:line evidence. Step 4 AGGREGATE: compile findings across panels, remove duplicates, rank by severity (HIGH blocks, MEDIUM warns, LOW informs). Step 5 REPORT: write a structured report artifact with panel summaries, consolidated findings table, and verdict (PASS/WARN/BLOCK).", "applicable_domains": [ "code", "governance", "review" ], "invocation_contract": { "inputs": [ { "name": "target", "type": "string", "description": "PR number, file path, or governance document to review.", "required": true }, { "name": "panels", "type": "array", "description": "Optional list of review perspectives. Defaults to [architecture, correctness, security, documentation].", "required": false } ], "outputs": [ { "name": "report", "type": "string", "description": "Structured review report with panel summaries and consolidated findings." }, { "name": "verdict", "type": "string", "description": "PASS | WARN | BLOCK" } ], "side_effects": [ "writes review report artifact to .artifacts/reviews/" ] }, "authored_by": "convergent-systems-key", "tags": [ "review", "multi-panel", "governance", "quality", "adversarial" ], "lifecycle": "stable", "invocation": [ "/review-panel", "/review-panel --pr=", "/review-panel " ] }, { "schema": "https://ai-atoms.com/schemas/skill-v1.json", "type": "skill", "id": "skill/systematic-debugging", "version": "1.0.0", "name": "Systematic Debugging", "description": "Five-phase debugging protocol: reproduce → isolate → root cause → fix with regression test → verify. Use when encountering any bug, test failure, or unexpected behavior. Never proposes a fix before root cause is confirmed. Enforces the 3-cycle local cap and 5-cycle total cap to prevent thrashing.", "system_prompt_fragment": "Debug using five phases in order — no skipping. Phase 1 REPRODUCE: establish a reliable reproduction; if you cannot, the bug report is the deliverable. Phase 2 ISOLATE: narrow to the smallest surface. Phase 3 ROOT CAUSE: name the root cause explicitly before proposing any fix. Phase 4 FIX + REGRESSION TEST: write a failing test first, then the minimal fix. Phase 5 VERIFY: run the suite and cite the output. After fixing: 'Why was this not caught?' — name the gap. Cap: after 3 failed attempts with the same approach, stop and propose an alternative. After 5 total attempts, escalate.", "applicable_domains": [ "code", "debug" ], "authored_by": "convergent-systems-key", "tags": [ "debug", "root-cause", "tdd", "regression" ], "lifecycle": "stable" }, { "schema": "https://ai-atoms.com/schemas/skill-v1.json", "type": "skill", "id": "skill/verification-before-completion", "version": "1.0.0", "name": "Verify Before Claiming Done", "description": "Run verification commands and confirm output before claiming any work is complete, fixed, or passing. Evidence before assertions always. Use before committing, opening PRs, or reporting success. Never cite your own reasoning as proof.", "system_prompt_fragment": "Before claiming work is complete: (1) Run the relevant verification command (test suite, build, type-check, lint). (2) Cite the actual output — not a summary, the output. (3) For 'tests pass': cite the test runner output with pass count. (4) For 'build succeeds': cite the build tool output and exit code. (5) For 'fix works': run it and cite the run. If you cannot produce the independent source, downgrade the claim to 'I believe X but did not verify' and surface the gap.", "applicable_domains": [ "code", "testing", "quality" ], "authored_by": "convergent-systems-key", "tags": [ "verification", "testing", "evidence", "ci" ], "lifecycle": "stable" } ], "compositions": [], "rules": [] }