agentic-coding
My clod skill for agentic coding workflows
Star 0
Fork 0
Watch
6 1 0
Files
.claude-plugin
commands
hooks
scripts
skills
templates
.gitignore
DEVELOPMENT.md
HANDOFF.md
PREFERENCES.md
README.md
README.md

agentic-dev #

A phased process for building software with coding agents, plus the document templates it runs on.

The idea #

Four files, each with a different job and a different lifetime:

File What it is
DESIGN.md What you're building. Starts rough, becomes a rigorous spec.
DEVELOPMENT.md The method. How the build proceeds, phase by phase.
PLAN.md Where the build actually stands right now.
AGENTS.md The rules, always loaded into context.

There is a fifth, optional, and it does not live in the project: PREFERENCES.md holds your standing defaults — "I always want Postgres" — and stays here as a single master copy. Phase 1 looks for agents/PREFERENCES.md first, then falls back to this one, so a project can override without anyone maintaining two copies.

It is used to propose answers, never to skip questions. A preference that silently becomes a decision is how a project ends up with an architecture nobody chose — which is exactly what happened to the second project built this way.

The one that surprises people is DESIGN.md, because it has three lives:

  1. Start — whatever you already know you want. Rough, gaps, contradictions, whole sections empty. This is the normal starting state.
  2. The gauntlet — the Clarification phase reads it, finds the ambiguities and the decisions nobody has made, and interviews you until they're resolved. The answers get written back in.
  3. After — the master spec. Every later phase reads it. PLAN.md follows from it.

So you do not need to have it all worked out before you begin. That is what the first phase is for.

Starting a project #

mkdir -p newproject/agents
cp agentic-dev/DEVELOPMENT.md newproject/agents/
cp agentic-dev/templates/DESIGN.md newproject/agents/
cp agentic-dev/templates/PLAN.md newproject/agents/
cp agentic-dev/templates/AGENTS.md newproject/AGENTS.md

AGENTS.md goes at the project root, not in agents/ — that is where coding agents look for it automatically. If your tool reads CLAUDE.md instead, leave a one-line CLAUDE.md at the root containing See [AGENTS.md](AGENTS.md). so both work.

Then:

  1. Open agents/DESIGN.md and write what you know. Leave the rest blank.
  2. Start a session and point it at agents/DEVELOPMENT.md.
  3. Phase 1 does the rest — it will interview you, and it should ask a lot.

What the process is opinionated about #

Worth knowing before you adopt it, because these are the parts that cost something:

It stops and asks. There are mandatory checkpoints — schema decisions before the database exists, concurrency approach before domain logic — where the process requires polling you rather than deciding. These exist where a wrong choice is cheap now and expensive later.

It has a theory of evidence. Verification must use the project's own documented path, not a harness built for the occasion. Booting infrastructure is verification; validating its config file is not. Green unit tests are evidence about a slice, never about the system. Most of the value in this process is here: the default failure mode of coding agents is confidently reporting success on things that were never run.

It runs agents in parallel, with rules. Concurrent agents get explicitly disjoint file ownership, only the orchestrator touches git, and interface contracts between agents are fixed in writing before either side starts. The rules exist because each one corresponds to something that has actually gone wrong.

It writes down why. PLAN.md keeps a dated log of every decision made with the owner, including what was rejected. Six months later that is the difference between a considered design and one nobody can defend.

The Claude Code layer (optional) #

Everything above is plain markdown and works with any coding agent. If you use Claude Code, this directory is also installable as a plugin, which adds enforcement for the two rules that matter most and are most often skipped.

The markdown remains the source of truth. Every rule the machinery enforces is also written down in prose, so another tool loses the enforcement, not the rule.

Hooks #

Hook What it does
Stop Runs your test suite when a turn tries to end and refuses to finish while it is red.
SessionStart Puts the current phase status from PLAN.md in front of a session that is starting cold.

The git hook that isn't here #

"Agents never run git" is the rule this process most wants enforced, and it cannot currently be enforced by a hook. Tested against Claude Code 2.1.220:

  • PreToolUse input carries no agent_id and no agent_type.
  • transcript_path is the main session's path even when a subagent issued the call, so the on-disk <session>/subagents/agent-<id>.jsonl layout cannot be used to identify the caller.
  • session_id likewise does not vary by subagent.

scripts/deny-git-in-subagent.py is kept, with its tests, because the detection is a one-line change if a future version exposes the caller. It is deliberately not wired into hooks.json.

That decision is the point rather than an oversight. A hook you believe is enforcing a rule, which silently isn't, is worse than no hook at all — you stop restating the rule in dispatch prompts, and lose the only protection you had. So the rule stays prose, in DEVELOPMENT.md and AGENTS.md, and keeps appearing in every dispatch prompt.

Set AGENTIC_DEV_HOOK_LOG=/path/to/log.jsonl to have the hook scripts append their input and decision. A hook that is not firing looks exactly like a hook that is firing and deferring; this is how you tell them apart, and it is how the above was established.

The Stop hook does nothing until you configure it. It reads .claude/agentic-dev.json from the project root:

{
  "testCommand": "docker compose -f compose.dev.yaml exec -T api pytest api/tests",
  "testTimeoutSeconds": 600,
  "maxConsecutiveBlocks": 2
}

No file means no interference — a hook that guessed how to test your project and blocked your turns would be worse than no hook at all.

Blocking a turn makes the model continue, which produces another turn, which is a loop if the failure is one it cannot fix. Claude Code documents no built-in guard for this, so there is a local one: after maxConsecutiveBlocks the hook stands down and lets the turn end with the failure reported. Trapping you is worse than letting a red suite through.

The SessionStart hook injects state, not instructions. It reads only the phase-status table and the checkpoint list from PLAN.md — deliberately not the decision log, deferred work, or notes for later phases, which are read on demand when they matter and would otherwise cost context on every session to serve a minority of them.

It stays silent in a project with no agents/PLAN.md, and silent in one that has been scaffolded but not started, so a blank phase table is never injected. It does not fire on compaction — after a compaction the model has just been handed a summary of the same session — and it does not fire for subagents at all, which get their context from their dispatch prompt.

Skills and commands #

  • /kickoff — scaffolds the four documents into a new project, puts AGENTS.md where tools actually look for it, and hands off to Phase 1. If you already have notes on what you want to build, it uses them as-is rather than tidying them — the rough version is the input Phase 1 needs.
  • dispatch-phase-agent — loads when you are about to launch agents. The dispatch-prompt template, wave planning from the dependency graph, and the clauses that each exist because omitting one caused a real failure.

Installing it #

For a single session:

claude --plugin-dir /path/to/agentic-dev

Changes to skills take effect immediately; changes to hooks need /reload-plugins.

Adapting it #

Not every phase applies to every project. A CLI tool has no UI phase; a library has no deployment phase; a single-operator tool may need a shared secret rather than an authentication system. Decide during clarification, record it in PLAN.md's phase table, and skip phases explicitly rather than silently — a skipped phase should be visibly skipped, so nobody later has to guess whether it was decided against or forgotten.

One thing to watch: any technology choice that ends up stated as fact in DEVELOPMENT.md stops being a question the clarification phase asks, and quietly becomes the next project's default. Keep the method free of stack decisions; they belong in DESIGN.md.