skills

Goal-statement or direct-invocation queue driver for agile-workflow. Use when a harness goal or user request says to run autopilot, drain ready work, finish an epic, continue through .work/active/, or make autonomous progress on the substrate. Reads .work/active/, picks ready items by depends_on and stage, delegates to design, implement, and review skills, commits transitions, and repeats until the scope is done or blocked. Before reporting complete, runs a final peer-review/fresh-context completion pass and fixes or files accepted findings. No /loop or --resume mechanics; the harness goal/continuation feature owns long-running persistence. Epic-scoped by default; --all drains all active work; free-text scope directives are allowed.

Deep multi-angle correctness bug hunt. Use when the user asks to "scan for bugs", "bug hunt", "deep bug audit", "find hidden bugs", "find race conditions", or audit lurking correctness issues. Fans parallel scanner agents across relevant domains such as concurrency, async, state, resource leaks, time/numbers, error handling, data layer, and language footguns. Standalone mode writes a scored report; gate mode binds to a release bundle and emits .work/active/stories/ items with gate_origin:bugs. Distinct from gate-security, review, perf-design, and repo-eval.

Multi-lane, decomposition-first codebase scan campaign for agile-workflow. Use when the user asks for a deep code scan, comprehensive audit, whole-repo issue hunt, or organized fix plan that spans multiple lanes such as correctness, tests, performance, security, quality, structure, or architecture. Interviews for goal, lanes, rigor, scanner tier, and altitude bands; maps the repo from leaf to system scope; fans out scoped scanners; runs a review gauntlet; and consolidates surviving findings into one fix epic. For a single-domain scan, route to the specialist instead.

ALWAYS invoke this skill when the user asks to design e2e tests, audit or bootstrap the e2e program, or work on a [e2e-test]/[testing] feature at stage:drafting. Designs service-level-mocked e2e coverage, writes the design into the feature body, spawns child stories with depends_on chains, and advances drafting to implementing. Supports golden-path, failure-mode, chaos, and fuzzing coverage, plus --bootstrap and --audit modes.

ALWAYS invoke this skill when the user asks to design, decompose, or pick up an epic at stage:drafting. Reads the epic, foundation docs, and codebase; identifies child feature arcs; writes feature files with parent and depends_on metadata; updates the epic body with the realized decomposition; and advances drafting to implementing. When ux-ui-design is installed, includes mockup planning for net-new screens and journeys.

ALWAYS invoke when the user asks to design or flesh out a feature at stage:drafting; do not write design prose inline. Designs the feature inside its agile-workflow item body, grounded in foundation docs and code, then spawns child stories with depends_on chains and advances drafting to implementing. Use for greenfield features without [refactor], [perf], [prose], or [research] tags; route [refactor] to refactor-design, [perf] to perf-design, [prose] to prose-author, [research] to the agentic-research research-orchestrator, and epic decomposition to epic-design. UI/UX mockups are fallback here, inherited from the parent epic when available.

Cruft gate that scans the items bound to a release for AI-accumulated debris (dead code, stale comments, compatibility shims, defensive bloat, over-abstraction) introduced or revealed by the bundle. Delegates the full scan to a deep cleanup scanner agent which runs language-aware detection plus heuristic pattern-matching, then returns findings. The orchestrator converts findings into items in .work/active/ with gate_origin:cruft and tags:[cleanup]. Auto-triggers during /agile-workflow:release-deploy.

Documentation gate that enforces the rolling-foundation principle. Delegates the full drift detection to a deep documentation scanner agent which scans the bundle's changes for foundation-doc drift (assertions in docs/ that no longer match implementation), changelog gaps, README staleness, and skill/pattern-skill staleness. The orchestrator converts findings into items in .work/active/ with gate_origin:docs and tags:[documentation]. Auto-triggers during /agile-workflow:release-deploy.

Patterns gate that scans the bundle's changes for reusable code structures. Delegates the full discovery to a deep pattern scanner agent which identifies recurring shapes (3+ occurrences) introduced or revealed by the bundle, names them, documents them with concrete file:line examples, and returns pattern drafts. The orchestrator writes detailed pattern skills to .agents/skills/patterns/ (the single source of truth) with optional Claude mirrors, updates the index, also generates the hook-loaded .agents/rules/patterns.md digest (a do-not-hand-edit slug+one-liner index that points back at the patterns skill for detail), and produces a tracking item with gate_origin:patterns. Auto-triggers during /agile-workflow:release-deploy as the final gate.

