@erclx/aitk 0.27.0 → 0.29.0

package/README.md

@@ -6,7 +6,9 @@
 
 One source for your repos' AI conventions. Install once, sync everywhere.
 
-![Adding the aitk marketplace and installing the plugin in Claude Code](assets/install.png)
+![The aitk catalog, listing skills, governance rules, and standards with the count each ships and a sample of their names](assets/hero.png)
+
+If you work across more than one repository and your AI setup has started to drift between them, this is for you. The counts above are read from the catalogs when the image is built, so they're what the repo actually ships today.
 
 ## Install
 
@@ -17,6 +19,8 @@ claude plugin marketplace add https://github.com/erclx/aitk
 claude plugin install aitk@aitk
 ```
 
+![Adding the aitk marketplace and installing the plugin in Claude Code](assets/install.png)
+
 The skills land as `/aitk:<name>`. If your session was already open, run `/reload-plugins` to pick them up. Updates arrive on release, so a push to this repo won't reach your installed copy.
 
 Several skills call the `aitk` CLI to read catalogs and run installs, and the plugin doesn't put it on your path. Install it from the registry.

package/claude/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "aitk",
   "description": "Automated governance, versioning, and discovery tools for Claude Code.",
-  "version": "0.27.0",
+  "version": "0.29.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

package/docs/agents.md

@@ -93,7 +93,7 @@ Each domain exposes a consistent shape where applicable: `list`, `install`, `syn
 | `snippets`  | `list`, `install`, `sync`, `create`                                    |
 | `standards` | `list`, `install`, `sync`                                              |
 | `gov`       | `list`, `install`, `sync`, `build`                                     |
-| `claude`    | `init`, `sync`, `seeds list`, `setup [dest]`                           |
+| `claude`    | `init`, `sync`, `seeds list`, `skills list`, `setup [dest]`            |
 | `wiki`      | `init`                                                                 |
 | `design`    | `render`                                                               |
 | `slides`    | `render`, `list`                                                       |
