Skip to content
Back to search

ai-literacy-superpowers

A set of Claude Code and GitHub Copilot plugins providing the AI Literacy framework's complete development workflow — harness engineering, agent orchestration, literate programming, CUPID code review, and the three enforcement loops

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/Habitat-Thinking/ai-literacy-superpowers with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/Habitat-Thinking/ai-literacy-superpowers'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/habitat-thinking--ai-literacy-superpowers/badge.svg)](/listings/habitat-thinking--ai-literacy-superpowers)

HTML

<a href="/listings/habitat-thinking--ai-literacy-superpowers"><img src="/api/listings/habitat-thinking--ai-literacy-superpowers/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

1. Add the marketplace (once)

# Claude Code
claude plugin marketplace add Habitat-Thinking/ai-literacy-superpowers

# GitHub Copilot CLI
copilot plugin marketplace add Habitat-Thinking/ai-literacy-superpowers

2. Install the plugin(s) you want

# Claude Code
claude plugin install ai-literacy-superpowers     # the flagship
claude plugin install model-cards                  # the sister

# GitHub Copilot CLI
copilot plugin install ai-literacy-superpowers@ai-literacy-superpowers
copilot plugin install model-cards@ai-literacy-superpowers

You can install one, the other, or both. Once installed, each plugin's skills, agents, hooks, and commands (or prompts) are available in any session within your project.

> Commands are available as `/command-name` in Claude Code and as `/prompt-name` in Copilot CLI.

Updating

Check if an update is available

New template content is found by running `/harness-upgrade`, which compares your harness against the plugin's template directly. Nothing nudges you automatically: the marker that used to drive a session-start nudge tracked the plugin version rather than template content, so it fired on every release whether or not the template had changed.

- **Manual check** — compare installed vs latest at any time:

claude plugin list

Update the plugin

When a new version is released, update your local installation:

# Claude Code
claude plugin update ai-literacy-superpowers@ai-literacy-superpowers

# Copilot CLI
/plugin update ai-literacy-superpowers

Check the [CHANGELOG](CHANGELOG.md) for what changed between versions.

After updating, run `/harness-upgrade` to review and adopt any new template content (constraints, GC rules, optional blocks) into your HARNESS.md.

Update the marketplace listing

If you maintain your own marketplace that includes this plugin, refresh the index so new versions are discoverable:

claude plugin marketplace update Habitat-Thinking/ai-literacy-superpowers

This pulls the latest `plugin.json` metadata (version, description, keywords) into the marketplace index. Users who have already installed the plugin still need to run `claude plugin update` separately.

See [How to Update the Plugin](docs/plugins/ai-literacy-superpowers/update-the-plugin.md) for the full guide.

Quick start

After installation, run these commands to set up your project:

# Full habitat setup (recommended for new projects)
/superpowers-init

# Harness-only setup (if you want constraints without the agent pipeline)
/harness-init

# Check the status of your harness
/harness-status

# Run a health check
/harness-health

# Run an AI literacy assessment
/assess

**`/superpowers-init`** sets up the complete habitat: CLAUDE.md, HARNESS.md, AGENTS.md, MODEL_ROUTING.md, REFLECTION_LOG.md, the full agent team, skills, hooks, and CI workflow templates. Use this for new projects.

**`/harness-init`** sets up only the harness: HARNESS.md with starter constraints and GC rules. Use this if you want the constraint and enforcement machinery without the full agent pipeline.

Changing a harness rule

Setting a harness up is the easy half. **Once it exists, this is how it changes:**

/reflect → a human reads the reflections → HARNESS.md → /harness-sync

`HARNESS.md` is the master and it is human-curated. `/reflect` captures what was noticed and routes it by signal type; a human reviews the corpus, with agentic support, and decides what is worth writing down. `/harness-sync` then brings the convention files for Cursor, Copilot and Windsurf into line.

`/harness-constrain` helps author a constraint. `/harness-audit` checks whether what `HARNESS.md` declares still matches reality. Git history is the record of what changed and why.

Tool Compatibility

This plugin works with both Claude Code and GitHub Copilot CLI from the same repository. The formats have converged:

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 33 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. {
  2. "name": "ai-literacy-superpowers",
  3. "owner": {
  4. "name": "Russ Miles"
  5. },
  6. "version": "0.4.0",
  7. "plugin_version": "0.92.0",
  8. "description": "Marketplace listing for the ai-literacy-superpowers Copilot plugin — provides easy install and canonical plugin metadata.",
  9. "repository": {
  10. "type": "git",
  11. "url": "https://github.com/Habitat-Thinking/ai-literacy-superpowers"
  12. },
  13. "plugins": [
  14. {
  15. "name": "ai-literacy-superpowers",
  16. "source": "./ai-literacy-superpowers",
  17. "description": "The AI Literacy framework's complete development workflow — harness engineering, agent orchestration, literate programming, CUPID code review, compound learning, and the three enforcement loops",
  18. "version": "0.92.0"
  19. },
  20. {
  21. "name": "model-cards",
  22. "source": "./model-cards",
  23. "description": "Researches and authors Mitchell-extended model cards from a model name.",
  24. "version": "0.1.0"
  25. },
  26. {
  27. "name": "diagnostic-legibility",
  28. "source": "./diagnostic-legibility",
  29. "description": "Agents accountable for helping to maintain human understanding. Ships the `diagnostic-legibility` agent — builds and self-challenges two models of a codebase scope (architectural moving parts and domain concepts) via a five-question retained-challenge cycle, then cross-checks the two collections against each other via a five-question per-direction cycle. The `/diagnose` command surfaces the mutually-corrected models on demand as a readable report. The `ConceptualPipelineMap` template adds a standalone, presentation-agnostic flow-perspective data model; the agent's `scope-resolution` mode answers 'what does my task touch?' (a bounded, disclosed scope from a work task); and its `pipeline` mode traces control flow within that bound into a ConceptualPipelineMap alongside the architectural/domain collections, then cross-checks all three against each other (the maximal six directed pairs) for mutual correction. The `/pipeline-map \"<task>\"` command renders the task-scoped map as a self-contained HTML flowchart (pinned, SHA-verified Mermaid inlined; no CDN) with a scope-resolution panel, node-detail table, and no-JS fallback; `--predict-change` adds an opt-in change-site prediction (which stages the task will modify and where it will insert new ones) disclosed as a prediction, never a directive.",
  30. "version": "0.11.0"
  31. }
  32. ]
  33. }