Refactor gate that discovers scan-rule libraries declared in the host project (default roots: {project}/.agents/skills/scan-*/SKILL.md and {project}/.claude/skills/scan-*/SKILL.md; configurable via CONVENTIONS.md: gate_refactor_scan_library_roots), loads every discovered library, checks the release bundle's changed files against all loaded rules, and produces findings as items with gate_origin:refactor; routing tag declared per library (libraries whose fixes are behavior-preserving declare findings-route:refactor; behavior-changing libraries declare no route — findings emit untagged and route through normal feature/story design). Rule libraries are deployment-local — the gate ships the mechanism; adopters supply the rules. Auto-triggers during /agile-workflow:release-deploy when the host project opts in via CONVENTIONS.md: gates_for_release: [..., refactor, ...]. No-libraries behavior: graceful skip (logs "no scan-* libraries discovered" and continues). Item-producer, NOT a pass/fail report.

Security gate that scans items bound to a release and produces items as findings. Delegates the full audit to a deep security scanner agent which discovers stack, picks relevant security domains (auth, injection, secrets, deps, API, infra, crypto, data protection, error handling), audits the bundle's code changes, and returns findings. The orchestrator converts findings into items in .work/active/ with gate_origin:security and appropriate tags. Auto-triggers during /agile-workflow:release-deploy quality-gate stage. Item-producer, NOT a pass/fail report.

Test-quality gate that scans items bound to a release for test coverage gaps. Delegates the full analysis to a deep test scanner agent which derives expected coverage from each bound item's acceptance criteria (NOT from implementation code), maps existing test coverage, identifies gaps, and returns findings. The orchestrator converts findings into gate_origin:tests items in .work/active/. Auto-triggers during /agile-workflow:release-deploy.

Backlog hygiene sweep for the agile-workflow substrate. Use when the user asks to groom the backlog, audit backlog hygiene, find stale/dead/duplicate/superseded backlog items, or clean up .work/backlog/. Triggers on "groom the backlog", "backlog hygiene", "find stale items", "what's dead in the backlog", "any duplicates in the backlog". Reads .work/backlog/, classifies items (DONE / SUPERSEDED / DUPLICATE / STALE / MERGEABLE / VALID) from date/metadata signals plus a grounded semantic pass, and writes a triage REPORT of proposals. Propose-not-prune: it never auto-archives, merges, or deletes — every disposition is operator-confirmed per finding, and dead items route through the project's terminal-tier retention convention. Opt-in and inert when not invoked; the staleness face is additionally inert unless backlog_staleness_days is configured.

ALWAYS invoke when the user asks to implement substrate items, work through stage:implementing items, drain the queue, or implement a feature/epic scope. Default implementation path; call implement directly only when the user says "inline". Builds a depends_on graph, bundles related work, chooses wave width and worktree isolation, and dispatches implementation sub-agents when useful. This skill authorizes sub-agents, including large non-overlapping write paths when ownership and verification make that safe. Advances parents whose children all reach stage:review.

ALWAYS invoke this skill when the user explicitly asks to implement a substrate item inline OR the delivery is tiny (about 50 LoC or less, two files or fewer, no coordination) OR the deliverable is no-code prose (a [prose] item — any size, as long as it needs no coordination) — for any larger or default *code* work prefer /agile-workflow:implement-orchestrator. Inline single-stride implementation of a substrate item at stage:implementing. Reads the design embedded in the item body, writes code per the spec, runs build+tests, advances stage implementing to review, and updates the item body with implementation notes. Triggers on "implement this inline", "implement this item inline", "just do it inline", or a very small explicit delivery.

