ai-literacy-superpowers

Run an AI literacy assessment — scan the repo for evidence, ask clarifying questions, produce a timestamped assessment document, apply immediate habitat fixes, recommend workflow changes, capture a reflection, and add a literacy level badge to the README

Run the Choice Cartographer (decision-archaeology agent) on a spec — produces the choice-story record at docs/superpowers/stories/<slug>.md; use after spec-mode /diaboli dispositions are resolved, before plan approval

Sync HARNESS.md conventions to Cursor, Copilot, and Windsurf convention files

Capture AI tool cost data — guide through provider dashboards, record spend and token usage, compare to previous snapshot, update MODEL_ROUTING.md

Run the adversarial reviewer on a spec or implementation — produces the objection record at docs/superpowers/objections/<slug>.md (spec mode) or <slug>-code.md (code mode); use after spec-writer completes or after the final code-reviewer PASS

Run a guided convention extraction session — surfaces tacit team knowledge through structured questions and maps answers to CLAUDE.md conventions and HARNESS.md constraints

Run a deep governance investigation — semantic drift analysis, governance debt inventory, constraint falsifiability scoring, three-frame alignment checks, and governance health reporting

Guided authoring of governance constraints — translates governance language into operational meaning with three-frame alignment check, then writes the constraint to HARNESS.md

Show governance health snapshot — constraint count, falsifiability ratio, drift score, debt inventory, last audit date. Pass --dashboard to generate the HTML governance dashboard.

Manage the project's affordance inventory — declared tools the agent can invoke, the identity each tool runs under, and the audit trail each tool produces. Subcommands - discover (scan config to produce a draft inventory), add (planned), review (planned). See docs/superpowers/specs/2026-04-26-harness-affordances-design.md for the design.

Run a full meta-verification of the harness — check whether HARNESS.md matches reality and update the status

Add a new constraint to HARNESS.md or promote an existing one from unverified to agent or deterministic

Manage and run garbage collection rules — add new periodic checks or run existing ones on demand

Generate a harness health snapshot — enforcement status, mutation trends, learning velocity, cadence compliance, and meta-observability checks

Set up a living harness for this project — select features, discover the stack, define conventions, generate HARNESS.md with enforcement. Re-run to add features incrementally.

Generate a human-readable onboarding document from HARNESS.md, AGENTS.md, and REFLECTION_LOG.md — a friendly guide for new team members

Show the current health of the project's harness — enforcement ratio, drift, and garbage collection state

Detect drift across all push-direction control surfaces, present the full picture, and apply the user's selected fixes via the existing primitives — single human-instigated entry point for keeping convention files in sync with HARNESS.md. ONBOARDING.md staleness is surfaced but not auto-fixed; users run /harness-onboarding deliberately when they want it regenerated.

Discover and adopt new template content after a plugin upgrade — diffs your HARNESS.md against the current template and presents new items for review

Verify that all data signals the Habitat Observatory expects are present and correctly formatted — runs the 82-signal checklist against the latest output files

Assess AI literacy across multiple repositories — aggregate assessments into a portfolio view with level distribution, shared gaps, and prioritised improvements

Capture a reflection after completing work — what was surprising, what should future agents know, what could improve

Set up the complete AI Literacy framework habitat for this project — discover the stack, define conventions, scaffold harness, agent team, compound learning, and CI templates

Show the complete health of the project's AI Literacy habitat — harness enforcement, agent team, compound learning, model routing, and CI status

Manage git worktrees for parallel agent isolation — spin up a new worktree, merge it back, or clean it up

Use after spec-writer completes (spec mode) or after the final code-reviewer PASS (code mode) — reads the spec or implementation and produces a structured objection record; read-only trust boundary enforces the human-cognition gate on dispositions at both gates

Use this agent to run an AI literacy assessment — scans the repository for observable evidence, asks clarifying questions, and produces a timestamped assessment document with a README badge. Examples: <example> Context: User wants to know their team's AI literacy level user: "Where are we on the AI literacy framework?" assistant: "I'll use the assessor agent to run a full assessment." <commentary> The assessor scans the repo, asks clarifying questions, and produces an evidence-based level assessment. </commentary> </example> <example> Context: User runs /assess command user: "/assess" assistant: "Starting the AI literacy assessment." <commentary> The /assess command dispatches the assessor agent. </commentary> </example>

Use after spec-mode advocatus-diaboli dispositions are resolved and before plan approval — reads the spec, reconstructs the decisions it implies (including the silent ones), and produces a structured choice-story record; read-only trust boundary enforces the human-cognition gate on dispositions

Use after implementation is complete and tests are green — reviews code through the CUPID and literate programming lenses, returns PASS or a prioritised list of findings