@@ -327,6 +327,8 @@ aitk capture assets/install.html
 aitk capture assets --out .claude/review/captures
 ```
 
+`assets/` now holds two sources, so a bare `aitk capture` rebuilds both. `install.html` is hand-authored and its text came from a real run. `hero.html` is generated by `scripts/core/regen-hero.sh` from the CLI catalogs and must not be edited by hand, since `bun run check` regenerates it and fails on the difference. Only the HTML is asserted for drift. The PNG is a chromium render whose bytes move with the browser version, so rebuild it with `aitk capture assets/hero.html` when the check reports the HTML changed.
+
 | Option             | Behavior                                          |
 | ------------------ | ------------------------------------------------- |
 | `--out <dir>`      | Write every PNG here instead of beside its source |
@@ -407,14 +409,15 @@ What remains is a sentence naming a hypothetical entry to show the shape of a na
 
 Use these to discover what's available instead of hardcoding names.
 
-| Command                         | Returns                                      |
-| ------------------------------- | -------------------------------------------- |
-| `aitk tooling list --json`      | Stacks, extends chain, dep and script counts |
-| `aitk snippets list --json`     | Presets and categories with their slugs      |
-| `aitk standards list --json`    | Standards docs and the paths each governs    |
-| `aitk gov list --json`          | Governance stacks and rule sets              |
-| `aitk claude seeds list --json` | Seed doc sources with content                |
-| `aitk docs list --json`         | Consumer docs plus per-domain context        |
+| Command                          | Returns                                      |
+| -------------------------------- | -------------------------------------------- |
+| `aitk tooling list --json`       | Stacks, extends chain, dep and script counts |
+| `aitk snippets list --json`      | Presets and categories with their slugs      |
+| `aitk standards list --json`     | Standards docs and the paths each governs    |
+| `aitk gov list --json`           | Governance stacks and rule sets              |
+| `aitk claude seeds list --json`  | Seed doc sources with content                |
+| `aitk claude skills list --json` | Plugin skills with their descriptions        |
+| `aitk docs list --json`          | Consumer docs plus per-domain context        |
 
 Every catalog serializes through `JSON.stringify`, so a name carrying a quote
 emits valid JSON. `aitk tooling list` and `aitk snippets list` previously built
@@ -433,6 +436,14 @@ listing and the install cannot disagree. It now reports
 `.claude/context/index.md`, which `init` has always installed and the listing
 never named, and it emits the project-level `CLAUDE.md` last rather than first.
 
+`aitk claude skills list` reads `claude/skills/*/SKILL.md` and reports the folder
+name with the frontmatter description, sorted by name. Internal skills under
+`.claude/skills/` are excluded, since they never install into a target and a
+count spanning both overstates what ships. A skill whose frontmatter is missing
+or unparseable returns an empty description rather than failing the listing, so
+one malformed file cannot hide the rest of the catalog. `--names` emits skill
+names one per line.
+
 ## Non-interactive examples
 
 ```bash

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/aitk",
   "type": "module",
-  "version": "0.27.0",
+  "version": "0.29.0",
   "description": "Infrastructure and quality tooling for developer workflows",
   "license": "MIT",
   "bin": {

package/scripts/core/regen-hero.sh

@@ -0,0 +1,128 @@
+#!/usr/bin/env bash
+# Fills assets/hero.html.tmpl from the CLI catalogs and writes assets/hero.html.
+#
+# Only the HTML regenerates here. The PNG beside it is a chromium render whose
+# bytes move with the browser version, so asserting it in verify.sh would fail
+# on a machine whose chromium differs rather than on a stale count. Rebuild the
+# image with `aitk capture assets/hero.html` after this script reports a change.
+# The frame carries no version. `package.json` is bumped on main by the release
+# tooling, so embedding it drifts every open branch on the next release and the
+# stage then fails for work that touched nothing.
+#
+# Clone-only. `src/capture` is excluded from the published tarball, and this
+# script reads the repository's own catalogs, so a registry install has neither.
+set -e
+set -o pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="${PROJECT_ROOT:-$(cd "$SCRIPT_DIR/../.." && pwd)}"
+
+TEMPLATE="$PROJECT_ROOT/assets/hero.html.tmpl"
+OUTPUT="$PROJECT_ROOT/assets/hero.html"
+LISTED=10
+
+# `bun src/cli.ts` rather than `aitk`, since a globally linked binary resolves to
+# the main checkout no matter which worktree is running.
+catalog() {
+  (cd "$PROJECT_ROOT" && AITK_NON_INTERACTIVE=1 bun src/cli.ts "$@" --json 2>/dev/null)
+}
+
+if [ ! -f "$TEMPLATE" ]; then
+  echo "regen-hero: missing template at $TEMPLATE" >&2
+  exit 1
+fi
+
+SKILLS_JSON="$(catalog claude skills list)"
+GOV_JSON="$(catalog gov list)"
+STANDARDS_JSON="$(catalog standards list)"
+SNIPPETS_JSON="$(catalog snippets list)"
+TOOLING_JSON="$(catalog tooling list)"
+
+for payload in "$SKILLS_JSON" "$GOV_JSON" "$STANDARDS_JSON" "$SNIPPETS_JSON" "$TOOLING_JSON"; do
+  if [ -z "$payload" ]; then
+    echo "regen-hero: a catalog returned nothing, refusing to write a zeroed hero" >&2
+    exit 1
+  fi
+done
+
+export SKILLS_JSON GOV_JSON STANDARDS_JSON SNIPPETS_JSON TOOLING_JSON
+export TEMPLATE OUTPUT LISTED PROJECT_ROOT
+
+bun --eval '
+const {
+  SKILLS_JSON, GOV_JSON, STANDARDS_JSON, SNIPPETS_JSON, TOOLING_JSON,
+  TEMPLATE, OUTPUT, LISTED, PROJECT_ROOT,
+} = process.env
+
+const listed = Number(LISTED)
+const skills = JSON.parse(SKILLS_JSON).skills.map((entry) => entry.name)
+const gov = JSON.parse(GOV_JSON)
+// Rule names carry a numeric prefix that orders the load, not the identity a
+// reader knows them by, so the frame shows the slug alone.
+const rules = gov.rules.map((entry) => entry.name.replace(/^\d+-/, ""))
+const standards = JSON.parse(STANDARDS_JSON).standards.map((entry) => entry.name)
+const snippets = new Set(
+  JSON.parse(SNIPPETS_JSON).categories.flatMap((category) => category.entries),
+)
+const toolingStacks = JSON.parse(TOOLING_JSON).stacks
+
+const escape = (value) =>
+  value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;")
+
+// Even spacing across the sorted catalog rather than its first N. The skill
+// names are prefixed by domain, so an alphabetical head returns eight
+// `claude-*` entries and reads as a narrower catalog than the one that ships.
+const sample = (names) => {
+  if (names.length <= listed) return names
+  const step = names.length / listed
+  return Array.from({ length: listed }, (_, i) => names[Math.floor(i * step)])
+}
+
+const entries = (names) =>
+  sample(names)
+    .map((name) => `            <div class="entry">${escape(name)}</div>`)
+    .join("\n")
+
+const remaining = (names) => String(Math.max(0, names.length - listed))
+
+// An empty array is well-formed JSON, so the shell guard on an empty payload
+// does not catch a catalog whose tree went missing. A zeroed count would ship a
+// frame claiming the domain has nothing in it.
+for (const [label, list] of [
+  ["skills", skills], ["rules", rules], ["standards", standards],
+  ["snippets", [...snippets]], ["tooling stacks", toolingStacks], ["gov stacks", gov.stacks],
+]) {
+  if (list.length === 0) {
+    console.error(`regen-hero: the ${label} catalog is empty, refusing to write a zeroed hero`)
+    process.exit(1)
+  }
+}
+
+const values = {
+  SKILL_COUNT: String(skills.length),
+  RULE_COUNT: String(rules.length),
+  STANDARD_COUNT: String(standards.length),
+  SNIPPET_COUNT: String(snippets.size),
+  GOV_STACK_COUNT: String(gov.stacks.length),
+  TOOLING_STACK_COUNT: String(toolingStacks.length),
+  SKILL_ENTRIES: entries(skills),
+  RULE_ENTRIES: entries(rules),
+  STANDARD_ENTRIES: entries(standards),
+  SKILL_MORE: remaining(skills),
+  RULE_MORE: remaining(rules),
+  STANDARD_MORE: remaining(standards),
+}
+
+let html = await Bun.file(TEMPLATE).text()
+for (const [key, value] of Object.entries(values)) {
+  html = html.replaceAll(`{{${key}}}`, value)
+}
+
+const unresolved = html.match(/{{[A-Z_]+}}/g)
+if (unresolved) {
+  console.error(`regen-hero: unresolved placeholders ${[...new Set(unresolved)].join(", ")}`)
+  process.exit(1)
+}
+
+await Bun.write(OUTPUT, html)
+'

package/scripts/core/verify.sh

@@ -99,6 +99,23 @@ collect_plugin_manifests() {
   } | sort -u
 }
 
+# The drift assert covers the HTML because the PNG is a chromium render whose
+# bytes move with the browser. That leaves the artifact a visitor actually sees
+# asserted nowhere, so a branch that regenerates the HTML and never runs the
+# capture passes every stage while shipping an image with the old counts.
+#
+# The two files move together or the image is stale, so their last-touching
+# commit is the same commit. Comparing the branch's file list instead would pass
+# any branch that touched both anywhere, including one that regenerated the HTML
+# alone in a later commit. Both absent resolves to two empty strings and passes,
+# which is correct for a tree that carries neither.
+assert_hero_pair() {
+  local html_commit png_commit
+  html_commit=$(git -C "$PROJECT_ROOT" log -1 --format=%H -- assets/hero.html)
+  png_commit=$(git -C "$PROJECT_ROOT" log -1 --format=%H -- assets/hero.png)
+  [ "$html_commit" = "$png_commit" ]
+}
+
 assert_no_drift() {
   local paths=$1
   local err_msg=$2
@@ -135,6 +152,15 @@ main() {
   assert_no_drift ".claude/standards .claude/snippets .claude/internal .claude/rules" "Consumed copies drifted. Run bun run check and commit .claude/standards, .claude/snippets, .claude/internal, and .claude/rules."
   log_info "Consumed copies clean"
 
+  # Only the HTML is asserted. The PNG beside it is a chromium render whose bytes
+  # move with the browser version, so a drift check over it would fail on a
+  # machine whose chromium differs rather than on a stale count.
+  log_step "Hero"
+  run_check "bash $PROJECT_ROOT/scripts/core/regen-hero.sh" "Hero regen failed"
+  assert_no_drift "assets/hero.html" "Hero counts drifted. Run bun run check, then aitk capture assets/hero.html, and commit assets/hero.html with assets/hero.png."
+  run_check "assert_hero_pair" "Hero HTML and image last moved in different commits, so the image may be stale. Run aitk capture assets/hero.html and commit both files together."
+  log_info "Hero clean"
+
   log_step "Skill references"
   run_check "bash $PROJECT_ROOT/scripts/core/regen-skill-references.sh" "Skill-reference regen failed"
   assert_no_drift "claude/skills/*/references" "Skill references drifted. Run bun run check and commit the updated reference files."

