Spec-Driven Development in Practice #1: Setup — Define the Rules Your AI Should Follow

Introduction

This is part 1 of a practical guide to the spec series in agent-skills (an open-source skill set published by ZenChAIne for Spec-Driven Development). The series shows how each skill is actually used in a project. Part 1 covers spec-workflow-init and spec-rules-init, the two skills that generate the foundation documents Spec-Driven Development relies on.

For an introduction to Agent Skills as a format, see What Are Agent Skills and the agent-skills open-source release post. This article assumes those basics and goes one level deeper into actual project usage.

Why Do You Need Spec-Driven Development Skills?

When you hand development to AI agents, the first problem is consistency: the same project gets different output granularity and different conventions from each agent session. Branch flow, test style, commit language, and import ordering drift between conversations.

This is an operational question: how do you share the implicit knowledge of a project with an AI agent? The Spec-Driven Development skills answer it by extracting that knowledge into three documents and making every later skill read them.

The three foundation documents look like this:

Part 1 (this article) covers how to generate these three documents.

The agent-skills Spec Series at a Glance (9 Skills)

The spec series owns the Issue-to-PR workflow in four stages:

This article focuses on the two Stage 0 skills.

Companion Skills Worth Knowing Up Front

agent-skills ships several non-spec skills that surround the workflow. The ones directly relevant to this article are introduced here so they do not appear out of nowhere later.

Treat skill-suggest as a companion that thickens the rules spec-rules-init can extract, and treat the three cmux skills as companions for multi-agent execution. Both come up again in the following sections.

How Does spec-workflow-init Generate Your Development Workflow?

spec-workflow-init generates a project-specific issue-to-pr-workflow.md through up to eight rounds of interactive dialogue.

The file is the playbook AI agents follow from "receive an Issue → read the spec → implement → review → test → open a PR". Downstream, spec-implement reads it and executes each phase in order. The playbook can encode much more than a checklist:

• Branch strategy: pick Git Flow, GitHub Flow, or trunk-based, plus the naming convention
• Development style: implementation first, TDD (tests first), BDD (E2E scenarios first) — push the AI through familiar engineering practices
• Quality gates: tests pass, lint, typecheck, coverage thresholds, all before opening a PR
• Review granularity: enforce a rule × file matrix so every rule hits every changed file, and decide whether to run a second opinion
• E2E scope: API-level only, or include browser E2E via Playwright
• Agent role allocation: instead of running everything on a single Claude Code or Codex agent, assign each phase to whichever model is strongest — for example "implement with Codex, review with Claude Code, test with Codex" (under multi-agent or multi-agent + cmux mode)

In other words, the playbook lets you use Claude Code and Codex together, mapping each engineering phase to the best agent rather than picking one and sticking with it. Once these decisions are written down up front, AI no longer drifts on "which phase am I in and what do I do next?"

Install with the npm skills CLI:

npx skills add anyoneanderson/agent-skills --skill spec-workflow-init -g -y

Trigger with natural language at the project root:

Generate development workflow
# or
ワークフローを生成して

The skill first runs environment auto-detection on:

• Package manager: pnpm-lock.yaml / yarn.lock / package-lock.json / bun.lockb
• Container: docker-compose.yml / Dockerfile
• CI/CD: .github/workflows/ / .gitlab-ci.yml / .circleci/
• Branch info: git branch -r
• Language, framework, scripts: package.json / go.mod / requirements.txt / pyproject.toml
• DB: prisma/schema.prisma and docker-compose entries
• Lint: .eslintrc* / biome.json
• Existing coding-rules.md / review_rules.md
• cmux environment: CMUX_SOCKET_PATH

Detection results are shown as a summary table for confirmation. Then the dialogue rounds run:

If you pick multi-agent, the skill writes workflow-implementer.md, workflow-reviewer.md, and workflow-tester.md into .claude/agents/ or .codex/agents/ (the Codex side uses TOML and also updates .codex/config.toml).

Finally, the skill offers to append a workflow reference to AGENTS.md or CLAUDE.md so later agents discover the workflow on boot.

Concrete example: the agent-skills repo itself uses a docs/issue-to-pr-workflow.md generated by this skill — full dogfooding.

How Does spec-rules-init Generate Coding Rules and Review Criteria?

spec-rules-init extracts rules from existing project conventions and emits docs/coding-rules.md (implementation quality gate) and docs/review_rules.md (review criteria).

Install and run:

npx skills add anyoneanderson/agent-skills --skill spec-rules-init -g -y

Generate coding rules
# or
コーディングルールを生成して

Sources are treated in three priority tiers.

The Priority 3 "installed skills" are not limited to agent-skills' own skills. Best-practice skills published by other vendors — such as vercel-react-best-practices from Vercel — are also picked up automatically once installed. If you let skill-suggest (covered later) install tech-stack-appropriate best-practice skills first, their accumulated knowledge becomes Priority 3 rules inside spec-rules-init.

Extraction categories are: Testing Standards, Code Quality, Error Handling, Documentation, Security, and Git. Each rule records its category, severity, source file, and line reference.

To strengthen the Priority 3 tier, pair skill-suggest with spec-rules-init. skill-suggest lives in the same agent-skills repo. It parses manifests like package.json, Cargo.toml, and go.mod, then proposes and installs best-practice skills from the skills.sh registry. Skills installed this way are automatically picked up by spec-rules-init as Priority 3 sources, so the two skills together give you a clean pipeline of "detect tech stack → install best-practice skills → extract rules."

npx skills add anyoneanderson/agent-skills --skill skill-suggest -g -y

Ask "Suggest skills for this project" and skill-suggest recommends skills that fit the detected stack.