ALWAYS invoke when the user asks to profile performance, find bottlenecks, optimize code, make something faster, or design a [perf]-tagged feature; do not optimize inline. Discovery mode profiles likely hot paths and emits substrate items per bottleneck. Per-feature mode designs an existing stage:drafting [perf] feature, writes the plan and benchmark scaffolds into the feature body, spawns child stories, and advances drafting to implementing. Uses the hierarchy: algorithmic/data model, I/O, data locality and CPU/cache behavior, language/runtime idioms, then parallelism. Route greenfield work to feature-design and refactors to refactor-design.

Cross-domain performance *idea* generator — a speculative brainstorm engine, not a profiler. Use when the user asks for performance ideas, optimization angles, "how could this be faster", "what would a game engine / database / GPU do here", a perf brainstorm, "ways to speed this up", or a broad sweep of possible speedups. Fans parallel highest-thinking-model scouts across strategy lenses (algorithmic, memory/locality, parallelism/SIMD, GPU, caching, I/O, distributed, game-engine, database internals, compiler/runtime, approximation) through scanner agents, each surfacing *candidate* optimizations borrowed from demanding domains as unvalidated hypotheses — never asserting gains are real. Then a different model class (via peeragent, or a fresh max-effort sub-agent) prunes weak ideas and surfaces missed angles. Writes a ranked report and parks ideas to .work/. Distinct from perf-design (which measures and asserts — hand validated ideas there), bug-scan (correctness), and refactor-design (structure).

agile-workflow principles — code-design (Ports & Adapters, Single Source of Truth, Generated Contracts, Fail Fast) and substrate-execution (Item-IS-the-Work, Rolling-Foundation, Late-Binding). Auto-loads when designing modules, defining interfaces, writing or implementing code, scoping work in the substrate, advancing stages, scoping releases, or any time the agile-workflow design/implement/review skills are active.

Create or update a project-specific refactor-conventions catalog for agile-workflow. Explores the repo, researches stack-specific best practices, interviews the user about stylistic preferences and structural refactor preferences, writes concise style rules into the canonical AGENTS.md, writes detailed refactor convention references under .agents/skills/refactor-conventions/, maintains optional Claude mirrors, and leaves refactor execution to /agile-workflow:refactor-design. The generated catalog extends refactor-design's sensible defaults; it does not replace them or create standalone plan docs.

ALWAYS invoke this skill when the user asks to scan for refactor opportunities, plan a refactor, or design a [refactor]-tagged feature. Discovery mode scans code smells, separates pure refactors from behavior changes, and emits substrate items. Per-feature mode plans an existing [refactor] feature at stage:drafting, writes the plan into the feature body, spawns child stories with depends_on chains, and advances drafting to implementing. Uses sensible built-in refactor heuristics by default, and extends them with a project-specific refactor-conventions catalog when present.

ALWAYS invoke this skill when the user asks to research a library, API, SDK, or technology choice — do not just web-search and summarize inline. Researches external libraries, APIs, SDKs, and patterns to inform design and implementation. Investigates options, evaluates trade-offs against project needs, and produces both a research document and an auto-loading reference skill. Use before designing features that depend on unfamiliar technology, when choosing between options, or when API assumptions need verification. Triggers on "research X", "compare X vs Y", "what library should I use for Y", "investigate an API", and "evaluate an SDK".

ALWAYS invoke this skill when the user asks to review a substrate item, an item is at stage:review, or the user says "review this". Substrate-first: reviews tracked items, files follow-up items, and advances or bounces them. Also supports out-of-band reviews of branches, commits, PRs, working trees, or unpushed commits without substrate side effects. Uses fast, standard, and deep lanes; deep review runs in fresh context when useful. Triggers on "review item X", "review this", "review this item", "deep review", "is this ready", and "verdict on this item".

ALWAYS invoke this skill when the user asks to scope, promote, formalize, cluster, or track new work — do not start drafting items inline. Promotes ideas from .work/backlog/ or fresh user requests into the active tier as epics, features, or stories with declared dependencies. Use when scoping new work, formalizing a new direction, clustering backlog, or promoting an idea into tracking. Triggers on "scope this", "scope it", "let's scope", "scope this item", "scope the backlog", "promote this", "let's track this", "this should be a feature/epic/story", or any request to formalize a new direction. For vision/spec/architecture changes, also rolls foundation docs forward in the same stride.