package/src/claude/skills-list.ts

@@ -0,0 +1,53 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+
+const FRONTMATTER = /^---\n([\s\S]*?)\n---/
+
+export interface SkillListing {
+  readonly name: string
+  readonly description: string
+}
+
+/**
+ * Enumerates the plugin skill catalog, which is the corpus under `claude/`
+ * rather than the internal skills under `.claude/`. Only the former installs
+ * into a target, so a count taken across both overstates what ships.
+ *
+ * The folder name wins over the frontmatter `name` when they disagree, because
+ * Claude Code invokes a skill by its directory.
+ */
+export function listSkills(root: string): SkillListing[] {
+  const skillsRoot = join(root, 'claude', 'skills')
+  if (!existsSync(skillsRoot)) return []
+
+  const paths = [
+    ...new Bun.Glob('*/SKILL.md').scanSync({
+      cwd: skillsRoot,
+      onlyFiles: true,
+    }),
+  ].sort()
+
+  return paths.map((path) => ({
+    name: dirname(path),
+    description: readDescription(join(skillsRoot, path)),
+  }))
+}
+
+/**
+ * Returns an empty description rather than throwing on a skill whose
+ * frontmatter is missing or unparseable, so one malformed file does not hide
+ * the rest of the catalog from a caller counting it.
+ */
+function readDescription(path: string): string {
+  const match = FRONTMATTER.exec(readFileSync(path, 'utf8'))
+  if (!match) return ''
+
+  try {
+    const parsed = Bun.YAML.parse(match[1])
+    if (typeof parsed !== 'object' || parsed === null) return ''
+    const { description } = parsed as Record<string, unknown>
+    return typeof description === 'string' ? description : ''
+  } catch {
+    return ''
+  }
+}

