Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
56 changes: 39 additions & 17 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,41 +5,56 @@ pipeline (`prime → grill → plan → implement → validate → ship`) plus r
intake, and research skills — that drops into **any** project and **any** agentic
coding tool. You fill in one config file; the skills carry everything else.

Nothing in the skill bodies knows your project's name, paths, stack, or vendors. All of
that lives in a single `workflow.config.yaml`. The skill logic lives once, in `core/`,
and three thin adapters expose it to Claude Code, OpenCode, and Codex.
Nothing in the skill bodies knows your project's name, paths, stack, vendors, or SDLC
policy. All of that lives in a single `workflow.config.yaml`. The skill logic lives once,
in `core/`, and two thin adapters expose it to Claude Code and OpenCode.

## Why

Most "AI dev workflow" skill collections are welded to the repo they were born in —
hardcoded paths, project names, one specific model, one specific tool. This pack
extracts the *shape* of a good agentic pipeline and makes every project-specific value
a config field, so the same skills work on a solo side project and a multi-repo product,
on Claude, GPT, or an open-source-class model, under any of the supported tools.
hardcoded paths, project names, one specific model, one specific tool, one team's git
policy. This pack extracts the *shape* of a good agentic pipeline and makes every
project-specific value a config field, so the same skills work on a solo side project and
a multi-repo product, on Claude or an open-source-class model, under either supported tool.
Even SDLC policy is config, not constant — a machine that BANS co-authored commits or
requires `TB-####` branches is one config away from the opposite one.

> **Direction (in progress).** The pack is evolving from "fill in a YAML by hand" into an
> AI-installed harness: a `setup-harness` skill that researches the machine, interviews you,
> decodes your company's own rule docs, and generates a tailored harness — hooks for what
> must be enforced, skills for procedures, rules/facts for the rest. The generic `core/`
> skills below are the proven foundation that installer builds on.

## What's in it

| Group | Skills |
|---|---|
| **Pipeline** | `prime` · `grill` · `plan` · `implement` · `validate` · `execute` · `ship` · `clean` |
| **Review** | `pr-review` · `audit-security` · `audit-tests` · `audit-performance` · `audit-code-quality` · `thermo-nuclear` · `prod-readiness` |
| **Review** | `pr-review` · `audit-security` · `audit-tests` · `audit-performance` · `audit-code-quality` · `thermo-nuclear` · `prod-readiness` · `second-opinion` |
| **Intake** | `feature` (idea → PRD → issues) · `prd` (warm or cold) · `stories` (PRD → tracer-bullet issues) |
| **Research** | `deep-research` · `llm-council` |
| **Ops** | `investigate` (root-cause a prod incident end to end, read-only until a human gate) |
| **Meta** | `handoff` (compact a session to resume clean) · `lesson` (capture a correction as a graduating gate) |
| **Agents** | `security-reviewer` (generic; parity / i18n / contract checks are config-gated inside `pr-review`, not separate agents) |

`execute` is the gated conductor (`issue → prime → grill → plan → implement`) with hard,
default-deny stage gates. `pr-review` keeps full multi-dimension orchestration; its
parity, i18n, and contract dimensions activate only when your config declares them.
parity, i18n, and contract dimensions activate only when your config declares them, and its
Phase 6 folds in an adversarial skeptic pass plus an optional cross-model `second-opinion`
on Critical findings. Every review/audit skill shares one `verification-protocol` (coverage
contract → adversarial verify → loop-until-dry → deferred ledger) and one behavioral
baseline that ships in `core/_shared/`.

## Architecture

```
core/ ← tool-agnostic skill bodies — the SINGLE source of truth
_shared/ ← verification-protocol + behavioral-baseline (read by many skills)
pipeline/ review/ intake/ research/ ops/ meta/ agents/
adapters/ ← thin per-tool wrappers; each points at a core/ body, no logic
claude-code/ ← .claude/skills + .claude/agents
opencode/ ← .opencode/skills + .opencode/agents
codex/ ← .codex/prompts
scripts/ ← install / sync / genericity-check
scripts/ ← install / sync / gen-adapters / check-genericity
workflow.config.example.yaml ← the config schema (copy → workflow.config.yaml)
```

Expand All @@ -57,7 +72,7 @@ in `core/` and every adapter inherits it.
2. Vendor the pack for your tool:
```bash
node scripts/install.mjs --tool claude-code --into /path/to/your-project
# --tool opencode | codex
# --tool opencode
```
This copies `core/` and the chosen adapter into your project's skills directory and
writes `skills-lock.json` pinning what was installed.
Expand All @@ -78,7 +93,6 @@ node scripts/install.mjs --tool claude-code --into /path/to/your-project --dry-r
|---|---|---|
| claude-code | `.claude/skills/<skill>/SKILL.md`, `.claude/agents/` | `.claude/skills/_core/` |
| opencode | `.opencode/skills/<skill>/SKILL.md`, `.opencode/agents/` | `.opencode/skills/_core/` |
| codex | `.codex/prompts/<skill>.md` | `.codex/prompts/_core/` |

## Update

Expand Down Expand Up @@ -116,10 +130,18 @@ it. The pack never requires hooks.

## Genericity guarantee

`core/**` must never contain a project-specific string. CI runs
`node scripts/check-genericity.mjs`, which fails the build if any project name, brand,
author handle, or absolute machine path leaks into a core file. This is what keeps the
pack reusable — project specifics belong in `workflow.config.yaml`, always.
`core/**` must never contain a project-specific string **or** a hardcoded SDLC policy
constant. CI runs `node scripts/check-genericity.mjs`, which fails the build on two classes
of leak:

1. **Project strings** — any project name, brand, author handle, or absolute machine path.
2. **Policy constants** — a `Co-Authored-By` commit trailer, the `gh` tracker CLI, a
squash-only merge, or a literal branch prefix baked in instead of read from config. A
policy line is allowed only when it also carries a `{{config.*}}` reference (so the
behavior is genuinely parameterized and the constant is just an inline illustration).

This is what keeps the pack reusable — project specifics *and* git policy belong in
`workflow.config.yaml`, always.

## Maintaining the pack

Expand Down
Original file line number Diff line number Diff line change
@@ -1,11 +1,16 @@
# audit-performance
---
name: handoff
description: Compact the current session into a resumable handoff document a fresh agent can pick up from.
argument-hint: [note]
---
# handoff

Repo-wide performance-risk audit: N+1s, missing indexes, render thrash, bundle bloat.
Compact the current session into a resumable handoff document a fresh agent can pick up from.

**This is a thin adapter.** The full, tool-agnostic instructions live in the pack core.
Read and follow the core skill body, then execute its steps against this project:

> **Core body:** `_core/review/audit-performance.md`
> **Core body:** `../_core/meta/handoff.md`

Resolve every `{{config.*}}` reference in the core body against this project's
`workflow.config.yaml` (at the project root). If a referenced optional config value is
Expand Down
19 changes: 19 additions & 0 deletions adapters/claude-code/skills/investigate/SKILL.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,19 @@
---
name: investigate
description: Root-cause a production incident end to end against the configured error tracker, deploy platform, prod data, and code — read-only until a human gate.
argument-hint: [issue-id | url | description]
---
# investigate

Root-cause a production incident end to end against the configured error tracker, deploy platform, prod data, and code — read-only until a human gate.

**This is a thin adapter.** The full, tool-agnostic instructions live in the pack core.
Read and follow the core skill body, then execute its steps against this project:

> **Core body:** `../_core/ops/investigate.md`

Resolve every `{{config.*}}` reference in the core body against this project's
`workflow.config.yaml` (at the project root). If a referenced optional config value is
absent, skip that step and record it in the skill's Deferred ledger. When the host tool
lacks parallel subagents or a named-agent registry, follow the core body's sequential
fallback.
Original file line number Diff line number Diff line change
@@ -1,11 +1,16 @@
# audit-tests
---
name: lesson
description: Capture a correction as a gated, graduating lesson — staged for approval, then promoted to a hook/lint rule or a scoped note.
argument-hint: [the lesson]
---
# lesson

Repo-wide test-QUALITY audit against a behavior+edge+failure rubric; not coverage percentage.
Capture a correction as a gated, graduating lesson — staged for approval, then promoted to a hook/lint rule or a scoped note.

**This is a thin adapter.** The full, tool-agnostic instructions live in the pack core.
Read and follow the core skill body, then execute its steps against this project:

> **Core body:** `_core/review/audit-tests.md`
> **Core body:** `../_core/meta/lesson.md`

Resolve every `{{config.*}}` reference in the core body against this project's
`workflow.config.yaml` (at the project root). If a referenced optional config value is
Expand Down
19 changes: 19 additions & 0 deletions adapters/claude-code/skills/second-opinion/SKILL.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,19 @@
---
name: second-opinion
description: Independent cross-model second opinion (via opencode) on one load-bearing claim or Critical finding; degrades to UNAVAILABLE when opencode is absent.
argument-hint: [claim [file:line]]
---
# second-opinion

Independent cross-model second opinion (via opencode) on one load-bearing claim or Critical finding; degrades to UNAVAILABLE when opencode is absent.

**This is a thin adapter.** The full, tool-agnostic instructions live in the pack core.
Read and follow the core skill body, then execute its steps against this project:

> **Core body:** `../_core/review/second-opinion.md`

Resolve every `{{config.*}}` reference in the core body against this project's
`workflow.config.yaml` (at the project root). If a referenced optional config value is
absent, skip that step and record it in the skill's Deferred ledger. When the host tool
lacks parallel subagents or a named-agent registry, follow the core body's sequential
fallback.
14 changes: 0 additions & 14 deletions adapters/codex/prompts/clean.md

This file was deleted.

14 changes: 0 additions & 14 deletions adapters/codex/prompts/deep-research.md

This file was deleted.

14 changes: 0 additions & 14 deletions adapters/codex/prompts/execute.md

This file was deleted.

14 changes: 0 additions & 14 deletions adapters/codex/prompts/feature.md

This file was deleted.

14 changes: 0 additions & 14 deletions adapters/codex/prompts/grill.md

This file was deleted.

14 changes: 0 additions & 14 deletions adapters/codex/prompts/implement.md

This file was deleted.

14 changes: 0 additions & 14 deletions adapters/codex/prompts/llm-council.md

This file was deleted.

14 changes: 0 additions & 14 deletions adapters/codex/prompts/plan.md

This file was deleted.

14 changes: 0 additions & 14 deletions adapters/codex/prompts/pr-review.md

This file was deleted.

14 changes: 0 additions & 14 deletions adapters/codex/prompts/prd.md

This file was deleted.

14 changes: 0 additions & 14 deletions adapters/codex/prompts/prime.md

This file was deleted.

14 changes: 0 additions & 14 deletions adapters/codex/prompts/prod-readiness.md

This file was deleted.

14 changes: 0 additions & 14 deletions adapters/codex/prompts/security-reviewer.md

This file was deleted.

14 changes: 0 additions & 14 deletions adapters/codex/prompts/ship.md

This file was deleted.

Loading
Loading