README.md · README · 728 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # ai-literacy-superpowers
  2. [![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
  3. [![Lint Markdown](https://github.com/Habitat-Thinking/ai-literacy-superpowers/actions/workflows/lint-markdown.yml/badge.svg)](https://github.com/Habitat-Thinking/ai-literacy-superpowers/actions/workflows/lint-markdown.yml)
  4. [![Marketplace](https://img.shields.io/badge/Marketplace-v0.4.0-4682B4?style=flat-square)](.claude-plugin/marketplace.json)
  5. [![ai-literacy-superpowers](https://img.shields.io/badge/ai--literacy--superpowers-v0.92.0-4682B4?style=flat-square)](ai-literacy-superpowers/)
  6. [![model-cards](https://img.shields.io/badge/model--cards-v0.1.0-4682B4?style=flat-square)](model-cards/)
  7. [![diagnostic-legibility](https://img.shields.io/badge/diagnostic--legibility-v0.11.0-4682B4?style=flat-square)](diagnostic-legibility/)
  8. [![Skills](https://img.shields.io/badge/Skills-41-2E8B57?style=flat-square)](#skills-41)
  9. [![Agents](https://img.shields.io/badge/Agents-22-2E8B57?style=flat-square)](#agents-22)
  10. [![Commands](https://img.shields.io/badge/Commands-40-2E8B57?style=flat-square)](#commands-40)
  11. [![Harness](https://img.shields.io/badge/Harness-35%2F36_enforced-B8860B?style=flat-square)](HARNESS.md)
  12. [![Harness Health](https://img.shields.io/badge/Harness_Health-Attention-DAA520?style=flat-square)](observability/snapshots/2026-08-25-snapshot.md)
  13. [![Claude Code](https://img.shields.io/badge/Claude_Code-Plugin-D97757?style=flat-square&logo=anthropic&logoColor=white)](https://claude.ai/claude-code)
  14. [![Copilot CLI](https://img.shields.io/badge/Copilot_CLI-Plugin-000000?style=flat-square&logo=githubcopilot&logoColor=white)](https://github.com/features/copilot)
  15. [![Agent Harness Enabled](https://img.shields.io/badge/Agent_Harness-Enabled-000000?style=flat-square)](HARNESS.md)
  16. [![AI Literacy](https://img.shields.io/badge/AI_Literacy-Level_4-2E8B57?style=flat-square)](assessments/2026-08-25-assessment.md)
  17. A plugin marketplace for [Claude Code](https://claude.ai/claude-code) and [GitHub Copilot CLI](https://github.com/features/copilot) shipping opinionated tools for the AI Literacy framework — harness engineering, agent orchestration, decision archaeology, governance, and model evaluation.
  18. Add the marketplace, install the plugin(s) you want, and you have a fully operational habitat for AI-assisted development.
  19. New to the project? Start with [ONBOARDING.md](ONBOARDING.md) or browse the [docs site](https://habitat-thinking.github.io/ai-literacy-superpowers/).
  20. ---
  21. ## Plugins in this marketplace
  22. | Plugin | Version | What it does | Docs |
  23. | ------ | ------- | ------------ | ---- |
  24. | **`ai-literacy-superpowers`** | v0.92.0 | The flagship. Harness engineering, agent orchestration, literate programming, CUPID code review, compound learning, and the three enforcement loops. **41 skills, 20 agents, 32 commands.** | [docs](docs/plugins/ai-literacy-superpowers/index.md) |
  25. | **`model-cards`** | v0.1.0 | Researches and authors Mitchell-extended model cards from a model name. Tiered source strategy (provider docs → HuggingFace → arXiv → web), refusal-on-unconfirmed-existence honesty rule. | [docs](docs/plugins/model-cards/index.md) |
  26. | **`diagnostic-legibility`** | v0.11.0 | Hosts agents accountable for maintaining human understanding. Ships the `diagnostic-legibility` agent — builds and self-challenges two models of a codebase scope (architectural moving parts and domain concepts) via a five-question retained-challenge cycle, then cross-checks the two collections against each other via a five-question per-direction cycle. The `/diagnose` command surfaces the mutually-corrected models on demand as a readable report. The `ConceptualPipelineMap` template adds a standalone, presentation-agnostic flow-perspective data model; the agent's `scope-resolution` mode answers "what does my task touch?"; its `pipeline` mode traces control flow within that bound and cross-checks all three collections; the `/pipeline-map "<task>"` command renders the task-scoped map as a self-contained HTML flowchart (pinned, SHA-verified Mermaid inlined; no CDN); and `--predict-change` adds an opt-in change-site prediction (which stages the task will modify and where it will insert new ones), disclosed as a prediction, never a directive. | [docs](docs/plugins/diagnostic-legibility/index.md) |
  27. The bulk of this README documents the **`ai-literacy-superpowers`** plugin specifically — its skills, agents, commands, hooks, templates, enforcement loops, and pipelines. For `model-cards`, see [its README](model-cards/README.md) and [its docs](docs/plugins/model-cards/index.md). Future sister plugins will land in this marketplace under `<plugin-name>/` with their own docs at `docs/plugins/<plugin-name>/`.
  28. ---
  29. ## Installation
  30. ### 1. Add the marketplace (once)
  31. ```bash
  32. # Claude Code
  33. claude plugin marketplace add Habitat-Thinking/ai-literacy-superpowers
  34. # GitHub Copilot CLI
  35. copilot plugin marketplace add Habitat-Thinking/ai-literacy-superpowers
  36. ```
  37. ### 2. Install the plugin(s) you want
  38. ```bash
  39. # Claude Code
  40. claude plugin install ai-literacy-superpowers # the flagship
  41. claude plugin install model-cards # the sister
  42. # GitHub Copilot CLI
  43. copilot plugin install ai-literacy-superpowers@ai-literacy-superpowers
  44. copilot plugin install model-cards@ai-literacy-superpowers
  45. ```
  46. You can install one, the other, or both. Once installed, each plugin's skills, agents, hooks, and commands (or prompts) are available in any session within your project.
  47. > Commands are available as `/command-name` in Claude Code and as `/prompt-name` in Copilot CLI.
  48. ### Updating
  49. #### Check if an update is available
  50. New template content is found by running `/harness-upgrade`, which compares
  51. your harness against the plugin's template directly. Nothing nudges you
  52. automatically: the marker that used to drive a session-start nudge tracked the
  53. plugin version rather than template content, so it fired on every release
  54. whether or not the template had changed.
  55. - **Manual check** — compare installed vs latest at any time:
  56. ```bash
  57. claude plugin list
  58. ```
  59. #### Update the plugin
  60. When a new version is released, update your local installation:
  61. ```bash
  62. # Claude Code
  63. claude plugin update ai-literacy-superpowers@ai-literacy-superpowers
  64. # Copilot CLI
  65. /plugin update ai-literacy-superpowers
  66. ```
  67. Check the [CHANGELOG](CHANGELOG.md) for what changed between versions.
  68. After updating, run `/harness-upgrade` to review and adopt any new template
  69. content (constraints, GC rules, optional blocks) into your HARNESS.md.
  70. #### Update the marketplace listing
  71. If you maintain your own marketplace that includes this plugin, refresh
  72. the index so new versions are discoverable:
  73. ```bash
  74. claude plugin marketplace update Habitat-Thinking/ai-literacy-superpowers
  75. ```
  76. This pulls the latest `plugin.json` metadata (version, description,
  77. keywords) into the marketplace index. Users who have already installed
  78. the plugin still need to run `claude plugin update` separately.
  79. See [How to Update the Plugin](docs/plugins/ai-literacy-superpowers/update-the-plugin.md) for
  80. the full guide.
  81. ### Quick start
  82. After installation, run these commands to set up your project:
  83. ```bash
  84. # Full habitat setup (recommended for new projects)
  85. /superpowers-init
  86. # Harness-only setup (if you want constraints without the agent pipeline)
  87. /harness-init
  88. # Check the status of your harness
  89. /harness-status
  90. # Run a health check
  91. /harness-health
  92. # Run an AI literacy assessment
  93. /assess
  94. ```
  95. **`/superpowers-init`** sets up the complete habitat: CLAUDE.md, HARNESS.md, AGENTS.md, MODEL_ROUTING.md, REFLECTION_LOG.md, the full agent team, skills, hooks, and CI workflow templates. Use this for new projects.
  96. **`/harness-init`** sets up only the harness: HARNESS.md with starter constraints and GC rules. Use this if you want the constraint and enforcement machinery without the full agent pipeline.
  97. ### Changing a harness rule
  98. Setting a harness up is the easy half. **Once it exists, this is how it changes:**
  99. ```text
  100. /reflect → a human reads the reflections → HARNESS.md → /harness-sync
  101. ```
  102. `HARNESS.md` is the master and it is human-curated. `/reflect` captures what was
  103. noticed and routes it by signal type; a human reviews the corpus, with agentic
  104. support, and decides what is worth writing down. `/harness-sync` then brings the
  105. convention files for Cursor, Copilot and Windsurf into line.
  106. `/harness-constrain` helps author a constraint. `/harness-audit` checks whether
  107. what `HARNESS.md` declares still matches reality. Git history is the record of
  108. what changed and why.
  109. ### Tool Compatibility
  110. This plugin works with both Claude Code and GitHub Copilot CLI from the same repository. The formats have converged:
  111. | Component | Claude Code | Copilot CLI | Shared? |
  112. | --------- | ----------- | ----------- | ------- |
  113. | Skills | `skills/*/SKILL.md` | `skills/*/SKILL.md` | Identical |
  114. | Agents | `agents/*.agent.md` | `agents/*.agent.md` | Identical |
  115. | Hooks | `hooks/hooks.json` | `hooks/hooks.json` | Identical |
  116. | Commands | `commands/*.md` | `.github/prompts/*.prompt.md` | Translated |
  117. | Instructions | Via `templates/CLAUDE.md` | `.github/copilot-instructions.md` | Adapted |
  118. ---
  119. ## `ai-literacy-superpowers` — what it ships
  120. The remaining sections of this README document the **`ai-literacy-superpowers`** plugin in detail. For `model-cards`, see [its README](model-cards/README.md) and [its docs](docs/plugins/model-cards/index.md).
  121. ### Skills (41)
  122. Code quality, harness engineering, and governance knowledge that agents read when working in your codebase.
  123. | Skill | What it provides |
  124. | ----- | ---------------- |
  125. | literate-programming | Knuth's five rules — code as literature, reader-first |
  126. | cupid-code-review | Terhorst-North's five properties — composable, unix, predictable, idiomatic, domain-based |
  127. | github-actions-supply-chain | CI hardening checklist — SHA pinning, permissions, dependabot |
  128. | dependency-vulnerability-audit | Go and Maven CVE scanning procedures |
  129. | docker-scout-audit | Docker image CVE triage and remediation |
  130. | harness-engineering | Foundational concepts — the three components, promotion ladder, enforcement timing |
  131. | context-engineering | Writing conventions precise enough for humans and LLMs to enforce |
  132. | dynamic-workflows | When/which/how to author ephemeral multi-agent workflows — six patterns, election rubric, INV-1/INV-2 governance |
  133. | constraint-design | Designing enforceable constraints with the verification slot model |
  134. | garbage-collection | Entropy-fighting patterns and the auto-fix safety rubric |
  135. | verification-slots | The unified interface for deterministic and agent-based checks |
  136. | ai-literacy-assessment | Assessment instrument — scan repo, ask questions, produce timestamped assessment with prioritised improvement plans |
  137. | harness-observability | Four-layer observability guidance — snapshot format, telemetry export, meta-observability checks |
  138. | convention-extraction | Five extraction questions, artefact mapping, four-element anatomy — surfaces tacit team conventions |
  139. | cross-repo-orchestration | Git-mediated (L4) and specification-mediated (L5) patterns for syncing artefacts and governing portfolios |
  140. | secrets-detection | Gitleaks-based secret scanning — configuration, baselining, and CI integration |
  141. | auto-enforcer-action | Automatic PR constraint checking via GitHub Actions |
  142. | convention-sync | Syncing HARNESS.md conventions to Cursor, Copilot, and Windsurf convention files |
  143. | fitness-functions | Architectural fitness functions as GC rules — periodic checks for layer boundaries, coupling, and complexity |
  144. | model-sovereignty | Decision framework for model selection, hosting, fine-tuning, and vendor independence |
  145. | literacy-improvements | Prioritised improvement plan mapping assessment gaps to plugin commands and skills |
  146. | portfolio-assessment | Multi-repo assessment aggregation — level distribution, shared gaps, and portfolio improvement plans |
  147. | portfolio-dashboard | Generate a self-contained HTML dashboard from portfolio assessment data with trend visualisation |
  148. | team-api | Create or update a Team Topologies Team API document with AI literacy portfolio data |
  149. | cost-tracking | Quarterly AI cost capture — record spend, compare trends, inform model routing |
  150. | cost-estimation | Prospective cost/token/time estimation — range-with-confidence estimate records, snapshot-grounded dollar figures, the prospective sibling of cost-tracking |
  151. | governance-constraint-design | Falsifiable governance constraint authoring — three-frame translation, anti-patterns gallery, governance constraint template |
  152. | governance-audit-practice | Governance audit methodology — five-stage semantic drift model, debt scoring matrix, frame alignment review |
  153. | governance-observability | Governance metrics catalogue, snapshot format extension, and HTML dashboard specification |
  154. | advocatus-diaboli | Adversarial spec review — six-category objection framework, evidence requirements, steel-manned challenge before plan approval |
  155. | choice-cartographer | Decision archaeology — six-lens map of implicit choices a spec has made (forces, alternatives, defaults, patterns, consequences, coherence); routing rule partitions findings between the Cartographer and the diaboli |
  156. | component-design-with-tdad | Design-time methodology for new plugin components — names the five design questions implied by the four-layer TDAD architecture (component type, layer targeting, scenario shape, new-vs-modification, scenario-vs-finding); loadable by spec-writer, tdd-agent, or human brainstorming |
  157. | cognitive-reservoir | Watches the human verifier the harness cannot verify — four observable proxies, observed/inferred/asked confidence discipline, disjunctive thresholds, the decide-your-stop-first principle, and the honesty rule separating contested science (ego depletion, hungry judges) from the robust basis (vigilance decrement, switching cost); advisory-only, never a fatigue score |
  158. | sentinel-design | Defines the sentinel agent category — the three-part signature (S1 read-only, S2 advisory-to-human, S3 explicit honesty rule), the near-miss gallery (why code-reviewer and harness-auditor don't qualify), the honesty-rule-before-detection-logic discipline, and the three anti-patterns (scoring the human, persisting human-state records, gating automatically) |
  159. ### Agents (22)
  160. A coordinated team that handles the full development lifecycle. It
  161. splits into two families: **sentinels**, whose object of care is the
  162. human's understanding and judgement, and **pipeline & harness agents**,
  163. whose object of care is an artefact, the pipeline, or the harness.
  164. #### Sentinels (9)
  165. > **Sentinel** — any agent whose primary purpose is to protect and
  166. > support the understanding and judgement of the human in the workflow.
  167. > It informs, challenges, surfaces, or warns — it never fixes, writes,
  168. > merges, or decides.
  169. Sentinels are the answer to the human side of Margaret-Anne Storey's
  170. [triple-debt model](docs/plugins/ai-literacy-superpowers/explanation/sentinels.md#why-the-category-exists-the-debts-ai-moves-upstream):
  171. where the pipeline and harness agents fight *technical* debt in the code,
  172. sentinels establish and protect the human's **understanding, judgement,
  173. and discernment** — holding back the *cognitive* and *intent* debt that
  174. accrue when AI produces output faster than a person can absorb it.
  175. Every sentinel satisfies the three-part **sentinel signature**: **S1**
  176. read-only trust boundary (no Write/Edit; `Bash` only for read-only
  177. inspection), **S2** advisory output a human disposes (no automated
  178. action), and **S3** an explicit epistemic honesty rule (it declares the
  179. status of its claims). S1 is enforced deterministically — the
  180. [Sentinel integrity](HARNESS.md) constraint fails CI if a
  181. `role: sentinel` agent is granted Write/Edit. See the `sentinel-design`
  182. skill for the near-miss gallery and authoring guidance.
  183. The [decision-discipline triad](docs/plugins/ai-literacy-superpowers/explanation/decision-discipline-triad.md)
  184. (`carpaccio`, `advocatus-diaboli`, `choice-cartographer`) guards
  185. *decisions*; the `reservoir-warden` guards *the decider*; the
  186. `cost-estimator` guards *the decision's inputs*. The four **cadence
  187. sentinels** guard the shape of the work around those decisions: the
  188. `coda` guards *the ending*, the `mast` *the pact*, the `wip-warden`
  189. *the count*, and the `convener` *the room*.
  190. | Agent | Guards | Role | Trust boundary |
  191. | ----- | ------ | ---- | -------------- |
  192. | carpaccio | Judgement scale | Cadence governor — runs at orchestrator step 0 before spec-writer; slices the raw task description into thin, end-to-end-complete pieces; hard gate on slice dispositions | Read only |
  193. | advocatus-diaboli | Decisions at both gates | Adversarial reviewer — spec-time (premise/design focus, before plan approval) and code-time (risk/implementation focus, before integration); six-category objection record, human-cognition gate on dispositions at both gates | Read only |
  194. | choice-cartographer | Understanding of implicit decisions | Decision-archaeology mapper — runs after spec-mode diaboli dispositions are resolved; emits choice stories (Henney pattern stories) for each material implicit decision; soft gate at plan approval, merge-time HARNESS constraint enforces resolution | Read only |
  195. | reservoir-warden | The decider | Verifier-watch — counts observable proxies (session span, decision volume, context switches, wall-clock hour) over the recent git window, reports each with an observed/inferred/asked flag, and offers the single decide-your-stop-first recommendation when a threshold is crossed; persists no record of the human's state | Read only (no Write/Edit) |
  196. | cost-estimator | The decision's inputs | Prospective-cost emitter — reads MODEL_ROUTING.md and the latest observability/costs/ snapshot, applies the cost-estimation methodology, and returns an estimate-record string (token + time ranges, dollar cost only when grounded) for a dispatcher to persist after a human disposes; refuses rather than fabricating an ungroundable estimate | Read only |
  197. | coda | The ending | Session-close ritual — surfaces what was decided, what is left open, and the next action; parks open threads as append-only records for a later session to resume; returns record content for `/coda` to persist; never records why someone stopped | Read only |
  198. | mast | The pact | Pact-keeper — recites a limit the person set in clear weather before measuring anything against it, so the recitation cannot be shaped by the moment; refuses to estimate spend it cannot observe; discloses its own check's blind spot; never gates | Read only |
  199. | wip-warden | The count | Concurrency counter — counts live sessions against a limit the person declared, never inventing one; reports the count's honesty flag; watches sessions, never the human; says plainly that `strict` cannot compel | Read only |
  200. | convener | The room | Counsel-bringer — runs at plan approval beside the cartographer; maps the roles and groups a spec affects and drafts the one concrete question worth asking each; soft gate at plan approval, complete-if-present merge constraint; **never contacts anyone**, in any medium, ever | Read only |
  201. #### Pipeline & harness agents (11)
  202. | Agent | Role | Trust boundary |
  203. | ----- | ---- | -------------- |
  204. | orchestrator | Pipeline coordinator — dispatches agents in sequence | Full access |
  205. | spec-writer | Updates specs and plans before any code is written | No Bash |
  206. | tdd-agent | Writes failing tests from spec scenarios | Can execute tests |
  207. | code-reviewer | Reviews code through CUPID and literate programming lenses | No Write |
  208. | integration-agent | CHANGELOG, commit, PR, CI, merge, cleanup, reflection | Full git access |
  209. | harness-discoverer | Read-only project scanner | Read only |
  210. | harness-enforcer | Unified verification engine for all constraint types | Read + Bash |
  211. | harness-gc | Periodic entropy fighter | Read + Write |
  212. | harness-auditor | Meta-agent — checks whether the harness matches reality | Write to Status only |
  213. | assessor | AI literacy assessment — scans repo, asks questions, applies fixes, recommends workflow changes | Read + Write |
  214. | governance-auditor | Governance specialist — semantic drift analysis, debt inventory, three-frame alignment | Read + limited Write |
  215. ### Commands (40)
  216. | Command | What it does |
  217. | ------- | ------------ |
  218. | `/superpowers-init` | Guided setup — scaffolds the full habitat |
  219. | `/superpowers-status` | Health dashboard — harness, agents, learning, CI |
  220. | `/harness-init` | Harness-specific init |
  221. | `/harness-status` | Quick harness health read |
  222. | `/harness-constrain` | Add or promote a constraint |
  223. | `/harness-gc` | Manage and run garbage collection rules |
  224. | `/harness-audit` | Read-only diagnostic. Same engine as `/harness-sync` but prints findings without prompting to fix. Use for inspection-without-commitment, CI scripts, or the quarterly cadence anchor. |
  225. | `/reflect` | Capture a post-task reflection |
  226. | `/worktree` | Git worktree lifecycle — spin, merge, clean |
  227. | `/assess` | AI literacy assessment with immediate fixes, workflow recommendations, and prioritised improvement plans |
  228. | `/harness-health` | Harness health snapshot — enforcement ratio, trends, meta-observability checks |
  229. | `/extract-conventions` | Guided session — surfaces tacit team conventions and maps them to CLAUDE.md and HARNESS.md |
  230. | `/harness-sync` | Everyday lifecycle entry. Runs the shared audit-engine to detect drift across every surface (convention files, snapshot, Status section accuracy, ONBOARDING.md staleness, template, constraint regressions, recurring reflection patterns), presents a unified drift table tagged `[auto]`/`[manual]`, and applies the fixes you select. Mechanical fixes (convention files, snapshot, Status) auto-apply via existing primitives; judgement-required fixes (ONBOARDING regen, template upgrade, constraint authoring) print suggested commands. |
  231. | `/convention-sync` | Sync HARNESS.md conventions to Cursor, Copilot, and Windsurf convention files |
  232. | `/portfolio-assess` | Multi-repo AI literacy assessment — aggregate across local repos, GitHub orgs, or topic tags |
  233. | `/cost-capture` | Capture AI tool cost data — record spend, compare to previous snapshot, update model routing |
  234. | `/cost-estimate` | Estimate a target's tokens, agent-compute time, and (when grounded) cost before it runs — dispatches the read-only `cost-estimator` agent, validates the record, and writes it to `cost-estimates/` after you dispose (the prospective sibling of `/cost-capture`) |
  235. | `/governance-constrain` | Guided governance constraint authoring with three-frame alignment check |
  236. | `/governance-audit` | Deep governance investigation — semantic drift, debt inventory, frame alignment |
  237. | `/governance-health` | Governance health pulse check and dashboard generation |
  238. | `/harness-upgrade` | Discover and adopt new template content after a plugin upgrade |
  239. | `/harness-onboarding` | Generate a human-readable onboarding guide from harness state |
  240. | `/observatory-verify` | Verify all Observatory signal contracts against latest output files |
  241. | `/carpaccio` | Slice a task description into thin, end-to-end-complete pieces before spec-writer (cadence governor; runs at orchestrator step 0) |
  242. | `/diaboli` | Run the adversarial spec reviewer — produces objection record at `docs/superpowers/objections/<slug>.md` |
  243. | `/choice-cartograph` | Run the Choice Cartographer — produces choice-story record at `docs/superpowers/stories/<slug>.md` after spec-mode diaboli dispositions are resolved |
  244. | `/harness-affordance` | Manage the project's affordance inventory — `discover` scans config to produce a draft inventory; `add` and `review` planned |
  245. | `/reservoir` | Read-only advisory on you, the verifier — Read mode dispatches the `reservoir-warden` agent for a fuller cognitive-reservoir read; Tune mode helps you edit the HARNESS.md `Cognitive reservoir` block (thresholds, chronotype). Advisory-only, not a Constraint |
  246. ### Templates (11)
  247. Opinionated defaults scaffolded by `/superpowers-init`:
  248. - **CLAUDE.md** — framework-aligned conventions (literate programming, CUPID, spec-first, TDD)
  249. - **HARNESS.md** — living harness with starter constraints and enforcement timing
  250. - **AGENTS.md** — compound learning memory (human-curated, agent-proposed)
  251. - **MODEL_ROUTING.md** — model-tier guidance and token budget thresholds (see below)
  252. - **REFLECTION_LOG.md** — append-only agent reflection log
  253. - **ci-github-actions.yml** — CI enforcement template for GitHub Actions
  254. - **ci-auto-enforcer.yml** — GitHub Actions workflow for agent-based PR constraint enforcement
  255. - **ci-mutation-testing.yml** — weekly mutation testing template
  256. - **ci-generic.sh** — fallback CI script for non-GitHub systems
  257. - **ONBOARDING.md** — human-readable onboarding guide skeleton for new team members
  258. - **harness-health-icon.svg** — monochrome shield icon for the README health badge
  259. **MODEL_ROUTING.md** guides cost-conscious model selection. It maps each agent to a model tier (most capable, standard, fast) based on the judgment required. The orchestrator consults it when dispatching agents — spec-writers and code-reviewers get the most capable model; implementers and integration agents get standard models. Token budget guidance prevents runaway costs.
  260. ### Hooks (11)
  261. All hooks are registered in `hooks/hooks.json` and active in every Claude Code session.
  262. - **PostToolUse commit-constraint check** — runs the deterministic commit-scoped constraints HARNESS.md declares against the file just written (deterministic, advisory)
  263. - **PreToolUse markdownlint check** — runs markdownlint on `.md` files being written or edited (deterministic, advisory)
  264. - **Stop drift check** — detects when CI, linter, or dependency configs change, nudges `/harness-audit`
  265. - **Stop snapshot staleness check** — detects when the harness snapshot is stale (> 30 days), nudges `/harness-health`
  266. - **Stop reflection prompt** — detects commits during the session, nudges `/reflect` to capture learnings
  267. - **Stop framework-change prompt** — detects `framework.md` modifications, nudges `/reflect` + `/sync-repos` + downstream README checks
  268. - **Stop secrets check** — scans for accidentally committed secrets or credentials using gitleaks
  269. - **Stop rotating GC check** — runs one deterministic GC rule per session (rotating by day), catching entropy between weekly CI runs
  270. - **Stop curation nudge** — detects unpromoted reflections in `REFLECTION_LOG.md` and nudges curation into `AGENTS.md`
  271. - **Stop governance drift check** — detects governance-related file changes and audit staleness, nudges `/governance-audit`
  272. ---
  273. ## Quick Start
  274. ### Install
  275. See the [Installation](#installation) section above for the full marketplace + plugin install. In short:
  276. ```bash
  277. claude plugin marketplace add Habitat-Thinking/ai-literacy-superpowers
  278. claude plugin install ai-literacy-superpowers
  279. ```
  280. ### Initialize
  281. ```bash
  282. cd your-project
  283. ```
  284. Then in Claude Code:
  285. ```text
  286. /superpowers-init
  287. ```
  288. The init command will:
  289. 1. Scan your project to discover the stack, existing linters, CI, and test frameworks
  290. 2. Ask about your conventions (one topic at a time)
  291. 3. Ask which constraints to enforce and how
  292. 4. Offer the full agent pipeline or a subset
  293. 5. Generate CLAUDE.md, HARNESS.md, AGENTS.md, MODEL_ROUTING.md, REFLECTION_LOG.md, CI workflows, and a README badge
  294. 6. Commit everything
  295. ### Check Health
  296. ```text
  297. /superpowers-status
  298. ```
  299. Shows harness enforcement ratio, agent team configuration, compound learning state, model routing, and CI summary.
  300. ---
  301. ## How to Extend
  302. ### Adding a language-specific implementer
  303. The plugin provides the agent pipeline pattern but does not ship language-specific implementers — these are created per project for each language in the stack. To create one:
  304. 1. Copy the pattern from any existing implementer (e.g. the exemplar's `go-implementer.md`)
  305. 2. Adapt the tool permissions, file scope, and build commands for your language
  306. 3. Save to `.claude/agents/<language>-implementer.md` in your project
  307. 4. The orchestrator will discover and dispatch it automatically
  308. ### Adding a new skill
  309. 1. Create a directory: `skills/<skill-name>/`
  310. 2. Add `SKILL.md` with YAML frontmatter (`name`, `description` with trigger conditions)
  311. 3. Optionally add a `references/` subdirectory for supporting material
  312. 4. The plugin auto-discovers skills by directory structure
  313. ### Adding a new command
  314. 1. Create `commands/<command-name>.md` with YAML frontmatter (`name`, `description`)
  315. 2. Define the process steps the command should follow
  316. 3. The command becomes available as `/<command-name>` in Claude Code sessions
  317. ### Adding a new hook
  318. 1. Create a script in `hooks/scripts/<script-name>.sh`
  319. 2. Add an entry to `hooks/hooks.json` under the appropriate event (`PreToolUse`, `PostToolUse`, or `Stop`)
  320. 3. Hook scripts receive context via environment variables (`CLAUDE_PROJECT_DIR`, etc.)
  321. 4. Always make hooks advisory (warn, don't block) unless enforcement is critical
  322. ---
  323. ## The Three Enforcement Loops
  324. Every mechanism in the plugin operates at one of three timescales:
  325. | Loop | Trigger | Strictness | Purpose |
  326. | ---- | ------- | ---------- | ------- |
  327. | Advisory | PreToolUse hook | Warn | Catch issues while context is fresh |
  328. | Strict | CI on PR | Fail | Prevent violations from reaching main |
  329. | Investigative | Scheduled GC + audit | Report | Fight slow entropy that gates miss |
  330. ### Mechanism Map
  331. ```text
  332. ADVISORY LOOP (edit time — warn, do not block)
  333. │
  334. ├── Hooks
  335. │ ├── PostToolUse commit-constraint Runs HARNESS.md's deterministic commit-scoped
  336. │ │ check constraints on the file just written
  337. │ ├── PreToolUse markdownlint check Runs markdownlint on .md files being
  338. │ │ written or edited (deterministic)
  339. │ ├── Stop drift check Detects CI/linter/dependency changes at
  340. │ │ session end, nudges /harness-audit
  341. │ ├── Stop snapshot staleness check Detects stale harness snapshot (> 30 days),
  342. │ │ nudges /harness-health
  343. │ ├── Stop reflection prompt Detects commits during session,
  344. │ │ nudges /reflect to capture learnings
  345. │ ├── Stop framework-change prompt Detects framework.md modifications,
  346. │ │ nudges /reflect + /sync-repos +
  347. │ │ downstream README checks
  348. │ ├── Stop secrets check Scans for committed secrets using gitleaks
  349. │ ├── Stop rotating GC check Runs one deterministic GC rule per session,
  350. │ │ rotating by day-of-year
  351. │ ├── Stop curation nudge Detects unpromoted reflections, nudges
  352. │ │ curation into AGENTS.md
  353. │ └── Stop governance drift check Detects governance file changes, nudges
  354. │ /governance-audit
  355. ├── Context (read by agents at session start)
  356. │ ├── CLAUDE.md Workflow rules, conventions, disciplines
  357. │ ├── AGENTS.md Compound learning memory (human-curated)
  358. │ ├── MODEL_ROUTING.md Model-tier guidance + token budgets
  359. │ └── Skills (36) Domain knowledge for agents
  360. │
  361. └── Commands
  362. ├── /reflect Capture post-task learnings
  363. └── /worktree spin|merge|clean Parallel agent isolation
  364. STRICT LOOP (merge time — block until green)
  365. │
  366. ├── CI Workflows (generated from templates)
  367. │ ├── ci-github-actions.yml PR-scoped constraint enforcement
  368. │ │ (markdownlint, gitleaks, shell checks)
  369. │ ├── gc.yml Weekly GC for deterministic rules
  370. │ ├── docs-build-check.yml mkdocs --strict at PR time
  371. │ ├── spec-redaction-marker-check.yml Blocks HTML-comment redaction in specs
  372. │ ├── tdad-tests-fast.yml TDAD Layers 0+1 fast-suite at PR time
  373. │ ├── tdad-scenario-check.yml New plugin components must ship a scenario
  374. │ └── ci-mutation-testing.yml Language-specific mutation testing
  375. │
  376. ├── Agent Pipeline
  377. │ ├── orchestrator Coordinates full pipeline
  378. │ │ ├── GATE: objection adjudication User resolves objections before proceeding
  379. │ │ ├── GATE: plan approval User reviews spec + adjudicated objections
  380. │ │ └── GUARDRAIL: MAX_REVIEW_CYCLES=3
  381. │ ├── spec-writer Spec + plan updates (no Bash)
  382. │ ├── advocatus-diaboli Adversarial spec review (read-only)
  383. │ ├── tdd-agent Failing tests from spec scenarios
  384. │ ├── implementer(s) Makes tests green — user-created per
  385. │ │ language, not shipped by the plugin
  386. │ ├── code-reviewer CUPID + LP review (no Write)
  387. │ └── integration-agent CHANGELOG, PR, CI, merge, reflection
  388. │
  389. └── Harness Constraints (HARNESS.md)
  390. ├── Deterministic Backed by CI tools
  391. ├── Agent-backed Backed by harness-enforcer
  392. └── Unverified Declared intent, not yet automated
  393. INVESTIGATIVE LOOP (scheduled — sweep for entropy)
  394. │
  395. ├── Garbage Collection Rules (HARNESS.md)
  396. │ ├── Weekly CI workflow (gc.yml) Deterministic rules: secret scanner,
  397. │ │ snapshot staleness, shell checks
  398. │ ├── Rotating Stop hook One deterministic GC rule per session
  399. │ └── Agent-scoped rules Documentation freshness, command-prompt
  400. │ sync, plugin manifest currency
  401. ├── Compound Learning
  402. │ ├── REFLECTION_LOG.md Agent reflections (append-only)
  403. │ └── AGENTS.md Human-curated from reflections
  404. │
  405. ├── Harness Commands
  406. │ ├── /harness-audit Full meta-verification
  407. │ ├── /harness-health Snapshot with trends and meta-observability checks
  408. │ ├── /harness-status Quick health read
  409. │ └── /harness-gc Run GC checks on demand
  410. │
  411. └── Governance Commands
  412. ├── /governance-constrain Guided governance constraint authoring
  413. ├── /governance-audit Deep governance investigation
  414. └── /governance-health Governance pulse check and dashboard
  415. ```
  416. ### Observability as the Enabling Layer
  417. The three enforcement loops generate signals that, when collected, make the entire habitat observable. The plugin's mechanisms produce the data; observability tools (OpenTelemetry, Claude Code analytics, Grafana) make it visible.
  418. | Panel | What it shows | Sources |
  419. | ----- | ------------- | ------- |
  420. | **Cost** | Spend trend, model-tier distribution, cost per PR | Provider API, MODEL_ROUTING.md compliance |
  421. | **Quality** | Coverage trend, mutation score trend, change failure rate | CI artifacts, mutation testing workflow |
  422. | **Adoption** | Active AI users, sessions per developer, acceptance rate | Provider analytics |
  423. | **Habitat health** | Harness enforcement ratio, compound learning growth, ALCI progression | /harness-status, REFLECTION_LOG.md, ALCI surveys |
  424. Without observability, cost discipline is aspirational, mutation testing is a one-time experiment, and the harness is a document that may or may not match reality. With it, every mechanism gains an evidence layer.
  425. ---
  426. ## Harness Observability
  427. The plugin includes a four-layer observability model for monitoring harness health over time:
  428. | Layer | Question | How |
  429. | ----- | -------- | --- |
  430. | Operational cadence | Is the harness running? | `/harness-health` generates snapshots; a Stop hook nudges when the last snapshot is older than 30 days |
  431. | Trend visibility | How has the harness changed? | Snapshots are diffed to show deltas; `--trends` produces multi-period views |
  432. | Telemetry export | Can I visualise this externally? | Snapshot data can be exported as OpenTelemetry metrics to any OTLP-compatible backend |
  433. | Meta-observability | Is the observability itself working? | Five self-checks: snapshot currency, cadence compliance, learning flow, GC effectiveness, trend direction |
  434. ### Health snapshots
  435. `/harness-health` generates structured markdown snapshots stored in `observability/snapshots/`. Each snapshot captures:
  436. - Enforcement ratios (deterministic / agent / unverified breakdown)
  437. - Garbage collection rule status and findings
  438. - Mutation testing kill rates per language
  439. - Compound learning velocity (reflections and promotions)
  440. - Operational cadence compliance
  441. - Meta-observability results
  442. Trends are derived by diffing consecutive snapshots — no external tooling required.
  443. ### README health badge
  444. `/harness-health` maintains a shields.io badge in the project README:
  445. - **Healthy** (green) — all layers operating, no overdue cadences
  446. - **Attention** (amber) — one layer degraded or outer loop overdue
  447. - **Degraded** (red) — multiple layers degraded or no snapshot in 30+ days
  448. ### Telemetry export
  449. For teams that want external dashboards, the `references/telemetry-export.md` reference documents OTel metric names and a reference export script. The file-based approach (snapshots in git) is the default — telemetry export is optional.
  450. ### Related plugin components
  451. - Skill: `skills/harness-observability/SKILL.md`
  452. - Command: `commands/harness-health.md`
  453. - Meta-checks: `skills/harness-observability/references/meta-observability-checks.md`
  454. - Snapshot format: `skills/harness-observability/references/snapshot-format.md`
  455. - Telemetry export: `skills/harness-observability/references/telemetry-export.md`
  456. - Hook: snapshot staleness check in `hooks/hooks.json`
  457. - Script: `scripts/update-health-badge.sh`
  458. ---
  459. ## The Agent Pipeline
  460. When you use the orchestrator agent, it runs this pipeline:
  461. ```text
  462. orchestrator
  463. → spec-writer
  464. → advocatus-diaboli (spec mode — read-only, produces spec objection record)
  465. → GATE: objection adjudication — spec mode (user writes dispositions; gate blocked while any is `pending`)
  466. → GATE: plan approval (user reviews plan + adjudicated spec objection record)
  467. → tdd-agent
  468. → implementer(s) (parallel, one per language — user-created per project)
  469. → code-reviewer
  470. → GUARDRAIL: MAX_REVIEW_CYCLES=3 (escalate after 3 loops)
  471. → advocatus-diaboli (code mode — read-only, produces code objection record; runs once after loop exits)
  472. → GATE: integration approval — code mode (user writes dispositions; gate blocked while any is `pending`)
  473. → integration-agent (includes reflection step)
  474. ```
  475. The spec objection adjudication gate raises premise-level challenges before any tests or code exist — the cheapest moment to change course. The plan approval gate catches bad plans before they become bad code. The loop guardrail prevents unbounded reviewer cycles. The code objection adjudication gate surfaces threat-model, failure-mode, and operational concerns visible in the implementation before merge.
  476. The plugin ships the orchestrator, spec-writer, tdd-agent, code-reviewer, and integration-agent. Language-specific implementers are not included — each project creates its own based on the stack. See [How to Extend](#how-to-extend) for instructions.
  477. ---
  478. ## Dynamic Workflows
  479. Beneath the static agent pipeline sits an **ephemeral execution substrate**: *dynamic workflows* — self-authored, single-task multi-agent harnesses an agent writes, runs once, and discards. Each subagent gets a clean context window and its own model tier, which is what defeats the three failure modes a single long context is prone to: **agentic laziness** (declaring a multi-part job done after partial progress), **self-preferential bias** (an agent judging its own output), and **goal drift**. The conceptual model lives in the [`dynamic-workflows`](ai-literacy-superpowers/skills/dynamic-workflows/SKILL.md) skill and the [how-to guide](docs/plugins/ai-literacy-superpowers/how-to/dynamic-workflows.md).
  480. **Six composable patterns** — classify-and-act, **fan-out**-and-synthesize, **adversarial** verification, generate-and-filter, **tournament**, and loop-until-done — are the building blocks. The plugin dogfoods them: the `harness-enforcer` fans out one verifier per constraint; `code-reviewer` reviews in a separate context; `assessor`/`harness-auditor` run deep-research scans; `/reflect --mine` mines the reflection log; and the `orchestrator` can route a task to a tournament, root-cause, or triage workflow.
  481. **Elect deliberately.** Workflows cost more tokens and suit long-running, massively parallel, highly structured, or adversarial tasks — so they are **opt-in**, never reflexive. The four-question [when-not-to-use](ai-literacy-superpowers/skills/dynamic-workflows/references/when-not-to-use.md) rubric keeps the **static pipeline the default**; reaching for a workflow on a routine task is treated as over-orchestration.
  482. **Two governing invariants** protect the curated harness from ephemeral churn:
  483. - **INV-1 — ephemeral proposes, durable curates.** A workflow may *propose* changes but **never writes** the durable, human-curated artefacts (`HARNESS.md`, `AGENTS.md`, `CLAUDE.md`, `MODEL_ROUTING.md`) directly; discoveries flow through `REFLECTION_LOG.md → human curates → AGENTS.md`. A deterministic CI firewall (`ai-literacy-superpowers/scripts/inv-firewall.sh`) enforces this on every shipped template.
  484. - **INV-2 — quarantine.** A workflow agent that reads untrusted or public content is withheld high-privilege tools; only separate trusted agents act on what it found.
  485. **Runtime scope — Claude Code only.** Dynamic workflows are a **Claude Code** runtime capability and are **not transferable** to other coding agents. The plugin ships the skill to both the Claude Code and **Copilot** CLI trees: where the workflow runtime is present, the modes execute; where it is absent (Copilot CLI or any other agent), the skill is **guidance** only — readable knowledge with each workflow-mode degrading to its static fallback — never omitted and never erroring.
  486. ---
  487. ## Compound Learning
  488. Agents learn across sessions through curated documentation:
  489. ```text
  490. Agent completes work
  491. → integration-agent appends to REFLECTION_LOG.md
  492. → Human reviews periodically
  493. → Worthy entries promoted to AGENTS.md
  494. → All agents read AGENTS.md at next session start
  495. ```
  496. Research shows LLM-generated documentation files reduce success rates. Human-curated files provide modest but real improvement. The rule: agents propose; humans curate.
  497. ### Compound learning flow
  498. The plugin implements a three-stage learning cycle:
  499. 1. **Capture** — the integration-agent appends a structured reflection to `REFLECTION_LOG.md` after each task (date, agent, task, surprise, proposal, improvement)
  500. 2. **Curate** — during the quarterly operating cadence, humans review reflections and promote worthy entries to `AGENTS.md` as GOTCHA or ARCH_DECISION entries
  501. 3. **Benefit** — all agents read `AGENTS.md` at session start, incorporating prior learnings into their decision-making
  502. The GC rule "Stale AGENTS.md" flags reflections older than 30 days that haven't been reviewed for promotion. This prevents the common failure mode where reflections are captured but nobody reads them.
  503. ---
  504. ## Intellectual Foundations
  505. This plugin packages the practical workflow from the AI Literacy for Software Engineers framework. The design draws on several lineages — architecture, theory, craft, and engineering practice — that converge on a single idea: the environment matters as much as the code.
  506. ### Architecture and Habitability
  507. - **Christopher Alexander** — *A Pattern Language* (1977); *The Timeless Way of Building* (1979). The "quality without a name" — design for inhabitants, not spectators. Alexander's insight that environments shape the behaviour of their occupants is the conceptual root of habitat engineering.
  508. - **Richard P. Gabriel** — *Patterns of Software* (1996). Habitability: code as a place to live in. Gabriel extended Alexander's architectural philosophy to software, arguing that code should be welcoming to the people who maintain it.
  509. ### Code as Tacit Practice
  510. - **Michael Polanyi** — *Personal Knowledge* (1958); *The Tacit Dimension* (1966). *We can know more than we can tell.* Tacit knowing — the practical understanding built up through engaged work, much of which resists articulation — is the ground on which all explicit knowledge stands. Polanyi gives the cognitive-science epistemology that Naur's theory-building applies to software: the substance of "theory" is Polanyi's tacit knowing. Polanyi grounds why the plugin's pedagogical commitments matter — the framework's cognitive gym (Theme #7), no-vibe coding (Theme #2), and the creator-to-verifier shift (Theme #15) are all defences against the tacit-knowledge attrition that AI generation tends to produce. Frank Ginac's "Cognitive Atrophy and Systemic Collapse in AI-Dependent Software Engineering" (2026, arxiv:2604.26855) gives the contemporary application.
  511. ### Code as Theory
  512. - **Peter Naur** — "Programming as Theory Building" (1985); *Computing: A Human Activity* (1992). The essential product of programming is not the code but the theory the programmers hold about how the system works — Polanyi's tacit knowing applied to software. Loss of theory is loss of system: code can be preserved while the understanding that made it changeable is not. Naur is what habitability protects — the substance of shared understanding that the plugin's compound-learning components (REFLECTION_LOG.md, AGENTS.md, the convention-extraction and harness-audit skills) exist to externalise and sustain.
  513. ### Code as Literature
  514. - **Donald Knuth** — "Literate Programming" (1984); *TeX: The Program* (1986). Code is written for humans to read, and only incidentally for machines to execute. The literate-programming skill applies Knuth's discipline: narrative preambles, reasoning-based documentation, presentation ordered by understanding.
  515. - **Daniel Terhorst-North** — "CUPID — for joyful coding" (2022). Five properties that good code tends toward: Composable, Unix philosophy, Predictable, Idiomatic, Domain-based. The cupid-code-review skill uses these as a review and refactoring lens.
  516. ### Harness Engineering
  517. - **Birgitta Boeckeler** — ["Harness Engineering"](https://martinfowler.com/articles/exploring-gen-ai/harness-engineering.html) (2026). *Exploring Gen AI*, martinfowler.com. The three components of a complete harness: context engineering, architectural constraints, and garbage collection. The theoretical foundation for the plugin's three enforcement loops.
  518. - **Mitchell Hashimoto** — "AI Harness" (2025). Blog post referenced by Boeckeler as a possible origin of the harness terminology.
  519. - **Chad Fowler** — "Relocating Rigor." Essay on how rigor moves from writing code to designing the systems that generate and verify code. Frames the shift from manual discipline to environmental enforcement.
  520. ### Convention Discovery
  521. - **Rahul Garg** — ["Encoding Team Standards"](https://martinfowler.com/articles/reduce-friction-ai/encoding-team-standards.html) (2026). *Patterns for Reducing Friction in AI-Assisted Development*, martinfowler.com. Treats AI instructions as infrastructure, not individual craft. Structured extraction interviews surface tacit team knowledge. Informed the convention-extraction skill and `/extract-conventions` command.
  522. ### Agent Orchestration
  523. - **Addy Osmani** — ["The Code Agent Orchestra"](https://addyosmani.com/blog/code-agent-orchestra/) (2026). addyosmani.com. Subagent delegation, quality gates, compound learning, and the orchestrator pattern. Informed the agent pipeline design, worktree isolation, and the review loop guardrail.
  524. ### Specification-Driven Development
  525. - **Gojko Adzic** — *Specification by Example: How Successful Teams Deliver the Right Software*. Manning. Concrete examples as tests; specifications as the shared language between intent and implementation. Informed the spec-first workflow and the spec-writer agent.
  526. ### Verification and Quality
  527. - **Dave Farley** — Controlled study of 150 participants comparing AI-generated and human-written code across creation and maintenance phases. Evidence for AI as an amplifier of existing discipline — the core argument for why harnesses matter.
  528. - **2025 DORA Report** — DevOps Research and Assessment. Findings on AI as an amplifier of existing engineering discipline: teams with strong practices benefit; teams without them are harmed.
  529. ### Cognitive Science (Framework Foundation)
  530. The plugin implements practical workflows, but the framework's design decisions are grounded in cognitive science research on how human and artificial intelligence differ:
  531. - **Andy Clark** — *Surfing Uncertainty* (2015). Predictive processing and the embodied mind.
  532. - **George Lakoff & Mark Johnson** — *Metaphors We Live By* (1980). Embodied cognition and conceptual metaphor.
  533. - **Edwin Hutchins** — *Cognition in the Wild* (1995). Distributed cognition — intelligence as a property of systems, not individuals.
  534. - **Lucy Suchman** — *Plans and Situated Actions* (1987). The gap between plans and situated human action.
  535. - **James J. Gibson** — *The Ecological Approach to Visual Perception* (1979). Affordances — the environment offers possibilities for action.
  536. - **John Boyd** — The OODA Loop. Observe-Orient-Decide-Act as a cognitive cycle — the basis for the harness's replanning-after-each-action pattern.
  537. - **Donella Meadows** — *Thinking in Systems* (2008). Systems thinking, leverage points, and feedback loops — the conceptual model for the three enforcement loops.
  538. The mission: building habitats where human and AI intelligence thrive together.
  539. ---
  540. ## See It in Action
  541. For a complete worked example of this plugin applied to a real project, see the [ai-literacy-exemplar](https://github.com/russmiles/ai-literacy-exemplar) repository — a Go CLI tool built using the full agent pipeline, with authentic git history showing the framework workflow.
  542. ---
  543. ## License
  544. [Apache License 2.0](LICENSE)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.