package/src/commands/claude.ts

@@ -12,6 +12,7 @@ import {
   type Seed,
 } from '@/claude/seeds'
 import { listSeeds, readSeedContents } from '@/claude/seeds-list'
+import { listSkills } from '@/claude/skills-list'
 import {
   planSettings,
   readSettings,
@@ -43,6 +44,11 @@ interface SeedsListOptions {
   readonly names?: boolean
 }
 
+interface SkillsListOptions {
+  readonly json?: boolean
+  readonly names?: boolean
+}
+
 const SEEDED_FILES: readonly string[] = [
   'ARCHITECTURE.md',
   'REQUIREMENTS.md',
@@ -130,6 +136,42 @@ export function register(program: Command): void {
     .action(async (opts: SeedsListOptions) => {
       process.exitCode = await runSeedsList(opts)
     })
+
+  const skills = claude
+    .command('skills')
+    .description('Plugin skill catalog (list)')
+    .argument('[subcommand]', "Only 'list' is supported")
+    .helpOption('-h, --help', 'Show this help message')
+    .action((subcommand: string | undefined) => {
+      intro('aitk claude')
+      logError(
+        subcommand === undefined
+          ? "Missing subcommand. Use 'list'."
+          : `Unknown subcommand: ${subcommand}. Use 'list'.`,
+      )
+      outro()
+      process.exitCode = 1
+    })
+
+  skills
+    .command('list')
+    .description('List the plugin skills shipped under claude/skills/')
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--json', 'Emit JSON with name and description')
+    .option('--names', 'Only list skill names, one per line')
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Notes:',
+        '  Internal skills under .claude/skills/ are excluded, since they',
+        '  never install into a target project.',
+        '',
+      ].join('\n'),
+    )
+    .action((opts: SkillsListOptions) => {
+      process.exitCode = runSkillsList(opts)
+    })
 }
 
 function succeed(message: string): number {
@@ -347,3 +389,27 @@ async function runSeedsList(opts: SeedsListOptions): Promise<number> {
   outro()
   return 0
 }
+
+function runSkillsList(opts: SkillsListOptions): number {
+  const listings = listSkills(PROJECT_ROOT)
+
+  if (opts.json) {
+    process.stdout.write(`${JSON.stringify({ skills: listings })}\n`)
+    return 0
+  }
+
+  if (opts.names) {
+    process.stdout.write(
+      listings.map((listing) => listing.name).join('\n') + '\n',
+    )
+    return 0
+  }
+
+  intro('aitk claude')
+  logStep('Plugin skills')
+  for (const listing of listings) {
+    logInfo(listing.name)
+  }
+  outro()
+  return 0
+}

package/standards/index.md

@@ -19,6 +19,6 @@ Reference docs for consistent authoring across the toolkit and target projects.
 - [Claude skill reference](skill.md): Claude skill structure and authoring rules
 - [Slug reference](slug.md): Transform from a git branch name to a slug, and the three responses to an empty result
 - [Standard reference](standard.md): Shape and content rules for authoring a standard
-- [Tasks reference](tasks.md): Folder layout, filename convention, and content rules for .claude/tasks/
+- [Tasks reference](tasks.md): Folder layout, filename convention, readiness groups, and content rules for .claude/tasks/
 - [Versioning reference](versioning.md): Phase label vs semver discipline across tasks, PRs, reviews, issues, commits, and tags
 - [Wireframe reference](wireframes.md): Shape and content rules for .claude/wireframes/<surface>.md files

package/standards/tasks.md

@@ -1,6 +1,6 @@
 ---
 title: Tasks reference
-description: Folder layout, filename convention, and content rules for .claude/tasks/
+description: Folder layout, filename convention, readiness groups, and content rules for .claude/tasks/
 ---
 
 # Tasks reference
@@ -11,7 +11,7 @@ The folder is gitignored. Board state changes when work ships rather than when a
 
 ## Scope
 
-Governs the task board under `.claude/tasks/`: folder layout, filenames, frontmatter, file format, origin lines, and archiving.
+Governs the task board under `.claude/tasks/`: folder layout, filenames, frontmatter, file format, origin lines, execution ordering, and archiving.
 
 Does not govern:
 
@@ -34,11 +34,23 @@ One file per task is what keeps the board safe under parallel sessions. Two sess
 
 `index.md` is generated from sibling frontmatter. The folder is gitignored, so the whole-repo index walk skips it and a hook passing the changed path regenerates it instead. Never hand-edit it.
 
+The `claude-tasks` skill creates and archives task files. `claude-docs` marks outcomes `[x]` in an existing file and sweeps the plans those tasks cite. Neither does the other's job.
+
+## Ordering
+
 `priority.md` carries execution order and what each task is waiting on. The generated index sorts by filename and says nothing about order, so without this file board state gets reconstructed by hand every session. Why the order is what it is belongs in `.claude/ROADMAP.md`, which is committed because that rationale has no substitute record.
 
-Group tasks by readiness rather than by status, one row per task, with a stated column for what each is blocked on. Keep it to links and blockers: tables, plus at most one sentence per section. A paragraph in `priority.md` is a defect whatever it says. Stating the shape this way is what lets a single diff fail, since a size cap only trips after the fact and every addition looks defensible on its own.
+Group tasks by readiness rather than by status, one row per task, under the columns each group fixes below. Keep it to links and blockers: tables, plus at most one sentence per section. A paragraph in `priority.md` is a defect whatever it says. Stating the shape this way is what lets a single diff fail, since a size cap only trips after the fact and every addition looks defensible on its own.
 
-The `claude-tasks` skill creates and archives task files. `claude-docs` marks outcomes `[x]` in an existing file and sweeps the plans those tasks cite. Neither does the other's job.
+Readiness is three groups under fixed headings, `## Run now`, `## Up next`, and `## Needs a plan`, in that order. The names are the contract rather than a suggestion, because a board grouped by readiness under names of its own satisfies every other rule here and still reads as empty to anything counting rows under a heading. Add no fourth group. A task belongs to exactly one, and the tests are read in order.
+
+- `## Run now`: a written plan covers every open outcome, and the files the task touches collide with nothing already running. A worker is handed a task from this group alone.
+- `## Up next`: a written plan exists, and the task either collides with something running or waits on another task to land. The blocker column names which.
+- `## Needs a plan`: everything else. The task has no plan, or the plan it carries no longer describes the work.
+
+Each group fixes its own columns, which follow from the test above it rather than from preference. `## Run now` carries `Task`, `Touches`, and `Plan`, since neither half of its test is checkable without the last two. `## Up next` carries `Task`, `Touches`, and `Waiting on`, the last naming whether a collision or a dependency holds it. `## Needs a plan` carries `Task` and `Waiting on` alone, because a task with no plan has no bounded file set to state.
+
+The tests live here so the board does not carry them. Writing them as a sentence under each heading produces the paragraph the rule above deletes, and a criterion with no home gets restated from memory every time the board is touched.
 
 ## Filenames