# Team Templates

Course: [Intent Engineering](https://www.devtutorials.ai/learn/intent-engineering) · Section: Review and Scale
Source: https://www.devtutorials.ai/learn/intent-engineering/review-scale/team-templates

> Scale specs across a team: a spec-review skill calibrated on graded examples, a definition of ready, and matching the spec's depth to the size of the change.

## A Review Skill That Passes Everything

A **skill** is a file of instructions an agent loads for one job. In this lesson, you will write a skill that reviews specs. Then you will test that it really works.

Your team now writes specs before building.

Someone made a **spec-review skill** to check them.

It has only two rules:

- Check spelling.
- Make sure the spec looks professional.

### A Real-World Example

You put up a new smoke alarm.

You press the test button to make sure it works.

- An alarm that never rings is useless.
- An alarm that rings every time you make toast gets switched off.

A review skill is the same. It must catch the bad specs and let the good ones through.

Six specs go through the skill.

- Three are strong.
- Three are weak.

The skill lets all six through.

Click the button and open the card.

Press **Check my spec** with the starting skill.

- The checker says the first weak spec passes.
- It should have failed.

**Simple lesson:** a review skill is only as good as its rules. Test the rules on specs you already know are good or bad.

## TL;DR

1. **Skill** = a Markdown file (`SKILL.md`) an agent loads for one job.
2. **Spec-review skill** = a skill that checks a spec before anyone builds from it.
3. A good rule finds **one** clear problem that anyone can check.
4. Good rules catch:
   - vague words like "fast";
   - a requirement with no acceptance criterion;
   - an outcome with no number;
   - no non-goals;
   - a risky action with no decision rule.
5. **Calibration** = testing the skill on specs you already graded.
   - Weak specs must fail.
   - Strong specs must pass.
6. **Definition of ready** = the team checklist for when an agent may start.
7. Small changes need small specs. Big, long-lived changes need the full set of files.

## What You Will Learn

In this lesson, you will learn:

1. What a skill is.
2. How to write review rules a checker can apply.
3. How to test those rules on graded specs.
4. What a definition of ready is.
5. How much spec each change needs.

**About the checker in this lesson**

- Fixed rules check your skill. No AI reads it.
- Each rule you write matches one known problem, like vague words.
- The rules run on six fixed specs, so your result is the same every time.

## Skills

### A File for One Job

A skill is a short Markdown file.

It usually has:

- a name;
- a description;
- instructions;
- rules.

The agent loads the skill when the task matches it.

One skill should do one job. For example:

- a planning skill helps write plans;
- a review skill checks specs;
- a docs skill writes project docs.

A shared review skill means every spec gets the same checks, no matter who starts the review.

### Rules a Checker Can Apply

Some rules cannot be checked the same way twice.

Example:

```text
Make sure the spec looks professional.
```

Two people will read this rule in two different ways.

A good rule names one problem you can see in the spec.

Examples:

- Reject vague words like fast, easy, gracefully or user-friendly.
- Reject any requirement with no acceptance criterion that names it.
- Reject an outcome with no number.
- Reject a spec with no non-goals.
- Reject a risky action with no decision rule.

You met each of these problems earlier in the course.

**Simple lesson:** a good rule names one problem you can point at.

## Calibration

**Calibration** = running your skill on specs that people have already graded, to see if it judges them right.

### Fail the Weak, Pass the Strong

A **calibration set** = a few specs you already know are weak or strong.

Run the skill on all of them. Then look at the results.

- A weak spec passed? **A rule is missing.**
- A strong spec failed? **A rule is too strict.**

The goal:

```text
Fail every weak spec.
Pass every strong spec.
```

Watch the skill improve, one rule at a time:

Each new rule caught one more weak spec. The strong specs passed every time.

Each rule also catches only its own problem:

**Simple lesson:** one rule, one problem. Then you always know which rule to fix.

**Important:** write the rule about the real problem, not a nearby word.

- "Reject any spec that mentions a migration" also blocks good specs.
- The real problem is a migration with **no decision rule**.

## Definition of Ready

### When May an Agent Start?

A definition of ready is a short team checklist.

- If a spec passes every item, an agent may start.
- If it fails one, the spec goes back to its author.

Common checks:

- `intent.md` names a user.
- The problem says what it costs.
- The outcome has a number.
- An owner is named.
- Every requirement has an acceptance criterion.
- Non-goals are written down.
- Risky actions have a decision rule.

Watch a checklist sort five specs from the backlog:

"It looks finished" let everything in. Three real checks blocked the three unready specs.

**Simple lesson:** a checklist only helps if each item is something you can check.

### Lab Exercise: Write Your Team's Definition of Ready

This is a **Tech-lead extra**. In many teams, the tech lead owns this checklist.

The lab shows five backlog specs.

- Two are ready.
- Three are not.

Your task: write `ready.md`, one rule per line.

The checker runs your list on all five specs. You pass when the ready ones get in and the others are blocked.

## Match Spec Depth to the Change

### Specs Are a Tool, Not a Ceremony

A spec exists to lower risk and make the work clear.

It is not paperwork.

Not every change needs the same amount of spec.

- Too much spec for a tiny fix wastes time.
- Too little spec for big work leads to guesses.

Birgitta Böckeler describes three ways teams use specs:

- **Spec-first** = write the spec before building.
- **Spec-anchored** = keep the spec up to date while the code changes.
- **Spec-as-source** = the spec is the main source of truth.

A simple guide:

| The change | The spec it needs |
|---|---|
| Fix a typo | A clear ticket or a short spec |
| Add a tooltip | `spec.md` with requirements and acceptance criteria |
| A new export API others depend on | The full set: `intent.md`, `spec.md`, `plan.md`, kept up to date |

**Simple lesson:** the bigger and longer-lived the change, the more spec it needs.

### Lab Exercise: Calibrate the Spec-Review Skill

Go back to the lab card at the top of the lesson.

Replace the loose rules with real ones. Your skill must:

- fail S1, S2 and S3;
- pass S4, S5 and S6.

Press **Check my spec** until you get 6 of 6.

Each weak spec has one main problem. Find it, then write one rule that catches it.

## What Changes per Tool

| Tool | Location of the spec-review skill |
|---|---|
| Claude Code | `.claude/skills/spec-review/SKILL.md` |
| Codex | `.agents/skills/spec-review/SKILL.md` |
| Cursor | `.cursor/skills/spec-review/SKILL.md` |
| Spec Kit | Installed as a prompt or integration-specific skill |
| Kiro | Defined through steering files or agent hooks |

The course export puts the review skill in the right folder for your tool.

## Common Mistakes

| Mistake | Wrong idea | Correct idea | What goes wrong |
|---|---|---|---|
| Rules like "check spelling" | Neat specs are good specs. | Write rules about real problems. | Weak specs get through. |
| No calibration | "The rules look right." | Test the skill on graded specs. | You never find out what it misses. |
| A rule that is too strict | "Reject every migration." | Reject a migration with no decision rule. | Good specs fail, and people stop using the skill. |
| No definition of ready | "Any spec will do." | Keep a short team checklist. | Agents start on half-written specs. |
| The full set of files for everything | "More spec is always safer." | Match the spec to the change. | Small fixes take far too long. |
| No spec for big work | "We will figure it out." | Use the full set for long-lived features. | The agent guesses, on a big change. |

## Exercises

These exercises help you practise writing review rules and checklists.

Press **Check** when you are ready. Use **Show Hint** if you get stuck.

## What to Remember

- A skill is a file of instructions for one job.
- A spec-review skill checks a spec before anyone builds from it.
- Each rule should find one clear problem.
- Calibration tests the skill on specs you already graded.
- A weak spec that passes means a rule is missing.
- A strong spec that fails means a rule is too strict.
- A definition of ready says when an agent may start.
- Match the size of the spec to the size of the change.

## Further Reading

- [Understanding Spec-Driven Development: Kiro, spec-kit, and Tessl, by Birgitta Böckeler](https://martinfowler.com/articles/exploring-gen-ai/sdd-3-tools.html): spec-first, spec-anchored and spec-as-source.
- [GitHub Spec Kit](https://github.com/github/spec-kit): a constitution as a team-wide definition of ready.
- [Kiro steering](https://kiro.dev/docs/steering/): team rules every spec inherits.

Next: **Spec Capstone**. You will use everything from the course to write one complete spec, from start to finish.