A summary appears after extraction:

Extraction Results:
  Testing Standards:    8 rules
  Code Quality:         12 rules
  Error Handling:       5 rules
  Documentation:        4 rules
  Security:             3 rules
  Git:                  4 rules
  Total:                36 rules (Priority 1: 14, Priority 2: 18, Priority 3: 4)

You then pick the output path, fill in missing categories through targeted prompts, and finally choose whether to generate review_rules.md alongside. --with-review-rules skips the prompt; --no-review-rules skips the generation entirely.

Once generated, other agent-skills skills automatically reference these files:

• spec-generator: reads coding-rules.md as a design constraint during the design phase
• spec-inspect: uses [MUST] rules in Check 13 (Project Rule Compliance)
• spec-implement: enforces coding-rules.md as a quality gate during implementation
• spec-workflow-init: review phases reference review_rules.md
• cmux-second-opinion: uses review_rules.md for second opinions (see the dedicated cmux skills article for the three cmux skills)
• GitHub Actions: claude-review.yml can reference it

Concrete example: the agent-skills repo's own docs/coding-rules.md and docs/review_rules.md are generated by this skill.

What Changes When You Use Both Together?

With both skills run, later agents have a clear separation of "how to move", "how to write", and "how to review" — three files, three responsibilities:

.
├── AGENTS.md            ← read by every agent at boot
├── docs/
│   ├── issue-to-pr-workflow.md  ← how to move
│   ├── coding-rules.md          ← how to write
│   └── review_rules.md          ← how to review
└── .claude/agents/      ← role definitions (when multi-agent)

The crucial detail is the section both skills append to AGENTS.md / CLAUDE.md:

## Development Workflow
 
Follow the development workflow for Issue → Implementation → PR:
- [docs/issue-to-pr-workflow.md](docs/issue-to-pr-workflow.md) — Development workflow generated by spec-workflow-init
 
## Coding Rules
 
Follow the coding rules in these files during implementation:
- [docs/coding-rules.md](docs/coding-rules.md) — Quality rules generated by spec-rules-init
- [docs/review_rules.md](docs/review_rules.md) — Review criteria for code review and second opinion

That section means later agents (spec-implement, spec-code, spec-review, cmux-second-opinion) do not need to remember file names. They reach the right reference just by reading AGENTS.md on startup.

FAQ

Q. What if the project has no existing CLAUDE.md or AGENTS.md?

A. Both skills still work. spec-rules-init automatically falls back to a dialogue-only mode and asks targeted questions per category. spec-workflow-init similarly fills in any missing detection results through dialogue.

Q. Can I update the generated issue-to-pr-workflow.md or coding-rules.md later?

A. Yes. Re-running the skill triggers an existing-file detection dialog with overwrite, merge differences, and cancel options. --force skips the prompt.

Q. Does this work with agents other than Claude Code?

A. Yes. Any agent that supports the SKILL.md format works — Claude Code, Codex, Cursor, Gemini CLI, OpenCode. spec-workflow-init ships both Claude and Codex sub-agent templates and lets you pick targets in dialogue.

Q. What is the difference between coding-rules.md and review_rules.md?

A. coding-rules.md is the rule book that implementation agents (like spec-code) read while writing. review_rules.md is what reviewers (spec-review, cmux-second-opinion, GitHub Actions) consult to check what was written. Severity-based output policies (CI vs. review gate vs. second opinion) are defined only in review_rules.md.

Q. Does Stage 0 still work without cmux?

A. Yes. Round 6 of spec-workflow-init drops to a two-option choice (single / multi-agent) and the cmux-dispatch option hides. spec-rules-init does not depend on cmux at all.

Q. Should you grow these rules and workflows over time?

A. Absolutely — that is the intended usage. coding-rules.md, review_rules.md, and issue-to-pr-workflow.md are starting points. After generation, add repository-specific rules manually (this project uses Hook this way, this naming is forbidden, commit messages follow this format, license header is required, and so on). Keep them in Git and refine through PR review. Because later spec skills re-read these files every run, the thicker your rules grow, the higher the automation quality climbs. Start thin and accrete project-specific rules as you operate.

Q. Can I customize the .claude/agents/ or .codex/agents/ role definitions?

A. They are designed to be customized. The workflow-implementer.md, workflow-reviewer.md, and workflow-tester.md files generated by spec-workflow-init are templates as starting points. Edit them freely to match your project (for example: add DI guidance for the implementer in a NestJS project, add specific vulnerability patterns to the reviewer's mandatory checks, or pin a Playwright page-object convention for the tester). Both the Markdown and TOML files are plain text — bake in your project's "house style" and the agent output stabilizes accordingly.

Summary and What's Next

spec-workflow-init and spec-rules-init are the skills that generate agent-skills' "first foundation documents." Putting the development flow and quality rules into shared documents lets every later spec skill operate from the same reference point.

ZenChAIne dogfoods this approach as well: the agent-skills repo itself uses docs/issue-to-pr-workflow.md, docs/coding-rules.md, and docs/review_rules.md, and every new branch we cut starts from those files.

Part 2 (spec authoring) covers spec-generator, spec-inspect, and spec-to-issue — how to pull specifications out through dialogue, validate them, and convert them into GitHub Issues.

References

• agent-skills - GitHub
• spec-workflow-init SKILL.md
• spec-rules-init SKILL.md
• agent-skills - docs/issue-to-pr-workflow.md (dogfooding example)
• agent-skills - docs/coding-rules.md (dogfooding example)
• agent-skills - docs/review_rules.md (dogfooding example)
• What Are Agent Skills - ZenChAIne
• agent-skills open-source release - ZenChAIne
• skills.sh