nklisch-pi-agile-workflow

内容来源：README.md（说明文档） · 原始地址 · 查看安装指南

原始内容

# nklisch/skills

A software development workflow suite for Claude Code, OpenAI Codex, and Pi —
work tracking, UI/UX design, grounded research, markdown code audits, and
standalone utility skills, designed to tee up autonomous agent runs that
actually ship the right thing.

Available as **Claude Code plugins**, **Codex plugins**, and **Pi packages**.

## Install

All supported plugins ship through three channels. The shared `skills/`
directory is the portable surface; each harness adds only its native metadata or
ergonomics.

### Claude Code

```bash
/plugin marketplace add nklisch/skills

# Choose one mutually exclusive .work/ owner:
/plugin install agile-workflow@nklisch-skills    # structured work tracking + autopilot
# or: /plugin install workbench@nklisch-skills   # flexible requirements-first delivery

/plugin install ux-ui-design@nklisch-skills      # standalone mockup-first UI design
/plugin install code-audit@nklisch-skills        # standalone markdown code audits
/plugin install nates-toolkit@nklisch-skills     # standalone utility skills
/plugin install agentic-research@nklisch-skills  # grounded research discipline
/plugin install agent-coordination@nklisch-skills # sparse cross-agent ledger
```

### OpenAI Codex

```bash
codex plugin marketplace add https://github.com/nklisch/skills

# Choose one mutually exclusive .work/ owner:
codex plugin install agile-workflow
# or: codex plugin install workbench

codex plugin install ux-ui-design
codex plugin install code-audit
codex plugin install nates-toolkit
codex plugin install agentic-research
codex plugin install agent-coordination
```

### Pi

```bash
# Install the compatible default Pi package set (agile-workflow-based)
pi install git:github.com/nklisch/skills

# Or install individual published packages. Choose one .work/ owner:
pi install npm:@nklisch/pi-agile-workflow
# or: pi install npm:@nklisch/pi-workbench

pi install npm:@nklisch/pi-ux-ui-design
pi install npm:@nklisch/pi-code-audit
pi install npm:@nklisch/pi-nates-toolkit
pi install npm:@nklisch/pi-agentic-research
pi install npm:@nklisch/pi-agent-coordination
pi install npm:@nklisch/pi-background-tasks
pi install npm:@nklisch/pi-zai-research

# External companion plugin: peeragent lives in its own repo/package
pi install git:github.com/nklisch/peeragent@v0.4.1

# Local checkout/development installs
pi install -l .
pi install -l ./plugins/agile-workflow
pi install -l ./plugins/workbench
pi install -l ./plugins/ux-ui-design
pi install -l ./plugins/code-audit
pi install -l ./plugins/nates-toolkit
pi install -l ./plugins/agentic-research
pi install -l ./plugins/agent-coordination
pi install -l ./plugins/background-tasks
pi install -l ./plugins/zai-research
```

Pi packages can load executable extensions in addition to shared skills. The root
Git install loads the compatible default set built around `agile-workflow`;
`workbench` is an alternative `.work/` owner and must be installed individually
instead. The deprecated `workflow` plugin and external marketplace companions
such as `peeragent` are not included. Install alternatives and companions from
their own package roots. Install from trusted sources;
`agile-workflow` includes a Pi-native `/aw` command for queue inspection and
workflow handoffs.

## The supported plugins

