Kata Agent Team

"What does the pattern of the Improvement Kata give us? A means for systematically and scientifically working toward a new desired condition, in a way that is appropriate for the unpredictability and uncertainty involved."

— Mike Rother, Toyota Kata

The Kata Agent Team is an autonomous and continuously improving agentic development team running on GitHub Actions, organized as a daily Plan-Do-Study-Act (PDSA) cycle. Agents plan by writing specs, do by shipping features and hardening the repo, study their own execution traces and outputs, and act on findings — closing the loop every day. The name follows Toyota Kata: agents grasp the current condition (via prior-run traces), establish target conditions (via specs), and experiment toward them (via implementation). Six agent personas, five workflows, sixteen skills form this cycle.

This page is the internal-contributor entry point. The canonical reference is KATA.md at the repo root — read by every agent at the start of every Kata run. This page renders that material under the Kata brand for human contributors.

The Six Personas

Staff Engineer

The drafting bench. Owns the full spec → design → plan → implement arc for approved specs. Plan and Do.

Release Engineer

The shipping bay. Keeps PR branches merge-ready, repairs trivial CI, cuts releases. The sole external merge point. Do.

Security Engineer

The night watch. Patches dependencies, hardens supply chain, enforces security policies. Do, Study, Act.

Product Manager

The kanban rail. Triages issues, reviews spec quality, runs evaluations. Gates spec quality off the critical path via the spec:approved label. Study, Act.

Technical Writer

The archivist's desk. Reviews docs for accuracy, curates wiki, fixes staleness, files spec gaps. Study, Act.

Improvement Coach

The Ohno circle. Facilitates storyboard meetings and 1-on-1 coaching sessions. Reads traces. Study.

The PDSA Loop

Every workflow belongs to a phase of the Plan-Do-Study-Act cycle (after Deming). Findings from Study always re-enter the loop as specs or fix PRs — nothing is observed without downstream action.

Plan — Turn approved spec.md (WHAT/WHY) into design.md (WHICH/WHERE) then plan-a.md (HOW/WHEN) with steps, files, sequencing, risks.
Do — Execute plans via implementation PRs; run scheduled workflows that harden, release, and maintain. Every run captures a trace.
Study — Analyze Do outputs across four streams: security audits, external feedback triage, one-topic-deep doc review, one-trace-deep grounded theory.
Act — Trivial findings become pushed fix PRs; structural findings become spec.md documents on pushed spec branches. A local commit is not a PR — the URL is the only valid completion signal. fix/ and spec/ branches never mix.

The Trust Boundary

The Release Engineer is the sole external merge point. All other merge paths operate on trusted sources (our agents, Dependabot). The Product Manager gates spec quality off the critical path via the spec:approved label.

External PR type	What merges	Who implements
`fix` / `bug`	Contributor's code (small)	The external contributor
`spec`	Specification document only	Trusted agents, never the contributor
Everything else	Nothing — requires human review	N/A

Top-7 contributors pass the trust gate; kata-agent-team PRs are trusted by identity. A compromised top contributor cannot inject code via this pipeline — specs merge only the document, not code.

The Workflows

A single scheduled kata-shift workflow runs the producer → reviewer → shipper chain three times daily on a Europe/Paris rhythm — 03:00, 12:00, and 20:00 — plus the daily storyboard at 08:00, an event-driven kata-dispatch workflow on PR and issue activity (and on workflow_dispatch from the bridge services for threaded discussions), and two on-demand workflows dispatched manually: kata-coaching and kata-interview.

Workflow	Schedule (Paris, CEST)	Agent
kata-storyboard	Daily 08:00	improvement-coach (facilitates 5 agents)
kata-coaching	`workflow_dispatch`	improvement-coach (facilitates 1 agent)
kata-shift	Daily 03:00 · 12:00 · 20:00	product-manager → staff-engineer → security-engineer → technical-writer → release-engineer → improvement-coach
kata-dispatch	On PR / issue activity (and bridge dispatch)	release-engineer (facilitates up to 4 agents)
kata-interview	`workflow_dispatch`	product-manager (supervises 1 interview agent)

The kata-shift matrix runs sequentially in declaration order on every invocation: the product manager triages and approves spec quality so staff has a fresh backlog, staff implements, security-engineer reviews code before it ships, technical-writer reviews docs, release-engineer gates and ships, improvement-coach reviews the run. Adding or removing an agent is a one-line edit to the matrix in .github/workflows/kata-shift.yml.

Coordination Channels

Four channels carry agent-to-agent and agent-to-human collaboration. Shared memory (wiki, weekly logs, settled decisions) is owned separately by memory-protocol.md.

Channel	Use for	Lifetime	Mechanism
Storyboard	Daily current condition and next experiment	One day; captured into wiki	`kata-storyboard` workflow
Discussion	Open questions before they become decisions	Open until resolved into spec or wiki	`ghbridge` → `kata-dispatch`
PR / issue thread	Real-time response on a specific artifact	Lives with the artifact	`kata-dispatch` workflow
Sub-agent	Specialized inline work within one run	Ephemeral (one task)	`Agent` tool, skill spawning

Per-output coordination is governed by coordination-protocol.md.

Metrics

Agents record time-series data to wiki/metrics/{skill}/{YYYY}.csv after each run. The CSV schema (six fields: date, metric, value, unit, run, note), storage convention, and metric design are documented in KATA.md § Metrics. The storyboard meeting answers "what is the actual condition now?" with numbers, not narratives, and XmR process behavior charts distinguish stable processes from special-cause reactions.

Authentication

Workflows authenticate via the GitHub App kata-agent-team, not a PAT. Each run generates a 1-hour installation token via actions/create-github-app-token — no long-lived secrets to rotate. The token must generate before actions/checkout so checkout-token writes trigger downstream workflows.

Permission	Why
Contents	Checkout, commit, push to `fix/`, `spec/`, release branches
Pull requests	Open, comment, merge PRs (release-engineer, product-manager)
Issues	Triage, label, comment (product-manager)
Discussions	Reply on discussions and discussion comments (ghbridge → kata-dispatch)
Workflows	Token-driven pushes re-trigger downstream workflows
Metadata	Required by GitHub

Where Each Agent Lives

Agent	Profile
Staff Engineer	staff-engineer.md
Release Engineer	release-engineer.md
Security Engineer	security-engineer.md
Product Manager	product-manager.md
Technical Writer	technical-writer.md
Improvement Coach	improvement-coach.md