Use this agent when conducting a deep governance investigation — semantic drift analysis, governance debt inventory, constraint falsifiability scoring, three-frame alignment checks, or governance health reporting. Examples: <example> Context: User runs /governance-audit user: "/governance-audit" assistant: "I'll use the governance-auditor to conduct a deep governance investigation." <commentary> The governance-auditor owns the full audit methodology — drift detection, debt inventory, frame alignment. </commentary> </example> <example> Context: User suspects governance constraints have drifted user: "Our governance constraints feel out of date — the team works differently now" assistant: "I'll use the governance-auditor to check for semantic drift and governance debt." <commentary> Semantic drift is the governance-auditor's primary detection target. </commentary> </example> <example> Context: Quarterly governance review user: "Time for the quarterly governance audit" assistant: "I'll dispatch the governance-auditor for a full governance deep-dive." <commentary> Quarterly audit is the governance-auditor's primary scheduled cadence. </commentary> </example>

Use this agent when verifying the health of the harness itself — checking whether declared enforcement in HARNESS.md matches what actually exists in the project. Examples: <example> Context: User runs /harness-audit user: "/harness-audit" assistant: "I'll use the harness-auditor to check whether the harness matches reality." <commentary> The auditor is the meta-agent that keeps HARNESS.md honest. </commentary> </example> <example> Context: Scheduled weekly harness health check user: "Check the harness for drift" assistant: "I'll use the harness-auditor to compare declared vs actual enforcement." <commentary> Periodic auditing prevents HARNESS.md from becoming documentation that lies. </commentary> </example>

Use this agent when scanning a project to discover its tech stack, existing linters, CI configuration, test frameworks, and pre-commit hooks. Examples: <example> Context: User is running /harness-init on a new project user: "/harness-init" assistant: "I'll use the harness-discoverer agent to scan the project before asking about conventions." <commentary> The init command needs a factual baseline of what exists before it can generate HARNESS.md. </commentary> </example> <example> Context: User is adding a new constraint and wants to know what tools are available user: "/harness-constrain" assistant: "Let me scan the project for deterministic tools that could enforce this." <commentary> The constrain command needs to know what linters and formatters are already installed. </commentary> </example>

Use this agent when verifying constraints from HARNESS.md against code — running deterministic tools or performing agent-based reviews. Examples: <example> Context: CI needs to check PR constraints user: "Run the harness constraint checks on this PR" assistant: "I'll use the harness-enforcer agent to verify all PR-scoped constraints from HARNESS.md." <commentary> The enforcer runs both deterministic and agent-based checks through a unified interface. </commentary> </example> <example> Context: User just added a new constraint via /harness-constrain user: "Test this constraint to make sure it works" assistant: "I'll use the harness-enforcer to do a test run of the new constraint." <commentary> Test runs confirm a constraint catches violations before it goes live. </commentary> </example>

Use this agent when running garbage collection checks from HARNESS.md — periodic entropy-fighting sweeps for documentation staleness, dead code, convention drift, and dependency currency. Examples: <example> Context: Weekly scheduled garbage collection run user: "Run the weekly garbage collection checks" assistant: "I'll use the harness-gc agent to run all GC rules from HARNESS.md." <commentary> Scheduled GC fights the slow entropy that PR gates miss. </commentary> </example> <example> Context: User wants to check for stale documentation user: "/harness-gc" assistant: "I'll run the garbage collection checks on demand." <commentary> Manual GC lets users sweep for entropy whenever they choose. </commentary> </example>

Use when implementation and code review are complete — updates CHANGELOG, commits all changes, opens a PR, watches CI, merges when green, closes the linked issue, and prunes the local branch

Use when starting any new feature, fix, improvement, or refactoring task — receives a plain-English task description and coordinates the full pipeline from spec update through to merged PR and closed issue

Use when a feature, behaviour change, or improvement needs to be captured in a spec before implementation begins — updates spec and plan files so the project's spec-first discipline is upheld

Use after spec-writer has updated the spec and plan, and the user has approved the plan — writes failing tests that express the new acceptance scenarios, then confirms they are red before any implementation is written

Use when acting as the adversarial spec reviewer — raises steel-manned objections across six categories before plan approval, requires evidence per objection, and discloses what was not challenged

This skill should be used when the user asks to "assess AI literacy", "run an assessment", "check literacy level", "evaluate our AI collaboration", "where are we on the framework", or wants to determine their team's AI literacy level using the ALCI instrument.

Use when setting up automatic PR constraint enforcement via GitHub Actions — covers the advisory-vs-blocking split, workflow installation, configuration options, and reading the output

Use when acting as the decision-archaeology agent — surfaces decisions a spec has made (including the silent ones), emits each material choice as a Henney-style pattern story for human disposition, and pays down intent debt before plan approval

This skill should be used when the user asks to "add a constraint", "design a constraint", "write a harness rule", "choose enforcement type", "promote a constraint", "configure a verification slot", or needs guidance on the Constraints section of HARNESS.md.

This skill should be used when the user asks about "writing conventions", "codebase context", "HARNESS.md context section", "convention documentation", "how to write enforceable rules", or needs guidance on the Context section of HARNESS.md.

