A minimal practice for building software with AI agents.
It gives your projects a small amount of structure:
- Contracts, guardrails, workflows and practices stored in markdown that keep projects coherent while leaving agents free to explore
- 5 workflow skills: project-kickoff · build · review · harmonize · knowledgebase-kickoff
- 1 setup skill: kata-init
- no instruction-file patching — skills route themselves through their descriptions and point to the central rules
Zero footprint. No install, no dependencies, no external services. Just markdown files loaded by your agent at runtime. Boring in the best way.
- skill descriptions route the agent to the right skill; each skill reads the central rules
- project docs define architecture, contracts, and constraints
- the agent builds or reviews within those boundaries
- as the project grows, you can move from Light to Standard to Full tiers
- living docs (
PLAN.md,DECISIONS.md) capture state that evolves — refreshed as you work, or in one pass via the review skill's Refresh mode
Have you also noticed that AI agents often start well, then drift?
They explore alternatives and follow the conventions for a while, then gradually drift. Complexity crept in. The original shape of the project gets blurred. Fragility appears in random places. Instructions like use schemas, enforce invariants, or write are quietly forgotten. The agent would get stuck on the same approach and stop exploring.
A common reaction is to add more: more specialized agents, more orchestration, more complex setups. In practice this often makes things worse. Complex setups age badly and quickly become obsolete in a fast-moving agent ecosystem.
- A few months ago: we used few-shot prompting and asked agents to "act like a professional chef" in order to get a recipe
- Yesterday: we carefully hand-crafted and orchestrated dozens of specialized agents
- Today: models can generate those agent instructions for us
- Tomorrow: the model will likely create and run multiple agents under the hood from a single prompt
If a pattern works, frameworks eventually automate it. Over-engineering agents may become obsolete sooner than you think. So, KISS 💋.
So the real need is not more control. It is better structure. Kata Engineering gives agents elegant boundaries without over-constraining them. The architecture persists. Decisions are recorded. Constraints are testable. The agent remains free to explore, but not free to quietly deform the project.
A project's docs are not only for humans. They are loaded into agent context on every session — they are the codebase, too. That is why the discipline below treats them as load-bearing artifacts, not afterthought documentation.
In martial arts, a kata (型) is a sequence of movements practiced until they become instinct — correct form achieved not through supervision, but through deeply internalized principle. Elegance comes from discipline. Nothing is added that doesn't belong.
Dave Thomas introduced the concept of code kata to help developers practice and refine their craft. Kata Engineering extends that idea to AI agents.
This repository is itself a light-tier Kata project — all docs, no code. This README serves as its architecture doc.
kata-engineering/
├── README.md # This file — also the repo's architecture doc
├── INITIAL_PROMPT.md # Origin story: the prompt that started this project
├── rules/
│ ├── coding.md # Universal coding practices
│ └── testing.md # Universal testing practices
├── skills/
│ ├── kata-init/
│ │ └── SKILL.md # Global setup for Codex and Claude
│ ├── project-kickoff/
│ │ └── SKILL.md # Optional first step: refine an idea before building
│ ├── build/
│ │ ├── SKILL.md # Build skill (bootstrap + orient + build + verify + close)
│ │ └── templates/ # Project scaffolding templates
│ │ ├── architecture-light.md # Stable docs — tiered
│ │ ├── architecture-standard.md
│ │ ├── architecture-full.md
│ │ ├── contracts-standard.md
│ │ ├── contracts-full.md
│ │ ├── plan.md # Living docs — tier-agnostic
│ │ └── decisions.md
│ ├── review/
│ │ └── SKILL.md # Review skill (focused + health + tier + refresh)
│ ├── harmonize/
│ │ └── SKILL.md # Harmonize filenames and folder layout for product-readability
│ └── knowledgebase-kickoff/
│ ├── SKILL.md # Bootstrap a knowledge base for stakeholder-heavy projects
│ └── templates/ # KB scaffolding (SCHEMA, CLAUDE, PLAN, ingest-sources skill, …)
└── examples/
├── greenfield-project-prompt.md # Prompt for starting a new project from scratch
├── brownfield-rework-prompt.md # Prompt for reworking an existing project
└── review-prompt.md # Prompt for a full project health review
There are five workflow skills. The first four are used in sequence for new projects, and independently for ongoing work; knowledgebase-kickoff bootstraps knowledge bases rather than codebases. The separate kata-init skill is only for installing or refreshing the global Codex/Claude setup.
Use this before build when the idea is fuzzy. It interrogates the concept, challenges weak assumptions, and produces a Project Brief, Research Brief, and Execution Plan. It ends with a refined prompt ready to hand to the build skill.
Skip it when the idea is already clear.
The core skill. Covers the full lifecycle of a coding task:
- Bootstrap (once, on new projects) — pick a tier, scaffold architecture docs and living docs
- Orient — read project context, understand scope
- Build — implement the change
- Verify — run tests, check contracts, simplicity check
- Close — update affected docs, capture lessons, commit
The agent determines which phase to start from automatically. On a new project with no docs, it starts at Bootstrap. On an existing project, it starts at Orient.
Close runs the compounding loop: corrections received during the task are routed into the project's docs (project-specific lessons) or proposed as additions to the central rules (universal lessons), so the practice improves with every session instead of repeating mistakes.
| Mode | When | Edits files? |
|---|---|---|
| Focused | After a change, before merge | No |
| Health | Periodic, or when something feels off | No |
| Tier | After a tier upgrade, before a handoff | No |
| Refresh | When living docs have drifted from reality | Yes — living docs only |
Focused, Health, and Tier are diagnostic: they produce findings, not edits. Refresh is the only mode that writes, and it writes only to living docs (PLAN.md, DECISIONS.md).
| Mode | When | Edits files? |
|---|---|---|
| Propose | First pass — surface rename candidates without touching anything | No |
| Apply | Execute approved renames, update imports + doc refs, run tests | Yes |
| Review | Fresh-eyes pass over a plan or applied diff produced by another agent | No |
Use when filenames and folder layout no longer match the product vocabulary — names that mislead, undersell what a file owns, or reflect historical accidents. The skill insists on building independent assumptions before reading any prior plan, so the fresh-eyes signal stays honest.
Bootstraps a project whose deliverable is current knowledge rather than code: raw sources (emails, transcripts, documents) flow into LLM-maintained entity pages, forming a queryable, auditable source of truth. Scaffolds the folder skeleton, SCHEMA/CLAUDE/README docs, and an ingest-sources skill for the new project. Use it for stakeholder-heavy projects — many meetings, suppliers to hold accountable, decisions to trace.
Project docs fall into two categories with different discipline:
Stable docs describe what the project IS and what MUST hold true. They change only when the underlying design changes. Casual edits erode their authority.
Living docs describe current state. They go stale quickly — staleness is a defect. They are checked on every Close phase and can be batch-refreshed via the review skill's Refresh mode.
| Kind | Light | Standard | Full | |
|---|---|---|---|---|
ARCHITECTURE.md |
stable | ✓ | ✓ | ✓ |
CONTRACTS.md |
stable | ✓ | ✓ | |
| Schema definitions | stable | ✓ | ✓ | |
| Coupling guardrail tests | stable | ✓ | ||
| Structural integrity tests | stable | ✓ | ||
| Change governance | stable | ✓ | ||
DECISIONS.md |
living | optional | optional | ✓ |
PLAN.md |
living | optional | optional | recommended |
Use light for scripts and personal tools. Standard for projects with APIs, persistence, or multiple modules. Full for production systems that need governance.
Setup is symlinks only. Clone this
repository once, then run the kata-init skill from the repository root —
or ask your agent to follow
skills/kata-init/SKILL.md. It symlinks the
skills into each agent's global skills directory (~/.claude/skills,
~/.codex/skills). Skills route themselves: the agent picks them by their
descriptions, and each skill points to the central rules/ in this repository.
Edits to this repository are picked up by all projects automatically.
Project-level AGENTS.md or CLAUDE.md files stay focused on
project-specific constraints.
If you want an agent to initialize a computer from GitHub, use a prompt like:
Clone
https://github.com/pensiero/kata-engineeringinto a sensible local projects directory, then followskills/kata-init/SKILL.mdfrom the cloned repository to configure the agents installed on this machine.
For agents that support the SKILL.md format, symlink skills/ into their
skills directory the same way. For agents that don't, copy or reference
rules/ and the relevant SKILL.md files from the agent's configuration —
the skills are plain markdown and work anywhere text is read.
Rules encode preferences and practices. They grow through the build skill's lesson capture at Close, and they shrink through periodic consolidation. Every few weeks — or when agent performance degrades:
- Review rules for contradictions or bloat; merge overlapping rules; remove rules that no longer apply
- Promote recurring lesson entries (captured in project docs by
buildClose) into rules; drop the originals - Verify the skills still match your workflow
When editing any rule or skill:
- Write instructions, not descriptions — tell the agent what to do, don't restate what the code already shows
- Refer to artifacts by descriptive name (e.g. "the architecture doc"), not by exact path — paths churn, names survive
- Add new rule files as needed; reference them from the skills that should read them
Once deployed, your agent picks up the right skill automatically via AGENTS.md. Just work naturally — no special syntax needed. If a project has no architecture docs yet, the agent will bootstrap them before proceeding — even for small tasks.
The following are sample prompts:
New project from a rough idea (uses project-kickoff, then build)
I want to build a CLI tool that syncs files between two directories. Help me think it through first. Use project-kickoff skill.
New project with a clear idea (uses build directly)
I want to build a CLI tool that syncs files between two directories. It's a personal utility, keep it light.
Feature on an existing project
Add pagination to the /users endpoint.
Existing project with no docs yet
This project has no architecture docs. Let's set them up from the existing code.
Review
Review the changes I just made to the auth module.
Planning phased work
Let's create a plan. I want to break the remaining work into phases — authentication first, then the API layer, then the CLI.
Refreshing living docs
Refresh the living docs. I've done a few sessions of work and PLAN.md is out of date.
Tier upgrade
This project has grown. Let's upgrade from light to standard.
For longer, multi-phase tasks, use the ready-made prompts in examples/:
- Start a new project from scratch — full bootstrap with tier selection, architecture docs, schemas, and initial tests
- Rework an existing project — restructure docs and contracts for a project that already has working code
- Full project health review — periodic check on architecture accuracy, contract health, tier compliance, and complexity