@erclx/aitk 0.39.0 → 0.40.0

package/docs/agents/scripting.md

@@ -0,0 +1,115 @@
+---
+title: Scripting
+description: The runtime catalogs that replace hardcoded names, what each carries, and a headless invocation per domain
+---
+
+# Scripting
+
+What a skill or script reads to discover names at runtime, and how each domain is invoked with no TTY.
+
+## Runtime catalogs
+
+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 claude skills list --json` | Plugin skills, descriptions, requirement flag |
+| `aitk docs list --json`          | Consumer docs plus per-domain context         |
+
+### Catalog fields
+
+Every catalog serializes through `JSON.stringify`, so a name carrying a quote
+emits valid JSON. `aitk tooling list` and `aitk snippets list` previously built
+their output with `printf` and no escaping.
+
+`aitk standards list` carries `appliesTo` per standard, the paths that standard's
+`## Scope` statement declares. It holds the backticked paths from the first
+sentence of the statement, the single entry `*` for a standard governing an
+attribute rather than a document type, and an empty array when the statement
+declares nothing a parser can read. A consumer mapping a file to its governing
+standards reads this rather than holding a table of its own, and reports an empty
+array rather than skipping the standard behind it.
+
+`aitk claude seeds list` reads the same plan `aitk claude init` applies, so the
+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.
+
+### The skills catalog
+
+`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.
+
+Each entry also carries `requirement`, whether the folder holds a sibling
+`REQUIREMENT.md`. Every skill is meant to carry one, so a `false` is a gap to
+close rather than a recorded exemption, and the flag answers which skills are
+missing theirs without a caller listing the directory itself. Nothing gates the
+rule yet, which is why the flag is worth reading against the shipped corpus after
+a merge.
+
+## Non-interactive examples
+
+```bash
+# Create a new tooling stack
+AITK_NON_INTERACTIVE=1 aitk tooling create astro
+
+# Sync a stack into a target project
+AITK_NON_INTERACTIVE=1 aitk tooling sync astro /path/to/project
+
+# Install a governance stack (the stack argument is required headlessly)
+AITK_NON_INTERACTIVE=1 aitk gov install astro --add 260-shadcn /path/to/project
+
+# Update installed governance rules, dropping a retired .claude/GOV.md
+AITK_NON_INTERACTIVE=1 aitk gov sync /path/to/project
+
+# Concatenate installed rules into a paste payload
+AITK_NON_INTERACTIVE=1 aitk gov build /path/to/project
+
+# Sync a monorepo subtree, skipping the base layer the repo root already owns
+AITK_NON_INTERACTIVE=1 aitk tooling sync vite-react /path/to/repo/frontend --skip base
+
+# Verify a stack end-to-end in a throwaway scaffold
+aitk tooling verify vite-react
+
+# Apply one stack without scanning or prompting, for scripted provisioning
+aitk tooling inject base /path/to/project
+aitk tooling inject base /path/to/project --configs --seeds
+
+# Drop managed gitignore entries a manifest no longer declares
+# Prints the number removed on stdout, diagnostics on stderr
+aitk tooling prune-gitignore base /path/to/project
+
+# Install a snippet preset
+AITK_NON_INTERACTIVE=1 aitk snippets install essentials /path/to/project
+
+# Update snippets already installed, leaving project-authored ones alone
+AITK_NON_INTERACTIVE=1 aitk snippets sync /path/to/project
+
+# Report standards drift without applying it, which is what headless does here
+AITK_NON_INTERACTIVE=1 aitk standards sync /path/to/project
+
+# Copy every standard into a target, overwriting what is there
+AITK_NON_INTERACTIVE=1 aitk standards install /path/to/project
+
+# Bootstrap a project. Any flag suppresses the confirmation prompt
+AITK_NON_INTERACTIVE=1 aitk init --stack astro --skip wiki /path/to/project
+
+# Run every domain sync. The git workflow is refused headlessly, so nothing is pushed
+AITK_NON_INTERACTIVE=1 aitk sync /path/to/project
+
+# Scaffold .claude/wiki/ with a stub index. The target must already exist
+AITK_NON_INTERACTIVE=1 aitk wiki init /path/to/project
+
+# Run a sandbox scenario non-interactively
+SANDBOX_SCENARIO=sync aitk sandbox infra:tooling
+```

package/docs/agents/tasks.md

@@ -0,0 +1,33 @@
+---
+title: Tasks
+description: Selecting a shipped task by stem or pull request, the refusal reasons, and why the board root defaults to the main worktree
+---
+
+# Tasks
+
+`aitk tasks archive` moves a shipped task from `.claude/tasks/` into `.claude/.tmp/task-archive/`, drops its row from `priority.md`, and regenerates the board index. The three run as one unit, so the attended and unattended callers cannot archive differently.
+
+Name the task by its filename stem, or by the pull request it carries:
+
+```bash
+aitk tasks archive v28.1-trigger-escalation
+aitk tasks archive --pull-request 673 --json
+```
+
+| Option               | Behavior                                                     |
+| -------------------- | ------------------------------------------------------------ |
+| `--pull-request <n>` | Select the task whose `Pull request:` line names this number |
+| `--json`             | Emit a machine-readable record on stdout                     |
+| `--root <path>`      | Board root, defaulting to the main worktree                  |
+
+Exit codes: `0` archived, `1` refused. Every gate is a refusal rather than a warning, because `.husky/post-merge` calls this with nobody watching. The `reason` field carries which gate fired: `no-board`, `no-match`, `ambiguous`, `no-outcomes`, `open-outcomes`, or `plan-unswept`.
+
+The board is shared scratch at the main worktree root, so `--root` defaults to the first entry of `git worktree list` rather than the working directory. A linked worktree archives against the same board every other session reads.
+
+Skills branch on the reason rather than on the exit code:
+
+```bash
+aitk tasks archive --pull-request 673 --json | jq -r 'if .ok then .task else .reason end'
+```
+
+For the board format, the `Pull request:` line, and the archive rules, see `.claude/standards/tasks.md`.

package/docs/index.md

@@ -9,7 +9,6 @@ One-line reference for each doc in this folder.
 
 ## Agent surface
 
-- [Agents](agents.md): CLI catalog and invocation rules for agents
 - [AI workflow](ai-workflow.md): Overarching AI workflow across domains
 - [Target projects](target-projects.md): Scaffold, add domains later, and sync upstream drift in a toolkit-managed project
 
@@ -18,3 +17,7 @@ One-line reference for each doc in this folder.
 - [Operating model](operating-model.md): Orchestrator and worker roles for building across parallel sessions
 - [Visual design workflow](visual-design-workflow.md): Tiered guide for design and wireframe authoring with Claude Code
 - [Zshrc aliases for Claude Code](zshrc-aliases.md): Shell aliases that shorten common Claude Code invocations
+
+## Sub-catalogs
+
+- [Agents](agents/index.md): CLI catalog and invocation rules for agents, split by command domain. Start with overview.

package/docs/target-projects.md

@@ -8,7 +8,7 @@ category: Agent surface
 
 How a project outside this repo consumes the toolkit across its lifecycle. Three phases: scaffold once, add a domain later when a new need appears, and sync when the upstream toolkit moves.
 
-This doc stays at the narrative layer. For command flags and JSON shapes, see [agents](agents.md). For per-domain mechanics, see each `.claude/context/<domain>.md`.
+This doc stays at the narrative layer. For command flags and JSON shapes, see [agents](agents/index.md). For per-domain mechanics, see each `.claude/context/<domain>.md`.
 
 ## Getting the skills
 
@@ -179,7 +179,7 @@ Sync also refuses a target whose working tree is dirty, so commit or stash befor
 
 ## Related
 
-- [agents](agents.md): CLI flags, exit codes, and JSON output shapes
+- [agents](agents/index.md): CLI flags, exit codes, and JSON output shapes
 - [AI workflow](ai-workflow.md): feature-development loop inside a toolkit-managed project
 - [tooling](../.claude/context/tooling.md), [governance](../.claude/context/governance.md), [claude plugin](../.claude/context/claude-plugin/index.md), [indexes](../.claude/context/indexes.md), [snippets](../.claude/context/snippets.md), [standards](../.claude/context/standards.md): per-domain mechanics
 - [sandbox](../.claude/context/sandbox/index.md): scenario catalog for verifying domain flows

package/package.json

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

package/scripts/docs/list.sh

@@ -38,6 +38,35 @@ is_internal_topic() {
   esac
 }
 
+# Emits `name<TAB>description<TAB>category<TAB>target` per target-facing doc,
+# sorted so a domain split into a folder lands in its alphabetical place rather
+# than after every file. A folder declares its category on its own index, since
+# the allowlist is what separates a target-facing doc from a workflow one and a
+# split domain is not exempt from it.
+collect_docs() {
+  local file name description category
+  {
+    while IFS= read -r file; do
+      name=$(basename "$file" .md)
+      [ "$name" = "index" ] && continue
+      category=$(read_frontmatter_field "$file" "category")
+      is_target_facing "$category" || continue
+      description=$(read_frontmatter_field "$file" "description")
+      printf '%s\t%s\t%s\t%s\n' "$name" "$description" "$category" "docs/$name.md"
+    done < <(find "$DOCS_DIR" -maxdepth 1 -type f -name "*.md")
+
+    # A split domain is named by its folder and described by its generated
+    # index, which carries subtitle where a sibling file carries description
+    while IFS= read -r file; do
+      name=$(basename "$(dirname "$file")")
+      category=$(read_frontmatter_field "$file" "category")
+      is_target_facing "$category" || continue
+      description=$(read_frontmatter_field "$file" "subtitle")
+      printf '%s\t%s\t%s\t%s\n' "$name" "$description" "$category" "docs/$name/index.md"
+    done < <(find "$DOCS_DIR" -mindepth 2 -maxdepth 2 -type f -name "index.md")
+  } | sort
+}
+
 # Emits `name<TAB>description<TAB>target` per context entry, sorted so a domain
 # split into a folder lands in its alphabetical place rather than after every
 # file. Matches listTopics in src/docs/read.ts, which sorts both together.
@@ -64,16 +93,11 @@ collect_context() {
 }
 
 list_text() {
-  local file name description category target
+  local name description category target
   log_step "Docs"
-  while IFS= read -r file; do
-    name=$(basename "$file" .md)
-    [ "$name" = "index" ] && continue
-    category=$(read_frontmatter_field "$file" "category")
-    is_target_facing "$category" || continue
-    description=$(read_frontmatter_field "$file" "description")
+  while IFS=$'\t' read -r name description category target; do
     log_info "$name : $description"
-  done < <(find "$DOCS_DIR" -maxdepth 1 -type f -name "*.md" | sort)
+  done < <(collect_docs)
 
   # Absent in a registry install, which ships docs/ without .claude/
   if [ -d "$CONTEXT_DIR" ]; then
@@ -97,17 +121,12 @@ emit_json_entry() {
 }
 
 list_json() {
-  local file name description category target
+  local name description category target
   JSON_FIRST=1
   printf '['
-  while IFS= read -r file; do
-    name=$(basename "$file" .md)
-    [ "$name" = "index" ] && continue
-    category=$(read_frontmatter_field "$file" "category")
-    is_target_facing "$category" || continue
-    description=$(read_frontmatter_field "$file" "description")
-    emit_json_entry "$name" "$description" "$category" "docs/$(basename "$file")"
-  done < <(find "$DOCS_DIR" -maxdepth 1 -type f -name "*.md" | sort)
+  while IFS=$'\t' read -r name description category target; do
+    emit_json_entry "$name" "$description" "$category" "$target"
+  done < <(collect_docs)
 
   if [ -d "$CONTEXT_DIR" ]; then
     while IFS=$'\t' read -r name description target; do

package/src/commands/sandbox.ts

@@ -389,7 +389,7 @@ function runCheck(
 
   // The report always renders on stderr. `--json` adds the machine copy on
   // stdout rather than replacing the frame, per the stream contract in
-  // `docs/agents.md`, so one invocation serves a human and a caller at once.
+  // `docs/agents/output-shape.md`, so one invocation serves a human and a caller at once.
   reportVerdict(verdict)
   if (options.json === true)
     process.stdout.write(`${JSON.stringify(verdict)}\n`)

package/src/ui.ts

@@ -31,7 +31,7 @@ export function logRemove(message: string): void {
 }
 
 /**
- * Renders the `✗` shape `docs/agents.md` specifies for a failure inside an
+ * Renders the `✗` shape `docs/agents/output-shape.md` specifies for a failure inside an
  * open frame. It does not exit, so the caller closes the frame and returns an
  * exit code rather than terminating mid-write.
  */