Use when setting up a new project's conventions, onboarding AI to an existing codebase, after team composition changes, or when AI output quality varies depending on who prompts — guides structured discovery of tacit team knowledge into explicit, enforceable artefacts

Use when syncing HARNESS.md conventions to Cursor, Copilot, and Windsurf convention files — reads Context and Constraints sections and generates tool-specific output so all AI coding tools share the same project rules

Use when the user wants to capture AI tool costs, review spending trends, set cost budgets, or integrate cost data into health snapshots — guides quarterly cost capture, records data in a structured format, and updates MODEL_ROUTING.md with observed cost patterns

Use when coordinating changes across multiple repositories — syncing skills, templates, agents, or harness policies between upstream and downstream repos, or designing portfolio-level agent orchestration

Use when reviewing or refactoring code and wanting a structured lens beyond SOLID — applies Daniel Terhorst-North's CUPID properties to surface improvement opportunities in any codebase or language.

Use when auditing project dependencies for known vulnerabilities, supply chain risk, or provenance issues — covers Go modules, Maven/JVM, and CI integration for automated scanning

Use when auditing Docker images in this project for CVEs, base image staleness, or remediation recommendations — covers all four TUI images (Go, Python, Kotlin, C#)

Use when designing architectural fitness functions as GC rules — periodic checks that verify system-wide properties like layer boundaries, coupling trends, and complexity hotspots, complementing per-change constraints with weekly architectural health monitoring

This skill should be used when the user asks about "garbage collection rules", "entropy fighting", "documentation staleness", "dead code detection", "convention drift", "periodic checks", "auto-fix rules", or needs guidance on the Garbage Collection section of HARNESS.md.

Use when reviewing GitHub Actions workflow files for security issues, hardening CI pipelines, or assessing supply chain risk in a repository that uses GitHub Actions

Use when conducting a governance audit — detecting semantic drift in governance constraints, inventorying governance debt, checking three-frame alignment, or when the governance-auditor agent needs methodology for deep investigation.

Use when writing governance constraints for HARNESS.md, translating governance language into operational meaning, reviewing existing governance constraints for falsifiability, or when "/governance-constrain" needs guidance on the authoring workflow.

Use when defining governance metrics, reading governance health snapshots, generating the governance dashboard, or understanding the governance data model. Referenced by the governance-auditor agent and the /governance-health command.

Use when running the shared drift-detection logic that backs /harness-audit and /harness-sync — produces a structured drift report covering convention files, ONBOARDING.md, snapshot staleness, template drift, constraint regressions, recurring reflection patterns, and HARNESS.md Status section accuracy.

This skill should be used when the user asks about "harness engineering", "what is a harness", "harness framework", "AI code quality", "context engineering", "architectural constraints", "garbage collection for code", or wants to understand the conceptual foundation behind the harness-engineering plugin.

Use when checking harness health, setting up observability cadences, understanding snapshot formats, configuring telemetry export, or verifying that the harness's own observability is working — covers all four layers of harness observability

Use when generating a human-readable onboarding document from HARNESS.md, AGENTS.md, and REFLECTION_LOG.md — produces a friendly guide for new team members joining a harnessed project

Use when generating a prioritised improvement plan after an AI literacy assessment, or when a user knows their current level and wants to know what to do next — maps gaps to specific plugin commands and skills, grouped by target level, with accept/skip/defer for each item

Use when creating new source files, writing new functions or types, or significantly rewriting existing code — ensures code is structured for humans to read first, with narrative preambles, reasoning-based documentation, and presentation ordered by understanding rather than compiler convention

This skill should be used when the user asks about "local models", "custom models", "fine-tuning", "self-hosting models", "model selection", "which model should I use", "data privacy and models", "LoRA", "RAG vs fine-tuning", "Ollama", "vLLM", or wants guidance on whether to build, host, or customise their own AI models.

Use when assessing AI literacy across multiple repositories — aggregates individual assessments into a portfolio view with level distribution, shared gaps, outliers, and a prioritised improvement plan grouped by organisational impact. Discovers repos from local paths, GitHub orgs, or topic tags.

Use when the user wants to generate, update, or customise an HTML dashboard from portfolio assessment data — produces a self-contained HTML file with level distribution, repo table, shared gaps, improvement plan, and trend visualisation from multiple quarterly assessments

Use when auditing a project for secrets committed to source control, setting up gitleaks, or hardening the "No secrets in source" harness constraint — covers scanning, baselining, configuration, and CI integration

Use when the user wants to create or update a Team Topologies Team API document with AI literacy portfolio assessment data — generates a template Team API with literacy levels, discipline scores, shared gaps, and improvement plans, or updates an existing Team API with the latest assessment data

This skill should be used when the user asks about "verification slots", "integrating a linter", "adding a deterministic tool", "harness-enforcer", "constraint enforcement interface", "wrapping a tool", or needs the technical reference for how deterministic and agent-based checks work in the harness framework.

11 hooks across 3 events