@alexandrealvaro/agentic 0.15.0-beta.1 → 0.15.2-beta.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alexandrealvaro/agentic",
-  "version": "0.15.0-beta.1",
+  "version": "0.15.2-beta.1",
   "description": "Bootstrap and audit AGENTS.md, ARCHITECTURE.md, ADRs, skills, and subagents for engineering production code with LLMs",
   "type": "module",
   "bin": {

package/src/lib/rootdoc.js

@@ -11,48 +11,53 @@ const SECTION_END = '<!-- agentic-managed-skills:end -->';
 const SECTION_START_RE = /^<!-- agentic-managed-skills:start -->\n\n## Skills installed by `agentic`/m;
 const SECTION_END_RE = /^<!-- agentic-managed-skills:end -->$/m;
 
-export const SKILL_DESCRIPTIONS = {
-  'ad-bootstrap': 'Generate or audit `AGENTS.md` at the repo root.',
-  'ad-philosophy':
-    'Universal agent guardrails (think before coding, verify before claiming done). Auto-loads on non-trivial work.',
-  'ad-architecture': 'Generate or audit `ARCHITECTURE.md` at the repo root.',
-  'ad-adr': 'Draft a new ADR at `doc/adr/NNNN-<slug>.md`.',
-  'ad-spec':
-    'Draft a feature spec at `doc/specs/NNNN-<slug>.md` (Spec Kit-aligned mandatory sections). Layer 3 of the five-layer artifact stack.',
-  'ad-task': 'Draft a new task at `doc/tasks/NNNN-<slug>.md`.',
-  'ad-audit':
-    'Read-only drift report comparing AGENTS.md / ARCHITECTURE.md / ADRs against the code.',
-  'ad-review':
-    'Fresh-context code review per WORKFLOW §10 — assemble handoff, return structured findings.',
-  'ad-ground':
-    'Four-source pre-implementation research (docs / OSS / in-repo / git history) + happy-path synthesis + deviation gate. WORKFLOW §4 + §5.',
-  'ad-next':
-    'State survey + prioritized next-action recommendations across the five-layer artifact stack. Read-only navigation aid (`flutter doctor` pattern).',
-  'ad-spike':
-    'Staged spike with golden fixtures per WORKFLOW §14. Discovery + fixture + pipeline-with-gates + two-layer evaluation, when the *technique* is uncertain across multiple plausible approaches.',
-  'ad-tdg':
-    'Outcome-based prompting per WORKFLOW §9. Ground truth pair + Test Dependency Map + three approaches + single-criterion selection, when the technique is known but the implementation strategy is uncertain.',
-  'ad-domain':
-    'Lazy lifecycle owner of `CONTEXT.md` (Layer 2 — ubiquitous language per Evans 2003). Captures canonical project-specific nouns with aliases-to-avoid, relationships, and flagged ambiguities. Single-context or `CONTEXT-MAP.md` multi-context.',
-  'ad-grill':
-    'Interview-before-research grilling session — one question at a time with recommendation, codebase-first, sharpens vocabulary against `CONTEXT.md`, captures terms via `ad-domain` and decisions via `ad-adr` (three-criteria rule). Upstream of `ad-ground`.',
-  'ad-deepen':
-    'Surface deepening opportunities using WORKFLOW §8 vocabulary (Module / Interface / Depth / Seam / Adapter / Leverage / Locality). Three phases — explore, present numbered candidates with deletion-test framing, grill the chosen one. Pairs with `ad-audit`. Profile-scoped to `team` and `mature` only.',
-  'ad-diagnose':
-    'Disciplined diagnosis loop for hard bugs and performance regressions per WORKFLOW §15. Five phases — build a feedback loop (the skill itself), reproduce, hypothesise (3-5 ranked falsifiable), instrument (one variable at a time), fix + regression-test.',
-  'ad-commit':
-    'Atomic Conventional Commits with DCO `Signed-off-by` sign-off per ADR-0023. Four phases — scope intake, stage-split when concerns mix, draft message in Conventional Commits format, sign + write. Helper posture, not blocker.',
-  'ad-pr':
-    'Open a GitHub pull request with a uniform body shape (Summary / Test plan / Links) per ADR-0024. Four phases — preflight (`gh` auth + branch pushed), scope assembly, draft body, open + report URL. Title format = Conventional Commits.',
-  'ad-merge':
-    'Evaluate and merge a GitHub pull request per ADR-0025. Four phases — preflight, evaluate (CI / fresh-context review / linked task / unresolved comments / mergeability), decision (CI green = hard gate; others = warnings), merge with auto-detected mode + `--delete-branch`.',
-  'ad-design': 'Bootstrap `DESIGN.md` from existing tokens (frontend projects).',
-  'ad-subagent': 'Draft a new Claude Code subagent at `.claude/agents/<name>.md`.',
-  'ad-skill': 'Draft a new Claude Code or Codex skill at the appropriate path.',
-  'ad-hooks':
-    'Scaffold deterministic quality gates per WORKFLOW §11 — pre-commit + pre-push, runner detected from stack signals.',
+// Where installed SKILL.md files live per agent. Mirrors the install layout
+// (see ADR-0001). updateRootDoc is called per-target-project after install,
+// so reads happen against the just-written installed copy — not the kit
+// source tree (which rootdoc.js has no access to anyway).
+const SKILL_PATH_BY_AGENT = {
+  'claude-code': '.claude/skills',
+  codex: '.agents/skills',
 };
 
+/**
+ * Read the `summary:` line from an installed SKILL.md frontmatter block.
+ *
+ * Per task-0029, every kit skill carries a kit-specific `summary:` field
+ * alongside the Anthropic-spec `description:` field. `description:` is
+ * trigger-keyword-rich for the agent's skill router; `summary:` is the
+ * compressed cell (≤320 chars, enforced by `test/skills.test.js`) that
+ * lands in the managed AGENTS.md table.
+ *
+ * Tries each known target-tree location in order. Throws if no installed
+ * copy has the field — a missing summary surfaces an incomplete install
+ * loudly instead of silently producing empty table cells.
+ */
+function readSkillSummary(cwd, skill) {
+  let found = false;
+  for (const skillsDir of Object.values(SKILL_PATH_BY_AGENT)) {
+    const path = join(cwd, skillsDir, skill, 'SKILL.md');
+    if (!existsSync(path)) continue;
+    found = true;
+    const body = readFileSync(path, 'utf8');
+    // Horizontal whitespace only between `summary:` and the value. JavaScript
+    // `\s` matches `\n`, so `\s*` would silently consume the line break and
+    // capture the following frontmatter line as the summary when the field
+    // is present but empty. Restricting to `[ \t]*` keeps the match on one
+    // line and lets an empty-summary line fall through to the throw below.
+    const match = body.match(/^summary:[ \t]*(.+)$/m);
+    if (match) return match[1].trim();
+  }
+  if (found) {
+    throw new Error(
+      `skill ${skill} is installed but no SKILL.md carries a non-empty \`summary:\` frontmatter field`
+    );
+  }
+  throw new Error(
+    `skill ${skill} not found at any installed location; cannot read summary`
+  );
+}
+
 /**
  * Find the first existing root doc; null if none.
  * Preference order: AGENTS.md (open standard), then CLAUDE.md (Claude Code legacy).
@@ -65,7 +70,7 @@ function findRootDoc(cwd) {
   return null;
 }
 
-function buildSection(skills) {
+function buildSection(cwd, skills) {
   const lines = [];
   lines.push(SECTION_START);
   lines.push('');
@@ -78,7 +83,7 @@ function buildSection(skills) {
   lines.push('| Skill | Invoke | Notes |');
   lines.push('| --- | --- | --- |');
   for (const skill of skills) {
-    const note = SKILL_DESCRIPTIONS[skill] || '';
+    const note = readSkillSummary(cwd, skill);
     const invoke =
       skill === 'ad-philosophy' ? '_(implicit)_' : `\`/${skill}\``;
     lines.push(`| \`${skill}\` | ${invoke} | ${note} |`);
@@ -135,10 +140,13 @@ export async function updateRootDoc({
   if (!found) return { type: 'absent', path: null };
 
   const body = readFileSync(found.path, 'utf8');
-  const section = buildSection(skills);
   const bounds = findSectionBounds(body);
 
+  // Build the section lazily — readSkillSummary touches the installed
+  // SKILL.md files (per task-0029). When the user declines a section
+  // append/replace, there is no reason to walk every installed skill.
   if (bounds) {
+    const section = buildSection(cwd, skills);
     const updated = replaceSection(body, section, bounds);
     if (updated === body) return { type: 'unchanged', path: found.name };
     const ok = await confirmReplace(found.name);
@@ -150,6 +158,7 @@ export async function updateRootDoc({
   const ok = await confirmAppend(found.name);
   if (!ok) return { type: 'skipped', path: found.name };
 
+  const section = buildSection(cwd, skills);
   const sep = body.endsWith('\n') ? '\n' : '\n\n';
   if (!dryRun) writeFileSync(found.path, body + sep + section + '\n');
   return { type: 'appended', path: found.name };

package/src/skills/claude-code/ad-adr/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: ad-adr
 description: Draft a new ADR (Architecture Decision Record) at doc/adr/NNNN-<short-title>.md, using Michael Nygard's Context/Decision/Consequences/Alternatives pattern. Use when the user wants to record, write, draft, propose, or document an architecture decision. Status starts at proposed; the agent does not flip to accepted without explicit user approval.
+summary: Draft a new ADR at `doc/adr/NNNN-<slug>.md`.
 allowed-tools: Read, Write, Glob, Bash
 ---
 

package/src/skills/claude-code/ad-architecture/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: ad-architecture
 description: Generate ARCHITECTURE.md at the repo root by scanning the code first, pre-filling layers/patterns/observability/deployment from observed signals, then asking only the genuine gaps. Use when the user wants to bootstrap, scaffold, generate, document, or audit ARCHITECTURE.md (system-level patterns and boundaries, paired with ADRs in doc/adr/). Covers brownfield (code exists) and audit (drift report against existing ARCHITECTURE.md).
+summary: Generate or audit `ARCHITECTURE.md` at the repo root.
 allowed-tools: Read, Write, Glob, Grep, Bash
 ---
 

package/src/skills/claude-code/ad-audit/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: ad-audit
 description: Read-only drift audit — compare AGENTS.md, ARCHITECTURE.md, ADR statuses, feature specs in doc/specs/, and documentation discipline against what the code actually does. Outputs a drift list, never writes files. Use when the user wants to audit, review for drift, sanity-check, or report inconsistencies between the repo's docs and its code.
+summary: Read-only drift report comparing AGENTS.md / ARCHITECTURE.md / ADRs against the code.
 allowed-tools: Read, Glob, Grep, Bash
 ---
 

package/src/skills/claude-code/ad-bootstrap/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: ad-bootstrap
 description: Generate AGENTS.md at the repo root by scanning the codebase first, pre-filling placeholders from observed signals, and asking only the genuine gaps. Use whenever the user wants to bootstrap, scaffold, generate, create, set up, or audit AGENTS.md / agents.md / CLAUDE.md (the operational guide for agents working on this project). Covers greenfield (empty repo), brownfield (code exists, no AGENTS.md), and audit (drift report against existing AGENTS.md).
+summary: Generate or audit `AGENTS.md` at the repo root.
 allowed-tools: Read, Write, Glob, Grep, Bash
 ---
 

package/src/skills/claude-code/ad-commit/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: ad-commit
 description: Atomic Conventional Commits with DCO `Signed-off-by` sign-off per ADR-0023. Four phases — scope intake, stage-split when concerns mix, draft message in Conventional Commits format, sign + write. Stage-split is interactive; identity comes from `git config user.name` / `user.email`. No `Co-Authored-By`. Helper posture, not blocker. Triggers on "commit this", "stage and commit", "atomic commit", "Conventional Commit", "sign off", "DCO", "split this commit", "/ad-commit".
+summary: Atomic Conventional Commits with DCO `Signed-off-by` sign-off per ADR-0023. Four phases — scope intake, stage-split when concerns mix, draft message in Conventional Commits format, sign + write. Helper posture, not blocker.
 allowed-tools: Read, Bash
 ---
 

package/src/skills/claude-code/ad-deepen/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: ad-deepen
 description: Surface deepening opportunities in the codebase using the Ousterhout/Feathers vocabulary from WORKFLOW §8 (Module / Interface / Depth / Seam / Adapter / Leverage / Locality). Three-phase process — explore organically, present numbered candidates with deletion-test framing, grilling loop on the chosen candidate. Pairs with `ad-audit` (audit detects drift; deepen proposes refactors). Triggers on "deepen", "refactor for depth", "shallow module", "deletion test", "two-adapters rule", "interface is the test surface", "leverage", "locality", "/ad-deepen". Profile-scoped to `team` and `mature` only — premature for `poc` and `solo` per ADR-0020 §4.
+summary: Surface deepening opportunities using WORKFLOW §8 vocabulary (Module / Interface / Depth / Seam / Adapter / Leverage / Locality). Three phases — explore, present numbered candidates with deletion-test framing, grill the chosen one. Pairs with `ad-audit`. Profile-scoped to `team` and `mature` only.
 allowed-tools: Read, Glob, Grep, Bash
 ---
 

package/src/skills/claude-code/ad-design/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: ad-design
 description: Generate DESIGN.md at the repo root by scanning existing design tokens (Figma export, tailwind.config, tokens.json, stylesheet) and synthesizing W3C-compatible YAML frontmatter + Markdown rationale per the Google Labs design.md spec. Use when the user wants to bootstrap, scaffold, generate, document, or audit DESIGN.md (visual contract — colors, typography, spacing, motion). Frontend projects only.
+summary: Bootstrap `DESIGN.md` from existing tokens (frontend projects).
 allowed-tools: Read, Write, Glob, Grep, Bash
 ---
 

package/src/skills/claude-code/ad-diagnose/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: ad-diagnose
 description: Disciplined diagnosis loop for hard bugs and performance regressions per WORKFLOW §15. Five phases — build a feedback loop, reproduce, hypothesise (3-5 ranked falsifiable), instrument, fix + regression-test. The feedback loop is the skill; everything else is mechanical. Triggers on "diagnose this", "debug this", "this is broken", "this is throwing", "performance regression", "find the bug", "build a repro", "feedback loop", "ranked hypotheses", "falsifiable", "/ad-diagnose". Routes to `ad-spike` when the technique is uncertain across approaches, `ad-grill` when the spec is unclear, `ad-tdg` when the bug is a clean ground-truth-pair regression.
+summary: Disciplined diagnosis loop for hard bugs and performance regressions per WORKFLOW §15. Five phases — build a feedback loop (the skill itself), reproduce, hypothesise (3-5 ranked falsifiable), instrument (one variable at a time), fix + regression-test.
 allowed-tools: Read, Edit, Write, Glob, Grep, Bash
 ---
 

package/src/skills/claude-code/ad-domain/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: ad-domain
 description: Lazily create or update `CONTEXT.md` (Layer 2 — ubiquitous language per Evans 2003) at the repo root, or `CONTEXT-MAP.md` plus per-context `CONTEXT.md` for multi-context repos. Captures canonical project-specific nouns, the aliases to avoid, the relationships between them, and resolved ambiguities. Triggers on "domain term", "ubiquitous language", "glossary", "what should we call", "naming drift", "canonical noun", "_Avoid_", "/ad-domain", or whenever a grilling/spec/architecture session resolves a vocabulary question. Lazy by design — file only exists when there is something to write.
+summary: Lazy lifecycle owner of `CONTEXT.md` (Layer 2 — ubiquitous language per Evans 2003). Captures canonical project-specific nouns with aliases-to-avoid, relationships, and flagged ambiguities. Single-context or `CONTEXT-MAP.md` multi-context.
 allowed-tools: Read, Write, Edit, Glob, Grep, Bash
 ---
 

package/src/skills/claude-code/ad-grill/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: ad-grill
 description: Interview-before-research grilling session that challenges a fuzzy ask against the existing codebase, sharpens vocabulary against `CONTEXT.md`, and resolves the design tree branch by branch. One question at a time, codebase-first when an answer is in code, with each question carrying a recommended answer. Triggers on "grill me", "interview me", "stress test the plan", "challenge my assumptions", "before implementing", "ask me questions", "fuzzy ask", "sharpen the question", "what should I clarify", "/ad-grill". Routes to `ad-ground` once the question is research-ready, `ad-tdg` once the technique is settled, `ad-spike` for technique discovery, `ad-diagnose` for debugging.
+summary: Interview-before-research grilling session — one question at a time with recommendation, codebase-first, sharpens vocabulary against `CONTEXT.md`, captures terms via `ad-domain` and decisions via `ad-adr` (three-criteria rule). Upstream of `ad-ground`.
 allowed-tools: Read, Glob, Grep, Bash
 ---
 

package/src/skills/claude-code/ad-ground/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: ad-ground
 description: Four-source pre-implementation research — official docs, validated open-source examples, in-repo patterns, and git history — then synthesize a happy path and gate any deviation with an irrefutable justification before code is written. Auto-invokes on non-trivial work, refactors, library or pattern selection, "research before coding", "before implementing", "which library", "which pattern", "how to approach", "ground before coding". Workflow-operational counterpart to WORKFLOW.md §4 (Find the Happy Path) and §5 (Ground in Real Patterns); pairs with ad-philosophy (posture) and ad-review (post-implementation §10 review).
+summary: Four-source pre-implementation research (docs / OSS / in-repo / git history) + happy-path synthesis + deviation gate. WORKFLOW §4 + §5.
 allowed-tools: Read, Glob, Grep, Bash, WebFetch, WebSearch
 ---
 

package/src/skills/claude-code/ad-hooks/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: ad-hooks
 description: Scaffold deterministic quality gates per WORKFLOW.md §11 — pre-commit (lint, format, secret-scan), pre-push (build, unit, integration). Detects the project's stack and recommends a hook runner (Husky / lefthook / pre-commit / native), scaffolds the runner config, and updates AGENTS.md Quality Gates. Use when the user wants to wire hooks, configure pre-commit / pre-push, set up quality gates, prevent --no-verify bypass, or close the WORKFLOW §11 advisory-vs-deterministic gap. Opt-in skill; not auto-installed in the universal set.
+summary: Scaffold deterministic quality gates per WORKFLOW §11 — pre-commit + pre-push, runner detected from stack signals.
 allowed-tools: Read, Write, Glob, Bash
 ---
 

package/src/skills/claude-code/ad-merge/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: ad-merge
 description: Evaluate and merge a GitHub pull request per ADR-0025. Four phases — preflight (`gh` auth + PR resolution), evaluate (CI / fresh-context review / linked task / unresolved comments / mergeability), decision (CI green = hard gate; others = warnings yielding to user), merge via `gh pr merge` with auto-detected mode (squash / rebase / merge) and `--delete-branch`. Helper posture per ADR-0025 §3 — surfaces warnings, does not block on the senior engineer's judgment. Triggers on "merge this PR", "evaluate the PR", "is it mergeable", "gh pr merge", "/ad-merge".
+summary: Evaluate and merge a GitHub pull request per ADR-0025. Four phases — preflight, evaluate (CI / fresh-context review / linked task / unresolved comments / mergeability), decision (CI green = hard gate; others = warnings), merge with auto-detected mode + `--delete-branch`.
 allowed-tools: Read, Bash, Grep
 ---
 

package/src/skills/claude-code/ad-next/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: ad-next
 description: Survey the project's state across the five-layer artifact stack and recommend prioritized next actions, modeled on `flutter doctor`. Use when the user asks "what's next", "next step", "where am I", "project status", "doctor", "what should I do", "audit my workflow", or whenever a navigation aid is needed mid-flow. Read-only; complements `ad-audit` (drift detection, a different question). Profile-aware — `poc` suppresses Layer 3 / 4 noise, `team` / `mature` run the full survey.
+summary: State survey + prioritized next-action recommendations across the five-layer artifact stack. Read-only navigation aid (`flutter doctor` pattern).
 allowed-tools: Read, Glob, Grep, Bash
 ---
 

package/src/skills/claude-code/ad-philosophy/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: ad-philosophy
 description: Universal agent behavior and documentation discipline — think before coding, ground in real patterns, prefer simplicity, make surgical changes, define verifiable goals, verify before claiming done, and write documentation that captures only definitions and decisions. Auto-invokes on non-trivial changes, refactors, debugging, "think before coding", "ground before coding", "verify done", "before implementing", on documentation work — "writing docs", "writing readme", "writing architecture", "writing adr", "writing task", "audit docs" — or whenever the task is ambiguous enough that guardrails matter.
+summary: Universal agent guardrails (think before coding, verify before claiming done). Auto-loads on non-trivial work.
 ---
 
 # /ad-philosophy

package/src/skills/claude-code/ad-pr/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: ad-pr
 description: Open a GitHub pull request with a uniform body shape per ADR-0024. Four phases — preflight (`gh` auth + branch pushed), scope assembly (commits + diff vs base), draft body (Summary / Test plan / Links), open + report URL. Title format = Conventional Commits, type inferred from the dominant commit type in the range. `gh` CLI soft-fail with install hint. Triggers on "open a PR", "create a pull request", "submit a PR", "gh pr create", "/ad-pr".
+summary: Open a GitHub pull request with a uniform body shape (Summary / Test plan / Links) per ADR-0024. Four phases — preflight (`gh` auth + branch pushed), scope assembly, draft body, open + report URL. Title format = Conventional Commits.
 allowed-tools: Read, Bash, Glob, Grep
 ---
 

package/src/skills/claude-code/ad-review/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: ad-review
 description: Fresh-context code review per WORKFLOW §10 — assemble the diff plus the relevant spec slice (AGENTS.md, applicable ADRs, the task's Acceptance Criteria), delegate to a bundled fresh-context-reviewer subagent with no inherited context, return a structured findings list. Use when the user wants to review a diff, branch, PR, or recent commits against the project's spec, audit for bugs / coupling / edge cases / spec drift, or run a §10 senior-reviewing-junior pass. Adversarial framing — never emits an "approve" verdict.
+summary: Fresh-context code review per WORKFLOW §10 — assemble handoff, return structured findings.
 allowed-tools: Read, Glob, Grep, Bash, Task
 ---
 

package/src/skills/claude-code/ad-skill/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: ad-skill
 description: Draft a new Claude Code or Codex skill at .claude/skills/<name>/SKILL.md (or .agents/skills/<name>/SKILL.md for Codex), using the Anthropic Skills format. Use when the user wants to create, write, draft, or scaffold a custom skill for an agentic coding tool. Asks one question per missing field; never invents skill names or triggers.
+summary: Draft a new Claude Code or Codex skill at the appropriate path.
 allowed-tools: Read, Write, Glob, Bash
 ---
 

package/src/skills/claude-code/ad-spec/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: ad-spec
 description: Draft a feature-level specification at doc/specs/NNNN-<slug>.md following the kit's five-layer artifact stack (Constitution → Domain → Spec → Plan/Decisions → Code). Adapts GitHub Spec Kit's mandatory sections (User Scenarios, Requirements, Success Criteria) to the kit's documentation discipline. Use when the user wants to write, draft, scaffold, or open a feature spec, PRD, product requirements, feature brief, user stories, or success criteria for a feature multiple tasks will implement. Status starts at draft; the file is the binding feature contract once accepted.
+summary: Draft a feature spec at `doc/specs/NNNN-<slug>.md` (Spec Kit-aligned mandatory sections). Layer 3 of the five-layer artifact stack.
 allowed-tools: Read, Write, Glob, Bash
 ---
 

package/src/skills/claude-code/ad-spike/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: ad-spike
 description: Scaffold a staged spike with golden fixtures per WORKFLOW.md §14, for cases where the spec is clear but the technique is uncertain across multiple plausible approaches. Four stages — discovery, golden fixture, pipeline with gates, two-layer evaluation. Use when the unknown is *how*, not *what*. Triggers on "spike", "uncertain technique", "which library", "CV pipeline", "evaluate approaches", "ground truth", "golden fixture", "staged pipeline", "debug per stage". Routes to `ad-ground` if the *how* is routine and a single happy path is obvious. Read-and-write — creates `spikes/NNNN-<slug>/` with fixtures, debug per-stage artifacts, eval results.
+summary: Staged spike with golden fixtures per WORKFLOW §14. Discovery + fixture + pipeline-with-gates + two-layer evaluation, when the *technique* is uncertain across multiple plausible approaches.
 allowed-tools: Read, Write, Glob, Grep, Bash, WebFetch, WebSearch
 ---
 

package/src/skills/claude-code/ad-subagent/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: ad-subagent
 description: Draft a new Claude Code subagent at .claude/agents/<name>.md, using the official subagents format. Use when the user wants to create, write, draft, or scaffold a custom Claude Code subagent for delegated work (fresh-context reviewer, codebase researcher, diff auditor, etc.). Asks one question per missing field; never invents roles or tool sets. Claude Code only — Codex has no subagent primitive.
+summary: Draft a new Claude Code subagent at `.claude/agents/<name>.md`.
 allowed-tools: Read, Write, Glob, Bash
 ---
 

package/src/skills/claude-code/ad-task/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: ad-task
 description: Draft a new task tracking file at doc/tasks/NNNN-<short-slug>.md, using a checkbox-toggle + append-only-Notes format optimized for LLM editing. Use when the user wants to create, draft, scaffold, or open a task, ticket, work item, or backlog entry tracked in the repo. Status starts at proposed; the file is the source of truth, not a board.
+summary: Draft a new task at `doc/tasks/NNNN-<slug>.md`.
 allowed-tools: Read, Write, Glob, Bash
 ---
 

package/src/skills/claude-code/ad-tdg/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: ad-tdg
 description: Outcome-based prompting per WORKFLOW.md §9. Give the agent the finish line first, not the path. Five steps — confirm regime, ground truth pair, Test Dependency Map, three approaches, pick by one criterion, implement and verify. Triggers on "outcome-based", "TDG", "ground truth", "expected output", "three approaches", "pick by criterion", "test dependency map", "TDM", "before modifying", "tests covering this file", "give the finish line". Routes to `ad-spike` if the technique itself is uncertain. No file written; output is the verified implementation that lands through normal commits.
+summary: Outcome-based prompting per WORKFLOW §9. Ground truth pair + Test Dependency Map + three approaches + single-criterion selection, when the technique is known but the implementation strategy is uncertain.
 allowed-tools: Read, Glob, Grep, Bash
 ---
 

package/src/skills/codex/ad-adr/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: ad-adr
 description: Draft a new ADR (Architecture Decision Record) at doc/adr/NNNN-<short-title>.md, using Michael Nygard's Context/Decision/Consequences/Alternatives pattern. Use when the user wants to record, write, draft, propose, or document an architecture decision. Status starts at proposed.
+summary: Draft a new ADR at `doc/adr/NNNN-<slug>.md`.
 ---
 
 <background_information>

package/src/skills/codex/ad-architecture/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: ad-architecture
 description: Generate ARCHITECTURE.md at the repo root by scanning the code first, pre-filling layers/patterns/observability/deployment from observed signals, then asking only the genuine gaps. Use when the user wants to bootstrap, scaffold, generate, document, or audit ARCHITECTURE.md (system-level patterns and boundaries, paired with ADRs in doc/adr/).
+summary: Generate or audit `ARCHITECTURE.md` at the repo root.
 ---
 
 <background_information>

package/src/skills/codex/ad-audit/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: ad-audit
 description: Read-only drift audit — compare AGENTS.md, ARCHITECTURE.md, and ADR statuses against what the code actually does. Outputs a drift list, never writes files. Use when the user wants to audit, review for drift, sanity-check, or report inconsistencies between the repo's docs and its code.
+summary: Read-only drift report comparing AGENTS.md / ARCHITECTURE.md / ADRs against the code.
 ---
 
 <background_information>

package/src/skills/codex/ad-bootstrap/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: ad-bootstrap
 description: Generate AGENTS.md at the repo root by scanning the codebase first, pre-filling placeholders from observed signals, and asking only the genuine gaps. Use whenever the user wants to bootstrap, scaffold, generate, create, set up, or audit AGENTS.md / CLAUDE.md / agents.md (the operational guide for agents working on this project).
+summary: Generate or audit `AGENTS.md` at the repo root.
 ---
 
 <background_information>

package/src/skills/codex/ad-commit/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: ad-commit
 description: Atomic Conventional Commits with DCO `Signed-off-by` sign-off per ADR-0023. Four phases — scope intake, stage-split when concerns mix, draft message in Conventional Commits format, sign + write. Stage-split is interactive; identity comes from `git config user.name` / `user.email`. No `Co-Authored-By`. Helper posture, not blocker. Triggers on "commit this", "stage and commit", "atomic commit", "Conventional Commit", "sign off", "DCO", "split this commit", "/ad-commit".
+summary: Atomic Conventional Commits with DCO `Signed-off-by` sign-off per ADR-0023. Four phases — scope intake, stage-split when concerns mix, draft message in Conventional Commits format, sign + write. Helper posture, not blocker.
 ---
 
 <background_information>

package/src/skills/codex/ad-deepen/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: ad-deepen
 description: Surface deepening opportunities in the codebase using the Ousterhout/Feathers vocabulary from WORKFLOW §8 (Module / Interface / Depth / Seam / Adapter / Leverage / Locality). Three-phase process — explore organically, present numbered candidates with deletion-test framing, grilling loop on the chosen candidate. Pairs with `ad-audit` (audit detects drift; deepen proposes refactors). Triggers on "deepen", "refactor for depth", "shallow module", "deletion test", "two-adapters rule", "interface is the test surface", "leverage", "locality", "/ad-deepen". Profile-scoped to `team` and `mature` only — premature for `poc` and `solo` per ADR-0020 §4.
+summary: Surface deepening opportunities using WORKFLOW §8 vocabulary (Module / Interface / Depth / Seam / Adapter / Leverage / Locality). Three phases — explore, present numbered candidates with deletion-test framing, grill the chosen one. Pairs with `ad-audit`. Profile-scoped to `team` and `mature` only.
 ---
 
 <background_information>

package/src/skills/codex/ad-design/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: ad-design
 description: Generate DESIGN.md at the repo root by scanning existing design tokens (Figma export, tailwind.config, tokens.json, stylesheet) and synthesizing W3C-compatible YAML frontmatter + Markdown rationale per the Google Labs design.md spec. Use when the user wants to bootstrap, scaffold, generate, document, or audit DESIGN.md (visual contract — colors, typography, spacing, motion). Frontend projects only.
+summary: Bootstrap `DESIGN.md` from existing tokens (frontend projects).
 ---
 
 <background_information>

package/src/skills/codex/ad-diagnose/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: ad-diagnose
 description: Disciplined diagnosis loop for hard bugs and performance regressions per WORKFLOW §15. Five phases — build a feedback loop, reproduce, hypothesise (3-5 ranked falsifiable), instrument, fix + regression-test. The feedback loop is the skill; everything else is mechanical. Triggers on "diagnose this", "debug this", "this is broken", "this is throwing", "performance regression", "find the bug", "build a repro", "feedback loop", "ranked hypotheses", "falsifiable", "/ad-diagnose". Routes to `ad-spike` when the technique is uncertain across approaches, `ad-grill` when the spec is unclear, `ad-tdg` when the bug is a clean ground-truth-pair regression.
+summary: Disciplined diagnosis loop for hard bugs and performance regressions per WORKFLOW §15. Five phases — build a feedback loop (the skill itself), reproduce, hypothesise (3-5 ranked falsifiable), instrument (one variable at a time), fix + regression-test.
 ---
 
 <background_information>

package/src/skills/codex/ad-domain/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: ad-domain
 description: Lazily create or update `CONTEXT.md` (Layer 2 — ubiquitous language per Evans 2003) at the repo root, or `CONTEXT-MAP.md` plus per-context `CONTEXT.md` for multi-context repos. Captures canonical project-specific nouns, the aliases to avoid, the relationships between them, and resolved ambiguities. Triggers on "domain term", "ubiquitous language", "glossary", "what should we call", "naming drift", "canonical noun", "_Avoid_", "/ad-domain", or whenever a grilling/spec/architecture session resolves a vocabulary question. Lazy by design — file only exists when there is something to write.
+summary: Lazy lifecycle owner of `CONTEXT.md` (Layer 2 — ubiquitous language per Evans 2003). Captures canonical project-specific nouns with aliases-to-avoid, relationships, and flagged ambiguities. Single-context or `CONTEXT-MAP.md` multi-context.
 ---
 
 <background_information>

package/src/skills/codex/ad-grill/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: ad-grill
 description: Interview-before-research grilling session that challenges a fuzzy ask against the existing codebase, sharpens vocabulary against `CONTEXT.md`, and resolves the design tree branch by branch. One question at a time, codebase-first when an answer is in code, with each question carrying a recommended answer. Triggers on "grill me", "interview me", "stress test the plan", "challenge my assumptions", "before implementing", "ask me questions", "fuzzy ask", "sharpen the question", "what should I clarify", "/ad-grill". Routes to `ad-ground` once the question is research-ready, `ad-tdg` once the technique is settled, `ad-spike` for technique discovery, `ad-diagnose` for debugging.
+summary: Interview-before-research grilling session — one question at a time with recommendation, codebase-first, sharpens vocabulary against `CONTEXT.md`, captures terms via `ad-domain` and decisions via `ad-adr` (three-criteria rule). Upstream of `ad-ground`.
 ---
 
 <background_information>

package/src/skills/codex/ad-ground/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: ad-ground
 description: Four-source pre-implementation research — official docs, validated open-source examples, in-repo patterns, and git history — then synthesize a happy path and gate any deviation with an irrefutable justification before code is written. Auto-invokes on non-trivial work, refactors, library or pattern selection, "research before coding", "before implementing", "which library", "which pattern", "how to approach", "ground before coding". Workflow-operational counterpart to WORKFLOW.md §4 (Find the Happy Path) and §5 (Ground in Real Patterns).
+summary: Four-source pre-implementation research (docs / OSS / in-repo / git history) + happy-path synthesis + deviation gate. WORKFLOW §4 + §5.
 ---
 
 <background_information>

package/src/skills/codex/ad-hooks/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: ad-hooks
 description: Scaffold deterministic quality gates per WORKFLOW.md §11 — pre-commit (lint, format, secret-scan), pre-push (build, unit, integration). Detects the project's stack and recommends a hook runner (Husky / lefthook / pre-commit / native), scaffolds the runner config, and updates AGENTS.md Quality Gates. Use when the user wants to wire hooks, configure pre-commit / pre-push, set up quality gates, prevent --no-verify bypass, or close the WORKFLOW §11 advisory-vs-deterministic gap. Opt-in skill; not auto-installed.
+summary: Scaffold deterministic quality gates per WORKFLOW §11 — pre-commit + pre-push, runner detected from stack signals.
 ---
 
 <background_information>

package/src/skills/codex/ad-merge/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: ad-merge
 description: Evaluate and merge a GitHub pull request per ADR-0025. Four phases — preflight (`gh` auth + PR resolution), evaluate (CI / fresh-context review / linked task / unresolved comments / mergeability), decision (CI green = hard gate; others = warnings yielding to user), merge via `gh pr merge` with auto-detected mode (squash / rebase / merge) and `--delete-branch`. Helper posture per ADR-0025 §3 — surfaces warnings, does not block on the senior engineer's judgment. Triggers on "merge this PR", "evaluate the PR", "is it mergeable", "gh pr merge", "/ad-merge".
+summary: Evaluate and merge a GitHub pull request per ADR-0025. Four phases — preflight, evaluate (CI / fresh-context review / linked task / unresolved comments / mergeability), decision (CI green = hard gate; others = warnings), merge with auto-detected mode + `--delete-branch`.
 ---
 
 <background_information>

package/src/skills/codex/ad-next/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: ad-next
 description: Survey the project's state across the five-layer artifact stack and recommend prioritized next actions, modeled on `flutter doctor`. Use when the user asks "what's next", "next step", "where am I", "project status", "doctor", "what should I do", "audit my workflow". Read-only; complements `ad-audit` (drift detection, a different question). Profile-aware — `poc` suppresses Layer 3/4 noise, `team`/`mature` run the full survey.
+summary: State survey + prioritized next-action recommendations across the five-layer artifact stack. Read-only navigation aid (`flutter doctor` pattern).
 ---
 
 <background_information>

package/src/skills/codex/ad-philosophy/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: ad-philosophy
 description: Universal agent behavior and documentation discipline — think before coding, ground in real patterns, prefer simplicity, make surgical changes, define verifiable goals, verify before claiming done, and write documentation that captures only definitions and decisions. Auto-invokes on non-trivial changes, refactors, debugging, "think before coding", "ground before coding", "verify done", "before implementing", on documentation work — "writing docs", "writing readme", "writing architecture", "writing adr", "writing task", "audit docs" — or whenever the task is ambiguous enough that guardrails matter.
+summary: Universal agent guardrails (think before coding, verify before claiming done). Auto-loads on non-trivial work.
 ---
 
 <background_information>

package/src/skills/codex/ad-pr/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: ad-pr
 description: Open a GitHub pull request with a uniform body shape per ADR-0024. Four phases — preflight (`gh` auth + branch pushed), scope assembly (commits + diff vs base), draft body (Summary / Test plan / Links), open + report URL. Title format = Conventional Commits, type inferred from the dominant commit type in the range. `gh` CLI soft-fail with install hint. Triggers on "open a PR", "create a pull request", "submit a PR", "gh pr create", "/ad-pr".
+summary: Open a GitHub pull request with a uniform body shape (Summary / Test plan / Links) per ADR-0024. Four phases — preflight (`gh` auth + branch pushed), scope assembly, draft body, open + report URL. Title format = Conventional Commits.
 ---
 
 <background_information>

package/src/skills/codex/ad-review/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: ad-review
 description: Fresh-context code review per WORKFLOW §10 — assemble the diff plus the relevant spec slice (AGENTS.md, applicable ADRs, the task's Acceptance Criteria), perform a /clear handoff to a clean session, return a structured findings list. Use when the user wants to review a diff, branch, PR, or recent commits against the project's spec, audit for bugs / coupling / edge cases / spec drift, or run a §10 senior-reviewing-junior pass. Adversarial framing — never emits an "approve" verdict.
+summary: Fresh-context code review per WORKFLOW §10 — assemble handoff, return structured findings.
 ---
 
 <background_information>

package/src/skills/codex/ad-skill/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: ad-skill
 description: Draft a new Claude Code or Codex skill at .claude/skills/<name>/SKILL.md (or .agents/skills/<name>/SKILL.md for Codex), using the Anthropic Skills format. Use when the user wants to create, write, draft, or scaffold a custom skill for an agentic coding tool. Asks one question per missing field; never invents skill names or triggers.
+summary: Draft a new Claude Code or Codex skill at the appropriate path.
 ---
 
 <background_information>

package/src/skills/codex/ad-spec/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: ad-spec
 description: Draft a feature-level specification at doc/specs/NNNN-<slug>.md following the five-layer artifact stack (Constitution → Domain → Spec → Plan/Decisions → Code). Adapts GitHub Spec Kit's mandatory sections (User Scenarios, Requirements, Success Criteria) to the kit's documentation discipline. Use when the user wants to write, draft, scaffold, or open a feature spec, PRD, product requirements, feature brief, user stories, or success criteria. Status starts at draft.
+summary: Draft a feature spec at `doc/specs/NNNN-<slug>.md` (Spec Kit-aligned mandatory sections). Layer 3 of the five-layer artifact stack.
 ---
 
 <background_information>

package/src/skills/codex/ad-spike/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: ad-spike
 description: Scaffold a staged spike with golden fixtures per WORKFLOW.md §14, for cases where the spec is clear but the technique is uncertain across multiple plausible approaches. Four stages — discovery, golden fixture, pipeline with gates, two-layer evaluation. Use when the unknown is *how*, not *what*. Triggers on "spike", "uncertain technique", "which library", "CV pipeline", "evaluate approaches", "ground truth", "golden fixture", "staged pipeline", "debug per stage". Routes to `ad-ground` if the *how* is routine and a single happy path is obvious.
+summary: Staged spike with golden fixtures per WORKFLOW §14. Discovery + fixture + pipeline-with-gates + two-layer evaluation, when the *technique* is uncertain across multiple plausible approaches.
 ---
 
 <background_information>

package/src/skills/codex/ad-task/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: ad-task
 description: Draft a new task tracking file at doc/tasks/NNNN-<short-slug>.md, using a checkbox-toggle + append-only-Notes format optimized for LLM editing. Use when the user wants to create, draft, scaffold, or open a task, ticket, work item, or backlog entry tracked in the repo. Status starts at proposed.
+summary: Draft a new task at `doc/tasks/NNNN-<slug>.md`.
 ---
 
 <background_information>

package/src/skills/codex/ad-tdg/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: ad-tdg
 description: Outcome-based prompting per WORKFLOW.md §9. Give the agent the finish line first, not the path. Five steps — confirm regime, ground truth pair, Test Dependency Map, three approaches, pick by one criterion, implement and verify. Triggers on "outcome-based", "TDG", "ground truth", "expected output", "three approaches", "pick by criterion", "test dependency map", "TDM", "before modifying", "tests covering this file", "give the finish line". Routes to `ad-spike` if the technique itself is uncertain. No file written; output is the verified implementation that lands through normal commits.
+summary: Outcome-based prompting per WORKFLOW §9. Ground truth pair + Test Dependency Map + three approaches + single-criterion selection, when the technique is known but the implementation strategy is uncertain.
 ---
 
 <background_information>