Z.ai-powered web research for Pi: web search, URL/PDF/JSON/API reading, and GitHub repo deep-read. Reaches for five agent tools — zai_web_search (Z.ai web search), fetch_content (webReader pages, local PDF extraction, direct JSON/API fetches, and article extraction for noisy docs), search_repo_docs / get_repo_structure / read_repo_file (Z.ai zread over GitHub). Use whenever work needs current or version-sensitive information, structured API metadata, or deep-reading a GitHub repo without cloning. Auth comes from the configured Z.ai (zai) provider key.

Dynamic research-engagement entry point for the .research/ substrate. Reads the engagement's dials (scope_authority, verification_rigor), sets them with the user at kickoff, discovers fan-out topology from the seed (one inline pass to N specialists), and walks the ARD decision-graph at the dialed verification depth. Use for any grounded research engagement: focused single-pass, breadth survey, multi-specialist decomposition, or program-scale. Honors the ARD SPEC invariants (anti-fabrication floor, verification stack, registration); this is one deployment of ARD in a portable agent-skill system.

Bootstrap or sync the agile-workflow substrate. Auto-detects repo state: bootstrap creates .work/, CONVENTIONS.md, the canonical AGENTS.md section, Claude compatibility, work-view, and migrated items; sync refreshes plugin-owned artifacts plus optional skill catalog mirrors while preserving user-owned CONVENTIONS.md, refactor rules, and substrate state. `convert --update` performs one-pass artifact alignment. Discovery-driven: sweeps both skill roots to detect bespoke DIY skills that overlap plugin-owned concepts (patterns, refactor conventions, plan-doc generators) and offers to converge them to the canonical layout, deferring to the owning skill for placement. Checks inbound references before moving any path and rewrites or shims them. Always asks whether destructive cleanup is in scope before deleting, moving, or replacing legacy artifacts; preserve-only is the default.

The ARD anti-fabrication discipline bundle — the six core sections (source-bound citation, substrate test, no-footnote-fabrication, per-source attestation, contradiction-handling + seek-disconfirming, composed-claim) plus two supplementary disciplines (per-claim epistemic-status markers, corrections-vs-reversals) that bind any research-authoring context in this repo's .research/ substrate. This skill wraps ard-core/kernel/discipline.md (the single source of truth); the research-orchestrator reads that file and inlines it into every authoring dispatch so the discipline reaches sub-contexts. On the light path, read ard-core/kernel/discipline.md explicitly before authoring.

Discover an adopter's pre-existing research and bootstrap it into ARD parity. Use when a repo has research authored outside ARD (scattered docs, a wiki, a differently-shaped folder) but no conformant .research/ substrate. Auto-detects: absent .research/ bootstraps the substrate (CONVENTIONS, tier layout, per-corpus INDEX); an existing one syncs (validate + report drift, never overwrite). Sweeps the repo for foreign research, classifies it (operator-confirmed), routes raw sources to reference/ and claim-bearing syntheses to a holding area, then hands each synthesis to the research-orchestrator refresh branch for per-artifact rigor-uplift. Preserve-only default; content-integrity gate before any destructive op. The front half of ARD adoption that runs before rigor-uplift.

Operator-confirmed emission gate: takes a completed research engagement (analysis slug or campaign dir) and proposes .work/ items grounded in its actionable findings. Each emitted item carries research_origin metadata plus a body citation back to the .research/ artifact. Silent no-op when .work/CONVENTIONS.md is absent. NEVER auto-fires — always operator-invoked and always asks before writing.

Run long commands in the background and get woken when they finish, poll a command until a condition holds, and manage the resulting job registry. Reaches for three agent tools — background (run detached, wake on exit or first pattern match), monitor (poll until exit_zero / exit_nonzero / stdout_matches / stdout_not_matches, or timeout), and jobs (list, tail, status, cancel). Use whenever work involves a long-running command (test suite, build, deploy, CI run, watch/serve) or waiting on a state (CI going green, a file or port appearing, a log line) where blocking the turn would waste it. The tools are pi-runtime-only: this skill is the portable description of when and how to use them; they register via the pi extension and degrade to informational in harnesses that lack it.

