Specs Tell Your AI Agent What to Build. Nothing Tells It Why.

A teammate joins your feature halfway through the sprint. Their agent reads every file in seconds. They still spend the next two days asking you why half of it was built that way.

Next quarter, product asks to extend the same feature. The new code quietly breaks a rule the approver set in week two, because that rule was never written down. Months later a bug comes in, the original developer has moved on, and the agent "fixes" a decision someone fought for. Each time, the agent can read the code but not the reasoning behind it, so it guesses.

That missing reasoning is what I built Agentic Playbook to keep.

Spec-driven development answers what. Nothing answers why

Spec-driven development has been one of the best changes to AI-assisted coding. Instead of prompting an agent with a vague request, you turn the requirement into a spec, the spec into tasks, and the tasks into code. Tools like GitHub's Spec Kit and Kiro made this mainstream, and it works: agents build far better from a clear spec than from a chat message.

But a spec is scoped to one change and ends when that change is done. Everything that happens around it while a feature is being built lives in chats, meetings and people's heads:

• the analysis of what already existed in the code
• the questions that came up mid-build and how they were answered
• the standing rules the approver set along the way
• the alternatives that were rejected, and why
• which commit and which ticket delivered which requirement

That is exactly the knowledge a project needs to move fast with more than one developer, and the first thing it loses when people change.

The playbook sits one level above the spec

Agentic Playbook keeps one folder per feature, outside the product repos, as the feature's working memory for its whole life. Specs still drive each task. The playbook records everything around them as you build:

	Spec (spec-driven development)	Playbook
Scope	One change or task	The whole feature, from intent to release and beyond
Answers	What to build	What, why, who decided, and what shipped
Holds	Requirements, design, tasks	Requirements and acceptance criteria, analysis, decisions, directives, task progress
Links to	The code it produces	Every commit, PR and tracker ticket, per requirement
Lifespan	Done when the task is done	Lives as long as the feature does

Each file has one job:

• 00-REQUIREMENTS.md — what must be true, with acceptance criteria
• 01-ANALYSIS.md — what existed in the code before anything changed
• 02-PLAN.md — phases, tasks and an approval header; no code before it says approved
• 03-DECISIONS.md — every open question, its answer, who gave it and when
• 05-DIRECTIVES.md — the approver's standing rules, word for word
• 04-TRACEABILITY.md — requirement → task → test
• PROGRESS.md — every task with its commit, branch, PR and ticket, plus a session log

How a feature moves through its playbook

Here is a refund feature for an e-commerce app, from first idea to months after release.

1. Intent. A developer types /playbook new and one sentence: "customers should be able to request a refund from their order page." A requirement interview (my Agentic Prompt skill, or a built-in one) reads the code first, asks four questions, and writes requirements with acceptance criteria. "Above what amount does a human review it?" goes to the product lead as an open decision instead of being guessed.
2. Analysis and plan. The agent maps what can be reused (an existing payment gateway with a refund call) and what's missing (a refunds table), then breaks the work into five tasks. It stops. Nothing is built until the product lead approves the plan.
3. Building, one spec at a time. Each task is built from its own spec, spec-driven as usual. When a task is done, its row in the playbook records the commit, the branch, the PR and the test results, and the tasks waiting on it are unblocked.
4. Decisions land mid-build. The product lead answers: refunds of ₹5,000 or more go to manual review. The answer is recorded with who said it and when, the blank in the requirement is filled in, and the blocked task starts.
5. A rule changes the plan. The approver adds a standing directive: no refund for an order with an open chargeback. It's recorded word for word, and a new task is added to enforce it, linked to the requirement it protects.
6. A second developer joins. On a different machine, with a different agent, they open the same playbook. In one read their agent knows the phase, the next task, every decision and the directive. No handover meeting.
7. The feature grows. Next quarter, product wants partial refunds per item. The new requirement goes through the same interview, and the agent checks it against existing decisions and directives before planning. The chargeback rule still applies, and the plan says so.
8. A bug, months later. The agent traces it to the task, the commit and the decision behind it, fixes the real defect without undoing the ₹5,000 rule, and records the fix.

At no point did anyone write documentation as a separate chore. The playbook filled up as a side effect of building the feature.

Keeping it true is an algorithm, not a habit

A shared record is only useful if it's correct, and documentation usually rots. A task finishes, someone updates one row, and the phase header, the traceability table and the task that was waiting on it all go stale.

The playbook treats this as a data problem. Every fact has exactly one owning file and is referenced everywhere else by ID. After any change, a ripple sweep runs: write the fact in its owner, find every reference to its ID, update the dependents, then recompute the derived fields — current phase, next action, traceability status — from the task rows. One answer from the product lead updates the decision, the requirement and the blocked task in one pass. An audit script catches what slips: a done task with no evidence, or a phase marked complete while a task in it isn't.

Git first, your tracker if you have one

Progress is tracked from git, because every developer already has it: the commit, the branch, whether it's pushed, the PR, the test result. When an agent did the work and nothing is committed yet, the row records what changed and which tests ran. If your team uses Jira or Linear, plug in your own skill on an event — create an issue when a task is added, post a solution report when it's done — and the ticket key joins the evidence. The playbook never changes a ticket's status.

Specs build the task. Playbooks carry the project

Spec-driven development made agents better at building one change at a time. Real projects are many changes, by many people, over months: handovers, new requirements on old features, decisions that have to survive the people who made them. That work runs on knowing why the code is the way it is.

Agentic Playbook is MIT-licensed and works in Claude Code, Cursor and any agent that reads a skill file. Shared context doesn't make every agent produce identical output, but it means every agent starts from the same facts instead of guessing. Try it on your next feature: github.com/Gowrishankar4/agentic-playbook.