| Plugin | What it does | Guide |
|---|---|---|
| **agile-workflow** | Substrate-driven work tracking. Items as files in `.work/` with YAML frontmatter, late-binding releases, gates that produce items, goal-backed autopilot queue runner. | [docs/agile-workflow-guide.md](https://github.com/nklisch/skills/blob/HEAD/docs/agile-workflow-guide.md) |
| **workbench** | Flexible requirements-first delivery. A lightweight `.work/` ledger references grounded `.research/` evidence and interactive `.mockups/` walkthroughs; natural language drives research, design, implementation, review, scans, and release summaries. | [plugins/workbench/README.md](https://github.com/nklisch/skills/blob/HEAD/plugins/workbench/README.md) |
| **ux-ui-design** | HTML/CSS/JS mockup-first UI design. Throwaway single-file mockups in `.mockups/` for alignment before any production code. Loosely integrated with agile-workflow. | [docs/ux-ui-design-guide.md](https://github.com/nklisch/skills/blob/HEAD/docs/ux-ui-design-guide.md) |
| **code-audit** | Standalone markdown-first code audits — deep multi-lane scans, bug/security/test scans, perf scouting, bold refactor proposals, and repo scorecards without `.work`. | [plugins/code-audit/README.md](https://github.com/nklisch/skills/blob/HEAD/plugins/code-audit/README.md) |
| **nates-toolkit** | Standalone utility skills, no workflow lock-in — explain in plain language, reflect on tool & skill usage, author skills, and audit skill artifacts. | [plugins/nates-toolkit/README.md](https://github.com/nklisch/skills/blob/HEAD/plugins/nates-toolkit/README.md) |
| **agentic-research** | Grounded, verifiable AI research discipline. Produces `.research/` attestations and syntheses with citation/verification gates, and pairs with agile-workflow when research should ground a work item. | [plugins/agentic-research/README.md](https://github.com/nklisch/skills/blob/HEAD/plugins/agentic-research/README.md) |
| **agent-coordination** | Sparse cross-agent coordination ledger for shared repos — deliberate claims, handoffs, blockers, review summaries, and merge summaries without turning Discussions into chat. Lightly aware of agile-workflow `.work` IDs when present. | [plugins/agent-coordination/README.md](https://github.com/nklisch/skills/blob/HEAD/plugins/agent-coordination/README.md) |
| **background-tasks** | Pi-native background command, monitor, and job-registry tools. | [plugins/background-tasks/README.md](https://github.com/nklisch/skills/blob/HEAD/plugins/background-tasks/README.md) |
| **zai-research** | Pi-native Z.ai web, URL/PDF, JSON/API, and GitHub repository research tools. | [plugins/zai-research/README.md](https://github.com/nklisch/skills/blob/HEAD/plugins/zai-research/README.md) |

## External companion plugins

| Plugin | Pi install | What it does |
|---|---|---|
| **peeragent** | `pi install git:github.com/nklisch/peeragent@v0.4.1` | Cross-harness peer delegation and peer review. Pi loads the `peer` and `peer-review` skills from peeragent's package and uses its bundled wrapper/binaries to call Codex, Claude Code, Gemini through Antigravity, or Z.AI GLM 5.2 through Pi. |

The package release procedure is documented in
[docs/npm-publishing.md](https://github.com/nklisch/skills/blob/HEAD/docs/npm-publishing.md). Choose one `.work/` owner per
project: `agile-workflow` provides a structured stage-and-gate system, while
`workbench` provides a smaller requirements-first ledger and can migrate an
existing agile-workflow substrate through `/workbench:setup`. The standalone
`ux-ui-design` plugin remains available for projects that want its larger,
specialized mockup system.

> **Deprecated:** the `workflow` plugin (doc-driven, `docs/designs/`-as-artifacts)
> is **deprecated and no longer supported.** Existing projects on it still
> work, but no new features or fixes will land. New projects should use
> `agile-workflow`. To migrate an existing `workflow` project, run
> `/agile-workflow:convert` — it detects the legacy layout and migrates
> automatically. The old guide at [docs/workflow-guide.md](https://github.com/nklisch/skills/blob/HEAD/docs/workflow-guide.md)
> remains for reference.

## agile-workflow

A full substrate skill set for tracking and shipping work via markdown files in
`.work/`. See [docs/agile-workflow-guide.md](https://github.com/nklisch/skills/blob/HEAD/docs/agile-workflow-guide.md)
for the full guide and current catalog.

### Pipeline

```
ideate → convert → epicize           ← project bootstrap (greenfield)
    ↓
park / scope / fix                   ← capture & promotion (agent picks)
    ↓
epic-design --only-questions --all   ← align on big choices (also runs UI mocks)
feature-design --only-questions --all   ← drill in per feature
    ↓
Goal: Use agile-workflow autopilot to drain --all
    ↓
release-deploy <version>             ← bind, gate, ship
```

The two `--only-questions` passes are the killer move — front-load every
directional choice and mock so autopilot runs without guessing.

### Bootstrap (user-invocable)

| Skill | What it does |
|-------|-------------|
| **ideate** | Foundation-docs workshop. Produces VISION.md, SPEC.md, ARCHITECTURE.md that encode rolling-foundation from day one. |
| **convert** | Bootstrap the `.work/` substrate. Detects project shape (legacy workflow-plugin / ad-hoc / no-tracking / greenfield), seeds initial items, writes the canonical AGENTS.md section, keeps CLAUDE.md as a symlink/shim for compatibility, runs the conventions interview, copies `work-view`, produces MIGRATION_REPORT.md. Idempotent via `--update`. |
| **epicize** | Decompose foundation docs into multiple epics in `.work/active/epics/` with declared `depends_on` chains. |

### Capture & promotion (agent picks naturally)

| Skill | What it does |
|-------|-------------|
| **park** | Quick capture into `.work/backlog/`. Triggers on "park this", "add to backlog". |
| **scope** | Promote backlog item or fresh request into `.work/active/` as epic/feature/story. For large scope, rolls foundation docs forward in the same stride. **Batch mode** (no arg, `--all`, or NL filter) clusters the whole backlog by code seam and capability arc, proposes a structure, confirms once with the user, then writes everything. |
| **fix** | Single-stride bug repair. Reproduces, identifies root cause, writes failing test, applies minimal fix, lands story at stage:review. |

### Design family (agent picks; kind- and tag-routed)

| Skill | Triggered by | What it produces |
|-------|---|---|
| **epic-design** | epic at stage:drafting | Decomposes the epic into child features at stage:drafting with declared depends_on chains, written INTO the epic body; advances epic to implementing. Primary tier for `ux-ui-design` mocks. |
| **feature-design** | feature at stage:drafting, no specialized tag | Greenfield design — written INTO feature body, child stories spawned with depends_on, advances stage to implementing. Fallback tier for mocks. |
| **refactor-design** | feature with tags:[refactor], OR discovery (no arg / path / NL scope) | Per-feature: code-smell scan, before/after step shape, risk + rollback per step. Discovery: scans target scope, classifies findings as pure-refactor or behavior-changing, emits items. |
| **perf-design** | feature with tags:[perf], OR discovery (no arg / path / NL scope) | Per-feature: bottleneck identification, optimization hierarchy (algorithmic > I/O > idioms > parallelism), benchmark scaffolds. Discovery: picks top 3-5 likely hot paths, profiles them, emits items per bottleneck. |
| **prose-author** | feature with tags:[prose] | No-code authoring lane (authors, not a design step) — for prose deliverables with no code surface (docs, conventions, rules, copy). Verifies no real code surface (black-box test), writes brief-as-design, advances stage to implementing with no Explore / pre-mortem / question gate. Collapses to one inline stride for the common case; large multi-section prose can use drafting → implementing → review as real draft/write/revise steps. Pairs with implement's inline path. |
| **agentic-research:research-orchestrator** *(cross-plugin)* | feature with tags:[research] | Grounded ARD research engagement — an *input* that grounds other work, not a code design. Reads the item's `research_dials:` block — the commissioning subset of the registration (scope_authority, verification_rigor, intent, output_kind), with the rest settled at dispatch; scoping the item IS the dispatch act. Runs the ARD walk with verification gates inline; never binds to a release. Requires the `agentic-research` plugin (without it, `[research]` is an inert tag → `feature-design`). |

### Production + review (agent picks)

| Skill | What it does |
|-------|-------------|
| **implement** | Read item body (design is in there), write code, run build+tests, advance stage implementing → review. Single-stride sequential. |
| **implement-orchestrator** | For implementation bands: walk depends_on graph, decide bundles/waves/write-scope isolation, and dispatch implementation sub-agents when parallelism is beneficial. |
| **review** | Granularity-gated. A **story** fast-advances on the build+tests `implement` already ran — no lens pass, no peer (a second same-context review there rarely finds anything). A **feature/epic** gets a deep lens review run in a **fresh context**: cross-model via `peeragent:peer-review` when a different model class is reachable, otherwise a fresh top-class sub-agent (an Opus host spawns a *new* Opus for fresh perspective). Triages findings into items. Accepts `<id>`, `--all` / no arg (drain the review queue), or NL filter. |

### Release & autonomous

| Skill | What it does |
|-------|-------------|
| **release-deploy** | Bind items to a version, run all configured gates in CONVENTIONS.md order, wait for readiness, ship per release mapping, collapse the bundle into one release summary (bodies pruned or retained per terminal-tier retention). Idempotent. |
| **autopilot** | Goal-backed queue runner. Picks next ready item respecting depends_on, invokes the right skill, advances stage, repeats until the goal scope is done or blocked — then runs a final cross-model peer-review pass over the whole completion bundle before reporting complete. Invokable from goal text such as "Use agile-workflow autopilot to drain --all"; direct `/agile-workflow:autopilot <scope>` still works. Harness goal/continuation owns persistence, not `/loop`. |
| **bold-refactor** | Architectural reconception via conceptual lenses. Sweeps a target and produces one or more refactor EPICs with child features tagged [refactor]. User-invocable only — too aggressive for auto-trigger. |

### Gates (agent picks; produce items, NOT pass/fail reports)

Five gates fire by default during release-deploy's quality-gate stage in CONVENTIONS.md
order (default: security → tests → cruft → docs → patterns). `gate-refactor` is opt-in
— add it to `gates_for_release` when your project has scan-rule libraries installed.
Gate finding placement is configurable with `gate_finding_routing` after each
gate normalizes its own severity/priority/confidence vocabulary.

| Skill | Items produced |
|-------|---|
| **gate-security** | Security findings with `gate_origin: security`, `tags: [security]` |
| **gate-tests** | Coverage gaps + tautological-test reworks with `gate_origin: tests` |
| **gate-cruft** | Dead code / cruft cleanup items with `gate_origin: cruft` |
| **gate-docs** | Foundation-doc drift items (enforces rolling-foundation) with `gate_origin: docs` |
| **gate-patterns** | Reusable patterns extracted to `.agents/skills/patterns/` with optional Claude mirror |
| **gate-refactor** | Refactor rule-library findings with `gate_origin: refactor`; routing tag per library declaration (`findings-route:`); see the gate's SKILL.md — opt-in; discovers libraries under `gate_refactor_scan_library_roots` (default: `{project}/.agents/skills/scan-*/`, then `{project}/.claude/skills/scan-*/`); graceful no-op when no libraries installed |

### Reference

| Skill | What it does |
|-------|-------------|
| **principles** | Code-design (Ports & Adapters, SSOT, Generated Contracts, Fail Fast) + substrate-execution (Item-IS-the-Work, Rolling-Foundation, Late-Binding) principles. Auto-loads. |
| **research** | Investigate libraries, APIs, SDKs. Produces a research doc and auto-loading reference skill. |
| **refactor-conventions-creator** | Interview-based. Generates a project-specific refactor-conventions skill. |

## ux-ui-design

Seven skills for mockup-first UI/UX design. Throwaway single-file HTML
mockups in `.mockups/` for alignment before any production code. See
[docs/ux-ui-design-guide.md](https://github.com/nklisch/skills/blob/HEAD/docs/ux-ui-design-guide.md) for the full guide.

| Skill | What it does |
|-------|-------------|
| **palette** | Color + typography options as HTML previews. Locks the choice into `tokens.css`. |
| **components** | Showcase page of every button/input/card/modal in every state, plus a reusable `components.css`. |
| **motion** | Named easing-curve vocabulary, durations, springs, designed pauses — playable in browser, plus reusable `motion.css`. |
| **screens** | N (default 4) distinct HTML mockups for a single screen, plus a 2x2 comparison grid. |
| **flows** | Multi-page user flow with prev/next or hub-and-spoke chrome, plus index navigator. |
| **adopt** | Scans an existing codebase, inventories every UI surface, audits for inconsistencies, mirrors current UI into mocks OR reimagines them. |
| **ux-ui-principles** | Reference: storage layout, decision matrix, tech rule. Adds convention to project AGENTS.md on first run, with CLAUDE.md compatibility when needed. Auto-loads. |

### Plugged into agile-workflow

When both plugins are installed, mocks land at four tiers (highest tier
first wins, downstream inherits):

- **After `ideate`** → `palette` + `components`
- **During `epic-design --only-questions`** → `screens` + `flows` for cross-feature journeys
- **During `feature-design --only-questions`** → more `screens` + `flows` for per-feature surfaces
- **Ad-hoc during design work** → one-off mocks when a particular surface needs exploration

This is the killer pairing: do mocks alongside the `--only-questions`
passes so autopilot inherits visual alignment along with directional
choices.

## Nate's Toolkit

Standalone, project-agnostic utility skills with no workflow lock-in. Install
via `/plugin install nates-toolkit@nklisch-skills`.

| Skill | What it does |
|-------|-------------|
| **plainspeak** | Re-render the last thing said in vivid plain language — one everyday metaphor, one concrete example, a crisp restatement, at a chosen depth. Manual only (`/plainspeak`). |
| **agent-reflection** | Reflect on how the agent's own tools and skills served it this session — confusion, inefficiency, friction, context cost. Prioritized recommendations for tool and skill authors. |
| **write-tool-skill** | Create distributable reference skills for a tool, CLI, MCP server, or library. |
| **skill-auditor** | Static quality audit of a skill against type-specific, triggering, and emotional-tone rubrics. Scored report with fixes and a trigger-test plan. |

## Code Audit

Standalone markdown-first code audits with no workflow substrate. Install via
`/plugin install code-audit@nklisch-skills`.

| Skill | What it does |
|-------|-------------|
| **deep-code-scan** | Multi-lane campaign: decomposes the repo, fans out scanners, reviews findings, and writes `code-audit/scan-<goal>/` docs. |
| **bug-scan** | Correctness bug hunt across concurrency, async, state, resource, time/number, error, data, and language-footgun domains. |
| **security-scan** | Security review across auth, injection, secrets, deps, API, infra, crypto, data protection, and logging risks. |
| **test-scan** | Test-quality audit: coverage gaps from contracts/specs, weak assertions, stale fixtures, over-mocking, and flaky tests. |
| **perf-scout** | Speculative performance idea deck with validation paths; no claimed speedups. |
| **bold-refactor** | Architectural reconception proposals through elimination, unification, inversion, algebraic, declarative, and domain lenses. |
| **repo-eval** | Verified repository scorecard written to `REPO-EVAL.md`; this is the supported home for repository evaluation. |

### Which audit/eval path to use

Use **code-audit** when you want markdown deliverables only: reports, scorecards,
and remediation plans that do not assume agile-workflow exists.

Use **agile-workflow gates** when you are cutting a release and want findings to
become substrate work tied to the release bundle instead of standalone reports.

## Agent Coordination

Sparse cross-agent coordination for shared repositories. Install via
`/plugin install agent-coordination@nklisch-skills`.

| Skill | What it does |
|-------|-------------|
| **coordination-ledger** | Defines a deliberate GitHub Discussions-backed ledger for active claims, scope updates, releases, handoffs, blockers, review summaries, and merge summaries. Uses `.work` item IDs as optional context when agile-workflow is present, but keeps `.work`, PRs, and code review authoritative. |

The plugin also ships `scripts/agent-comms`, a small `gh api graphql` wrapper
for ledger operations such as `doctor`, `ensure-thread`, `active-claims`,
`claim`, `release`, `handoff`, `blocker`, `review-summary`, and `merge-summary`.

## Library & Tool References

Reference skills that auto-load when their library is detected.

| Skill | Library |
|-------|---------|
| **bun** | Bun runtime — Bun.$, Bun.file, bun:test |
| **zod-v4** | Zod v4 — schemas, safeParse, transforms |
| **biome-v2** | Biome v2 — linter/formatter config |
| **drizzle-v0** | Drizzle ORM v0.45+ PostgreSQL |
| **hono-v4** | Hono v4 — routes, middleware, SSE |
| **tanstack-query-v5** | TanStack Query v5 (React Query) |
| **tanstack-router-v1** | TanStack Router v1 — file-based routing |
| **tanstack-table-v8** | TanStack Table v8 — headless tables |
| **zustand-v5** | Zustand v5 — state management |
| **citty** | citty CLI framework (UnJS) |
| **clack-prompts** | @clack/prompts — terminal UI |
| **smol-toml** | smol-toml — TOML parser/serializer |
| **claude-cli-sdk** | @nklisch/claude-cli-sdk |
| **schemars** | schemars 1.x — Rust JSON Schema generation |

## Other Skills

| Skill | What it does |
|-------|-------------|
| **design-pages** | Design GitHub Pages for a project |
| **clean-memory** | Audit and refine MEMORY.md |

## Canonical layout (in projects using these skills)

```
.work/
├── active/{epics,features,stories}/  ← in-flight items (markdown + frontmatter)
├── backlog/                           ← parked ideas, unscoped
├── releases/<version>/                ← shipped bundles
├── archive/                           ← done items not bound to a release
├── bin/work-view                      ← query script (copied by /agile-workflow:convert)
└── CONVENTIONS.md                     ← project-specific overrides
AGENTS.md                              ← canonical agent instructions (slim: orientation + pointers + read-directive)
CLAUDE.md -> AGENTS.md                 ← Claude Code compatibility
.agents/
├── rules/*.md                         ← force-loaded agent rules (agile-workflow.md + patterns.md digest + user rules; hook-injected)
└── skills/patterns/                   ← detailed reusable code patterns (gate-patterns source of truth)
.mockups/
├── design-system/                     ← palette, typography, components, motion + tokens.css/components.css/motion.css
├── screens/<feature>/                 ← N option HTMLs + index.html
└── flows/<flow-name>/                 ← numbered sequence + index.html
docs/                                  ← foundation docs (VISION, SPEC, ARCHITECTURE) — roll forward in place
```

Items are markdown files with structured frontmatter (`id, kind, stage,
tags, parent, depends_on, release_binding, gate_origin, research_refs, research_origin, created, updated`).
Design lives inside the item's body — there are no parallel design docs.
Mockups land in `.mockups/` and link back via a `## Mockups` section in
the item body. See the guides for the full conventions.

## Repo Structure (this repo)

```
plugins/agile-workflow/            # agile-workflow plugin (substrate-driven)
├── skills/                        #   skill source
├── docs/                          #   foundation docs (VISION, SPEC, ARCHITECTURE, PRINCIPLES, MIGRATION)
├── hooks/                         #   SessionStart/UserPromptSubmit/PostCompact + PostToolUse hook scripts
├── scripts/work-view.sh           #   substrate query CLI (copied by /convert into target repos)
└── .claude-plugin/plugin.json
plugins/ux-ui-design/              # ux-ui-design plugin (7 skills, mockup-first)
├── skills/                        #   skill source
└── docs/                          #   plugin design docs
plugins/code-audit/skills/         # standalone markdown-first code audit skills
plugins/nates-toolkit/skills/      # standalone utility skills (plainspeak, agent-reflection, write-tool-skill, skill-auditor)
plugins/agentic-research/          # grounded research discipline + .research substrate
plugins/agent-coordination/skills/ # sparse cross-agent coordination ledger
plugins/workflow/                  # DEPRECATED — doc-driven, no longer supported
.agents/skills/                    # reference, principle, and utility skills
.claude-plugin/                    # Claude Code plugin manifest (root)
docs/                              # human-facing guides — agile-workflow-guide.md, ux-ui-design-guide.md, workflow-guide.md (deprecated)
```

## Requirements

- Claude Code with Task/Agent tool support, OpenAI Codex CLI, or Pi
- Git repository

nklisch/skills

A software development workflow suite for Claude Code, OpenAI Codex, and Pi — work tracking, UI/UX design, grounded research, markdown code audits, and standalone utility skills, designed to tee up autonomous agent runs that actually ship the right thing.

Available as Claude Code plugins, Codex plugins, and Pi packages.

Install

All supported plugins ship through three channels. The shared skills/ directory is the portable surface; each harness adds only its native metadata or ergonomics.

Claude Code

/plugin marketplace add nklisch/skills

# Choose one mutually exclusive .work/ owner:
/plugin install agile-workflow@nklisch-skills    # structured work tracking + autopilot
# or: /plugin install workbench@nklisch-skills   # flexible requirements-first delivery

/plugin install ux-ui-design@nklisch-skills      # standalone mockup-first UI design
/plugin install code-audit@nklisch-skills        # standalone markdown code audits
/plugin install nates-toolkit@nklisch-skills     # standalone utility skills
/plugin install agentic-research@nklisch-skills  # grounded research discipline
/plugin install agent-coordination@nklisch-skills # sparse cross-agent ledger

OpenAI Codex

codex plugin marketplace add https://github.com/nklisch/skills

# Choose one mutually exclusive .work/ owner:
codex plugin install agile-workflow
# or: codex plugin install workbench

codex plugin install ux-ui-design
codex plugin install code-audit
codex plugin install nates-toolkit
codex plugin install agentic-research
codex plugin install agent-coordination

Pi

# Install the compatible default Pi package set (agile-workflow-based)
pi install git:github.com/nklisch/skills

# Or install individual published packages. Choose one .work/ owner:
pi install npm:@nklisch/pi-agile-workflow
# or: pi install npm:@nklisch/pi-workbench

pi install npm:@nklisch/pi-ux-ui-design
pi install npm:@nklisch/pi-code-audit
pi install npm:@nklisch/pi-nates-toolkit
pi install npm:@nklisch/pi-agentic-research
pi install npm:@nklisch/pi-agent-coordination
pi install npm:@nklisch/pi-background-tasks
pi install npm:@nklisch/pi-zai-research

# External companion plugin: peeragent lives in its own repo/package
pi install git:github.com/nklisch/peeragent@v0.4.1

# Local checkout/development installs
pi install -l .
pi install -l ./plugins/agile-workflow
pi install -l ./plugins/workbench
pi install -l ./plugins/ux-ui-design
pi install -l ./plugins/code-audit
pi install -l ./plugins/nates-toolkit
pi install -l ./plugins/agentic-research
pi install -l ./plugins/agent-coordination
pi install -l ./plugins/background-tasks
pi install -l ./plugins/zai-research

Pi packages can load executable extensions in addition to shared skills. The root Git install loads the compatible default set built around agile-workflow; workbench is an alternative .work/ owner and must be installed individually instead. The deprecated workflow plugin and external marketplace companions such as peeragent are not included. Install alternatives and companions from their own package roots. Install from trusted sources; agile-workflow includes a Pi-native /aw command for queue inspection and workflow handoffs.

The supported plugins

Plugin	What it does	Guide
agile-workflow	Substrate-driven work tracking. Items as files in `.work/` with YAML frontmatter, late-binding releases, gates that produce items, goal-backed autopilot queue runner.	docs/agile-workflow-guide.md
workbench	Flexible requirements-first delivery. A lightweight `.work/` ledger references grounded `.research/` evidence and interactive `.mockups/` walkthroughs; natural language drives research, design, implementation, review, scans, and release summaries.	plugins/workbench/README.md
ux-ui-design	HTML/CSS/JS mockup-first UI design. Throwaway single-file mockups in `.mockups/` for alignment before any production code. Loosely integrated with agile-workflow.	docs/ux-ui-design-guide.md
code-audit	Standalone markdown-first code audits — deep multi-lane scans, bug/security/test scans, perf scouting, bold refactor proposals, and repo scorecards without `.work`.	plugins/code-audit/README.md
nates-toolkit	Standalone utility skills, no workflow lock-in — explain in plain language, reflect on tool & skill usage, author skills, and audit skill artifacts.	plugins/nates-toolkit/README.md
agentic-research	Grounded, verifiable AI research discipline. Produces `.research/` attestations and syntheses with citation/verification gates, and pairs with agile-workflow when research should ground a work item.	plugins/agentic-research/README.md
agent-coordination	Sparse cross-agent coordination ledger for shared repos — deliberate claims, handoffs, blockers, review summaries, and merge summaries without turning Discussions into chat. Lightly aware of agile-workflow `.work` IDs when present.	plugins/agent-coordination/README.md
background-tasks	Pi-native background command, monitor, and job-registry tools.	plugins/background-tasks/README.md
zai-research	Pi-native Z.ai web, URL/PDF, JSON/API, and GitHub repository research tools.	plugins/zai-research/README.md

External companion plugins

Plugin	Pi install	What it does
peeragent	`pi install git:github.com/nklisch/peeragent@v0.4.1`	Cross-harness peer delegation and peer review. Pi loads the `peer` and `peer-review` skills from peeragent's package and uses its bundled wrapper/binaries to call Codex, Claude Code, Gemini through Antigravity, or Z.AI GLM 5.2 through Pi.

The package release procedure is documented in docs/npm-publishing.md. Choose one .work/ owner per project: agile-workflow provides a structured stage-and-gate system, while workbench provides a smaller requirements-first ledger and can migrate an existing agile-workflow substrate through /workbench:setup. The standalone ux-ui-design plugin remains available for projects that want its larger, specialized mockup system.

Deprecated: the workflow plugin (doc-driven, docs/designs/-as-artifacts) is deprecated and no longer supported. Existing projects on it still work, but no new features or fixes will land. New projects should use agile-workflow. To migrate an existing workflow project, run /agile-workflow:convert — it detects the legacy layout and migrates automatically. The old guide at docs/workflow-guide.md remains for reference.

agile-workflow

A full substrate skill set for tracking and shipping work via markdown files in .work/. See docs/agile-workflow-guide.md for the full guide and current catalog.

Pipeline

ideate → convert → epicize           ← project bootstrap (greenfield)
    ↓
park / scope / fix                   ← capture & promotion (agent picks)
    ↓
epic-design --only-questions --all   ← align on big choices (also runs UI mocks)
feature-design --only-questions --all   ← drill in per feature
    ↓
Goal: Use agile-workflow autopilot to drain --all
    ↓
release-deploy <version>             ← bind, gate, ship

The two --only-questions passes are the killer move — front-load every directional choice and mock so autopilot runs without guessing.

Bootstrap (user-invocable)

Skill	What it does
ideate	Foundation-docs workshop. Produces VISION.md, SPEC.md, ARCHITECTURE.md that encode rolling-foundation from day one.
convert	Bootstrap the `.work/` substrate. Detects project shape (legacy workflow-plugin / ad-hoc / no-tracking / greenfield), seeds initial items, writes the canonical AGENTS.md section, keeps CLAUDE.md as a symlink/shim for compatibility, runs the conventions interview, copies `work-view`, produces MIGRATION_REPORT.md. Idempotent via `--update`.
epicize	Decompose foundation docs into multiple epics in `.work/active/epics/` with declared `depends_on` chains.

Capture & promotion (agent picks naturally)

Skill	What it does
park	Quick capture into `.work/backlog/`. Triggers on "park this", "add to backlog".
scope	Promote backlog item or fresh request into `.work/active/` as epic/feature/story. For large scope, rolls foundation docs forward in the same stride. Batch mode (no arg, `--all`, or NL filter) clusters the whole backlog by code seam and capability arc, proposes a structure, confirms once with the user, then writes everything.
fix	Single-stride bug repair. Reproduces, identifies root cause, writes failing test, applies minimal fix, lands story at stage:review.

Design family (agent picks; kind- and tag-routed)

Skill	Triggered by	What it produces
epic-design	epic at stage:drafting	Decomposes the epic into child features at stage:drafting with declared depends_on chains, written INTO the epic body; advances epic to implementing. Primary tier for `ux-ui-design` mocks.
feature-design	feature at stage:drafting, no specialized tag	Greenfield design — written INTO feature body, child stories spawned with depends_on, advances stage to implementing. Fallback tier for mocks.
refactor-design	feature with tags:[refactor], OR discovery (no arg / path / NL scope)	Per-feature: code-smell scan, before/after step shape, risk + rollback per step. Discovery: scans target scope, classifies findings as pure-refactor or behavior-changing, emits items.
perf-design	feature with tags:[perf], OR discovery (no arg / path / NL scope)	Per-feature: bottleneck identification, optimization hierarchy (algorithmic > I/O > idioms > parallelism), benchmark scaffolds. Discovery: picks top 3-5 likely hot paths, profiles them, emits items per bottleneck.
prose-author	feature with tags:[prose]	No-code authoring lane (authors, not a design step) — for prose deliverables with no code surface (docs, conventions, rules, copy). Verifies no real code surface (black-box test), writes brief-as-design, advances stage to implementing with no Explore / pre-mortem / question gate. Collapses to one inline stride for the common case; large multi-section prose can use drafting → implementing → review as real draft/write/revise steps. Pairs with implement's inline path.
agentic-research:research-orchestrator (cross-plugin)	feature with tags:[research]	Grounded ARD research engagement — an input that grounds other work, not a code design. Reads the item's `research_dials:` block — the commissioning subset of the registration (scope_authority, verification_rigor, intent, output_kind), with the rest settled at dispatch; scoping the item IS the dispatch act. Runs the ARD walk with verification gates inline; never binds to a release. Requires the `agentic-research` plugin (without it, `[research]` is an inert tag → `feature-design`).

Production + review (agent picks)

Skill	What it does
implement	Read item body (design is in there), write code, run build+tests, advance stage implementing → review. Single-stride sequential.
implement-orchestrator	For implementation bands: walk depends_on graph, decide bundles/waves/write-scope isolation, and dispatch implementation sub-agents when parallelism is beneficial.
review	Granularity-gated. A story fast-advances on the build+tests `implement` already ran — no lens pass, no peer (a second same-context review there rarely finds anything). A feature/epic gets a deep lens review run in a fresh context: cross-model via `peeragent:peer-review` when a different model class is reachable, otherwise a fresh top-class sub-agent (an Opus host spawns a new Opus for fresh perspective). Triages findings into items. Accepts `<id>`, `--all` / no arg (drain the review queue), or NL filter.

Release & autonomous

Skill	What it does
release-deploy	Bind items to a version, run all configured gates in CONVENTIONS.md order, wait for readiness, ship per release mapping, collapse the bundle into one release summary (bodies pruned or retained per terminal-tier retention). Idempotent.
autopilot	Goal-backed queue runner. Picks next ready item respecting depends_on, invokes the right skill, advances stage, repeats until the goal scope is done or blocked — then runs a final cross-model peer-review pass over the whole completion bundle before reporting complete. Invokable from goal text such as "Use agile-workflow autopilot to drain --all"; direct `/agile-workflow:autopilot <scope>` still works. Harness goal/continuation owns persistence, not `/loop`.
bold-refactor	Architectural reconception via conceptual lenses. Sweeps a target and produces one or more refactor EPICs with child features tagged [refactor]. User-invocable only — too aggressive for auto-trigger.

Gates (agent picks; produce items, NOT pass/fail reports)

Five gates fire by default during release-deploy's quality-gate stage in CONVENTIONS.md order (default: security → tests → cruft → docs → patterns). gate-refactor is opt-in — add it to gates_for_release when your project has scan-rule libraries installed. Gate finding placement is configurable with gate_finding_routing after each gate normalizes its own severity/priority/confidence vocabulary.

Skill	Items produced
gate-security	Security findings with `gate_origin: security`, `tags: [security]`
gate-tests	Coverage gaps + tautological-test reworks with `gate_origin: tests`
gate-cruft	Dead code / cruft cleanup items with `gate_origin: cruft`
gate-docs	Foundation-doc drift items (enforces rolling-foundation) with `gate_origin: docs`
gate-patterns	Reusable patterns extracted to `.agents/skills/patterns/` with optional Claude mirror
gate-refactor	Refactor rule-library findings with `gate_origin: refactor`; routing tag per library declaration (`findings-route:`); see the gate's SKILL.md — opt-in; discovers libraries under `gate_refactor_scan_library_roots` (default: `{project}/.agents/skills/scan-/`, then `{project}/.claude/skills/scan-/`); graceful no-op when no libraries installed

Reference

Skill	What it does
principles	Code-design (Ports & Adapters, SSOT, Generated Contracts, Fail Fast) + substrate-execution (Item-IS-the-Work, Rolling-Foundation, Late-Binding) principles. Auto-loads.
research	Investigate libraries, APIs, SDKs. Produces a research doc and auto-loading reference skill.
refactor-conventions-creator	Interview-based. Generates a project-specific refactor-conventions skill.

ux-ui-design

Seven skills for mockup-first UI/UX design. Throwaway single-file HTML mockups in .mockups/ for alignment before any production code. See docs/ux-ui-design-guide.md for the full guide.

Skill	What it does
palette	Color + typography options as HTML previews. Locks the choice into `tokens.css`.
components	Showcase page of every button/input/card/modal in every state, plus a reusable `components.css`.
motion	Named easing-curve vocabulary, durations, springs, designed pauses — playable in browser, plus reusable `motion.css`.
screens	N (default 4) distinct HTML mockups for a single screen, plus a 2x2 comparison grid.
flows	Multi-page user flow with prev/next or hub-and-spoke chrome, plus index navigator.
adopt	Scans an existing codebase, inventories every UI surface, audits for inconsistencies, mirrors current UI into mocks OR reimagines them.
ux-ui-principles	Reference: storage layout, decision matrix, tech rule. Adds convention to project AGENTS.md on first run, with CLAUDE.md compatibility when needed. Auto-loads.

Plugged into agile-workflow

When both plugins are installed, mocks land at four tiers (highest tier first wins, downstream inherits):

After ideate → palette + components
During epic-design --only-questions → screens + flows for cross-feature journeys
During feature-design --only-questions → more screens + flows for per-feature surfaces
Ad-hoc during design work → one-off mocks when a particular surface needs exploration

This is the killer pairing: do mocks alongside the --only-questions passes so autopilot inherits visual alignment along with directional choices.

Nate's Toolkit

Standalone, project-agnostic utility skills with no workflow lock-in. Install via /plugin install nates-toolkit@nklisch-skills.

Skill	What it does
plainspeak	Re-render the last thing said in vivid plain language — one everyday metaphor, one concrete example, a crisp restatement, at a chosen depth. Manual only (`/plainspeak`).
agent-reflection	Reflect on how the agent's own tools and skills served it this session — confusion, inefficiency, friction, context cost. Prioritized recommendations for tool and skill authors.
write-tool-skill	Create distributable reference skills for a tool, CLI, MCP server, or library.
skill-auditor	Static quality audit of a skill against type-specific, triggering, and emotional-tone rubrics. Scored report with fixes and a trigger-test plan.

Code Audit

Standalone markdown-first code audits with no workflow substrate. Install via /plugin install code-audit@nklisch-skills.

Skill	What it does
deep-code-scan	Multi-lane campaign: decomposes the repo, fans out scanners, reviews findings, and writes `code-audit/scan-<goal>/` docs.
bug-scan	Correctness bug hunt across concurrency, async, state, resource, time/number, error, data, and language-footgun domains.
security-scan	Security review across auth, injection, secrets, deps, API, infra, crypto, data protection, and logging risks.
test-scan	Test-quality audit: coverage gaps from contracts/specs, weak assertions, stale fixtures, over-mocking, and flaky tests.
perf-scout	Speculative performance idea deck with validation paths; no claimed speedups.
bold-refactor	Architectural reconception proposals through elimination, unification, inversion, algebraic, declarative, and domain lenses.
repo-eval	Verified repository scorecard written to `REPO-EVAL.md`; this is the supported home for repository evaluation.

Which audit/eval path to use

Use code-audit when you want markdown deliverables only: reports, scorecards, and remediation plans that do not assume agile-workflow exists.

Use agile-workflow gates when you are cutting a release and want findings to become substrate work tied to the release bundle instead of standalone reports.

Agent Coordination

Sparse cross-agent coordination for shared repositories. Install via /plugin install agent-coordination@nklisch-skills.

Skill	What it does
coordination-ledger	Defines a deliberate GitHub Discussions-backed ledger for active claims, scope updates, releases, handoffs, blockers, review summaries, and merge summaries. Uses `.work` item IDs as optional context when agile-workflow is present, but keeps `.work`, PRs, and code review authoritative.

The plugin also ships scripts/agent-comms, a small gh api graphql wrapper for ledger operations such as doctor, ensure-thread, active-claims, claim, release, handoff, blocker, review-summary, and merge-summary.

Library & Tool References

Reference skills that auto-load when their library is detected.

Skill	Library
bun	Bun runtime — Bun.$, Bun.file, bun:test
zod-v4	Zod v4 — schemas, safeParse, transforms
biome-v2	Biome v2 — linter/formatter config
drizzle-v0	Drizzle ORM v0.45+ PostgreSQL
hono-v4	Hono v4 — routes, middleware, SSE
tanstack-query-v5	TanStack Query v5 (React Query)
tanstack-router-v1	TanStack Router v1 — file-based routing
tanstack-table-v8	TanStack Table v8 — headless tables
zustand-v5	Zustand v5 — state management
citty	citty CLI framework (UnJS)
clack-prompts	@clack/prompts — terminal UI
smol-toml	smol-toml — TOML parser/serializer
claude-cli-sdk	@nklisch/claude-cli-sdk
schemars	schemars 1.x — Rust JSON Schema generation

Other Skills

Skill	What it does
design-pages	Design GitHub Pages for a project
clean-memory	Audit and refine MEMORY.md

Canonical layout (in projects using these skills)

.work/
├── active/{epics,features,stories}/  ← in-flight items (markdown + frontmatter)
├── backlog/                           ← parked ideas, unscoped
├── releases/<version>/                ← shipped bundles
├── archive/                           ← done items not bound to a release
├── bin/work-view                      ← query script (copied by /agile-workflow:convert)
└── CONVENTIONS.md                     ← project-specific overrides
AGENTS.md                              ← canonical agent instructions (slim: orientation + pointers + read-directive)
CLAUDE.md -> AGENTS.md                 ← Claude Code compatibility
.agents/
├── rules/*.md                         ← force-loaded agent rules (agile-workflow.md + patterns.md digest + user rules; hook-injected)
└── skills/patterns/                   ← detailed reusable code patterns (gate-patterns source of truth)
.mockups/
├── design-system/                     ← palette, typography, components, motion + tokens.css/components.css/motion.css
├── screens/<feature>/                 ← N option HTMLs + index.html
└── flows/<flow-name>/                 ← numbered sequence + index.html
docs/                                  ← foundation docs (VISION, SPEC, ARCHITECTURE) — roll forward in place

Items are markdown files with structured frontmatter (id, kind, stage, tags, parent, depends_on, release_binding, gate_origin, research_refs, research_origin, created, updated). Design lives inside the item's body — there are no parallel design docs. Mockups land in .mockups/ and link back via a ## Mockups section in the item body. See the guides for the full conventions.

Repo Structure (this repo)

plugins/agile-workflow/            # agile-workflow plugin (substrate-driven)
├── skills/                        #   skill source
├── docs/                          #   foundation docs (VISION, SPEC, ARCHITECTURE, PRINCIPLES, MIGRATION)
├── hooks/                         #   SessionStart/UserPromptSubmit/PostCompact + PostToolUse hook scripts
├── scripts/work-view.sh           #   substrate query CLI (copied by /convert into target repos)
└── .claude-plugin/plugin.json
plugins/ux-ui-design/              # ux-ui-design plugin (7 skills, mockup-first)
├── skills/                        #   skill source
└── docs/                          #   plugin design docs
plugins/code-audit/skills/         # standalone markdown-first code audit skills
plugins/nates-toolkit/skills/      # standalone utility skills (plainspeak, agent-reflection, write-tool-skill, skill-auditor)
plugins/agentic-research/          # grounded research discipline + .research substrate
plugins/agent-coordination/skills/ # sparse cross-agent coordination ledger
plugins/workflow/                  # DEPRECATED — doc-driven, no longer supported
.agents/skills/                    # reference, principle, and utility skills
.claude-plugin/                    # Claude Code plugin manifest (root)
docs/                              # human-facing guides — agile-workflow-guide.md, ux-ui-design-guide.md, workflow-guide.md (deprecated)

Requirements

Claude Code with Task/Agent tool support, OpenAI Codex CLI, or Pi
Git repository