Scaffold a single-person work-tracking repo from an interview about one job's real tools. Use when the user wants to set up or regenerate a worklog repo that reads tickets, chat, transcripts, docs, or notes; tracks goals and tasks in flat files; runs a start-of-day sync; plans against long-run goals; logs work; updates tickets; and generates self-contained HTML reports. This is a generator: it asks for a target path, protects existing state, writes concrete operating guides for the configured tools, and does not install itself into the generated repo.

Repo-local style contract for skills in this repository. Use when writing, updating, reviewing, or auditing any SKILL.md, agents/openai.yaml, plugin skill, or .agents/skills reference skill in this repo. Enforces portable frontmatter, Codex metadata placement, progressive disclosure, and harness-neutral wording.

ALWAYS invoke this skill when the user wants to capture an idea for later without derailing current work — do not start working on the parked idea inline. Captures short ideas, richer context notes, or roadmap-style multi-arc thoughts into the agile-workflow backlog under .work/backlog/ with minimal frontmatter. Use when a new direction surfaces mid-flow and you shouldn't derail what's currently in progress. Triggers on "park this", "park it", "remind me about X", "add to backlog", "we should consider Y", "save this for later", "let's not lose this".

Finds bold architectural reconceptions and writes markdown refactor proposals, without creating agile-workflow epics or tracked work. Use only when the user explicitly asks for a bold refactor, architectural rethink, deep simplification, or "what single idea would make this code much simpler?" Applies conceptual lenses such as elimination, unification, inversion, algebraic design, declarative design, and domain crystallization, then writes bold-refactor-report.md with accepted proposals, risks, sequencing, and suggested implementation slices.

Deep multi-angle correctness bug hunt that writes a markdown report only. Use when the user asks to "scan for bugs", "bug hunt", "deep bug audit", "find hidden bugs", "find race conditions", or audit lurking correctness issues without adopting agile-workflow. Fans parallel read-only scanner sub-agents across relevant domains such as concurrency, async, state, resource leaks, time/numbers, error handling, data layer, and language footguns, then aggregates verified findings into bug-scan-report.md.

Multi-lane, decomposition-first codebase scan campaign that writes markdown docs only. Use when the user asks for a deep code scan, comprehensive audit, whole-repo issue hunt, or organized remediation plan spanning multiple lanes such as correctness, tests, performance, security, quality, structure, or architecture without adopting agile-workflow. Interviews for goal, lanes, rigor, scanner tier, and altitude bands; maps the repo; fans out scoped scanners; runs a review gauntlet; and consolidates findings into a code-audit scan folder of markdown documents.

Cross-domain performance idea generator that writes a markdown report only. Use when the user asks for performance ideas, optimization angles, "how could this be faster", "ways to speed this up", a perf brainstorm, or a broad sweep of possible speedups without adopting agile-workflow. Fans parallel high-effort scout sub-agents across strategy lenses such as algorithmic, memory/locality, parallelism, GPU, caching, I/O, distributed systems, game-engine, database internals, compiler/runtime, and approximation. Produces perf-scout-report.md with ranked unvalidated hypotheses and validation paths.

Multi-dimensional codebase evaluation with verified scoring that writes a markdown scorecard only. Use when the user asks to evaluate, audit, score, grade, or review a repository holistically without adopting agile-workflow. Launches parallel exploratory sub-agents, cross-checks claims with direct verification, and produces calibrated 1-10 scores across architecture, code quality, error handling, testing, documentation, CI/CD, security, developer experience, and maintainability.

Standalone security review and vulnerability scan that writes a markdown report only. Use when the user asks for a security review, security scan, vulnerability audit, threat-oriented code review, dependency/security hygiene pass, or to inspect auth, injection, secrets, API security, infrastructure, cryptography, data protection, or logging risks without adopting agile-workflow. Discovers the stack, selects relevant security domains, runs read-only domain audits, classifies severity, and writes security-scan-report.md.

Standalone test-quality and coverage-gap scan that writes a markdown report only. Use when the user asks to audit tests, find missing test coverage, review test quality, identify weak assertions, stale fixtures, over-mocking, flaky tests, or derive test gaps from specs/contracts without adopting agile-workflow. Maps behavioral contracts, existing tests, gaps, and recommended test additions into test-scan-report.md.