From 217feb229f2f4cc6fc2c4047a0ab532c7fbfc354 Mon Sep 17 00:00:00 2001 From: Addy Osmani Date: Sat, 8 Aug 2026 09:57:00 -0700 Subject: [PATCH] docs: route to constraint-driven-development and refresh skill counts --- README.md | 11 +++++++---- docs/adoption-guide.md | 2 +- docs/codex-setup.md | 2 +- docs/commandcode-setup.md | 2 +- docs/comparison.md | 2 +- skills/using-agent-skills/SKILL.md | 1 + 6 files changed, 12 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index f31b37f..f6f4550 100644 --- a/README.md +++ b/README.md @@ -21,7 +21,7 @@ Skills encode the workflows, quality gates, and best practices that senior engin ## Commands -8 slash commands that map to the development lifecycle. Each one activates the right skills automatically. +9 slash commands that map to the development lifecycle. Each one activates the right skills automatically. | What you're doing | Command | Key principle | |-------------------|---------|---------------| @@ -29,6 +29,7 @@ Skills encode the workflows, quality gates, and best practices that senior engin | Plan how to build it | `/plan` | Small, atomic tasks | | Build incrementally | `/build` | One slice at a time | | Prove it works | `/test` | Tests are proof | +| Set the quality bar | `/constraints` | Decide it once, enforce it everywhere | | Review before merge | `/review` | Improve code health | | Audit web performance | `/webperf` | Measure before you optimize | | Simplify the code | `/code-simplify` | Clarity over cleverness | @@ -45,7 +46,7 @@ Skills also activate automatically based on what you're doing — designing an A **Fastest path — any agent, one command.** The open [skills CLI](https://github.com/vercel-labs/skills) installs into 70+ agents (Claude Code, Cursor, Codex, Copilot, Cline, and more): ```bash -npx skills add addyosmani/agent-skills # install all 24 skills +npx skills add addyosmani/agent-skills # install all 25 skills npx skills add addyosmani/agent-skills --list # browse before installing ``` @@ -218,7 +219,7 @@ Already installed? How you roll the pack out depends on your codebase. The **[Ad ## All 24 Skills -The commands above are entry points. The pack includes 24 skills total — 23 lifecycle skills plus the `using-agent-skills` meta-skill. Each skill is a structured workflow with steps, verification gates, and anti-rationalization tables. You can also reference any skill directly. +The commands above are entry points. The pack includes 25 skills total — 24 lifecycle skills plus the `using-agent-skills` meta-skill. Each skill is a structured workflow with steps, verification gates, and anti-rationalization tables. You can also reference any skill directly. ### Meta - Discover which skill applies @@ -233,6 +234,7 @@ The commands above are entry points. The pack includes 24 skills total — 23 li | [interview-me](skills/interview-me/SKILL.md) | One-question-at-a-time interview that extracts what the user actually wants instead of what they think they should want, until ~95% confidence | The ask is underspecified, or the user invokes "interview me" / "grill me" | | [idea-refine](skills/idea-refine/SKILL.md) | Structured divergent/convergent thinking to turn vague ideas into concrete proposals | You have a rough concept that needs exploration | | [spec-driven-development](skills/spec-driven-development/SKILL.md) | Write a PRD covering objectives, commands, structure, code style, testing, and boundaries before any code | Starting a new project, feature, or significant change | +| [constraint-driven-development](skills/constraint-driven-development/SKILL.md) | Interviews you for a quality bar with sane default thresholds, writes CONSTRAINTS.md, places each check by cost, and catches agents silencing checks or skipping tests to get green | No standards are written down, or an agent is producing more than anyone reads | ### Plan - Break it down @@ -347,10 +349,11 @@ Every skill follows a consistent anatomy: ``` agent-skills/ -├── skills/ # 24 skills (23 lifecycle + 1 meta) +├── skills/ # 25 skills (24 lifecycle + 1 meta) │ ├── interview-me/ # Define │ ├── idea-refine/ # Define │ ├── spec-driven-development/ # Define +│ ├── constraint-driven-development/ # Define │ ├── planning-and-task-breakdown/ # Plan │ ├── incremental-implementation/ # Build │ ├── context-engineering/ # Build diff --git a/docs/adoption-guide.md b/docs/adoption-guide.md index 77deeae..c02ec93 100644 --- a/docs/adoption-guide.md +++ b/docs/adoption-guide.md @@ -65,7 +65,7 @@ Run the lifecycle in order for the project's first real feature: ### Greenfield anti-patterns - **Skipping `/spec` because "it's just a prototype."** Prototypes become products. The spec is the cheapest artifact you'll ever write for this codebase. -- **Loading all 24 skills into every session.** It wastes context and dilutes the ones that matter. Load by phase; let `using-agent-skills` route. +- **Loading all 25 skills into every session.** It wastes context and dilutes the ones that matter. Load by phase; let `using-agent-skills` route. - **Deferring observability until "there's something to observe."** Instrument as you build, retrofitting structured logging is a Path B problem you're choosing to create. --- diff --git a/docs/codex-setup.md b/docs/codex-setup.md index 54b59a6..7f32939 100644 --- a/docs/codex-setup.md +++ b/docs/codex-setup.md @@ -22,7 +22,7 @@ codex plugin add agent-skills@agent-skills ## Usage -After install, invoke a skill in Codex chat with `@` (e.g. `@spec-driven-development`) or just describe the task and let Codex pick the right skill. All 24 skills under `skills/` are available. +After install, invoke a skill in Codex chat with `@` (e.g. `@spec-driven-development`) or just describe the task and let Codex pick the right skill. All 25 skills under `skills/` are available. ## How it works diff --git a/docs/commandcode-setup.md b/docs/commandcode-setup.md index e6aa360..0150adc 100644 --- a/docs/commandcode-setup.md +++ b/docs/commandcode-setup.md @@ -12,7 +12,7 @@ The Command Code binary is available as `cmd` (with aliases `cmdc` on Windows an cmd skills add addyosmani/agent-skills ``` -In an interactive terminal this shows a multi-select so you can choose which of the 24 skills to install. Pipe/non-interactive invocations install all discovered skills. +In an interactive terminal this shows a multi-select so you can choose which of the 25 skills to install. Pipe/non-interactive invocations install all discovered skills. **Install a specific skill:** diff --git a/docs/comparison.md b/docs/comparison.md index 904d270..2c51daa 100644 --- a/docs/comparison.md +++ b/docs/comparison.md @@ -18,7 +18,7 @@ People often ask how **agent-skills** relates to the two other "skills for codin |---|---|---|---| | **Core idea** | Encode the full senior-engineering lifecycle as skills | A complete development *methodology* built on composable skills | One expert's Claude Code workflow, open-sourced and evolving | | **Organizing principle** | SDLC **phases** (Define to Ship) behind a meta-skill router | A single disciplined loop: brainstorm, plan, execute, review | A curated toolbox of focused, composable commands | -| **Catalog size** | 24 skills spanning the whole lifecycle | ~14 skills, deep on the inner build loop | ~30 skills, grouped into engineering / productivity / in-progress / deprecated | +| **Catalog size** | 25 skills spanning the whole lifecycle | ~14 skills, deep on the inner build loop | ~30 skills, grouped into engineering / productivity / in-progress / deprecated | | **Lifecycle coverage** | Broad: idea refinement, API and UI design, security, performance, CI/CD, observability, deprecation, ADRs, launch | Deep but narrow: TDD, debugging, planning, review, skill authoring | Define and Build heavy: grilling, PRDs, issues, TDD, architecture, bug triage, knowledge management | | **Entry points** | Slash commands mapped 1:1 to phases (`/spec` `/plan` `/build` `/test` `/review` `/code-simplify` `/ship`, plus `/webperf`), with a `/build auto` full-plan mode | Skill-chained pipeline (`brainstorming`, `writing-plans`, `subagent-driven-development`) | Slash commands (`/grill-me`, `/tdd`, `/to-prd`, `/diagnosing-bugs`, `/grill-with-docs`) | | **Distinctive mechanisms** | Anti-rationalization tables and Red Flags in every skill; parallel review **personas** in `/ship`; reference checklists; a **three-tier eval framework** in CI | Subagent-driven development with a task reviewer (spec + quality) and a fix loop; git-worktree isolation; skills-that-write-skills, pressure-tested | The **grilling** primitive (one question at a time, design-tree walking); seam-based TDD; explicit user-invoked vs model-invoked split; issue-tracker integration | diff --git a/skills/using-agent-skills/SKILL.md b/skills/using-agent-skills/SKILL.md index 975fb5c..ce8aab1 100644 --- a/skills/using-agent-skills/SKILL.md +++ b/skills/using-agent-skills/SKILL.md @@ -19,6 +19,7 @@ Task arrives ├── Don't know what you want yet? ──────→ interview-me ├── Have a rough concept, need variants? → idea-refine ├── New project/feature/change? ──→ spec-driven-development + ├── No quality bar written down? ──→ constraint-driven-development ├── Have a spec, need tasks? ──────→ planning-and-task-breakdown ├── Implementing code? ────────────→ incremental-implementation │ ├── UI work? ─────────────────→ frontend-ui-engineering