Kata
"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
Kata is the Forward Impact repo self-maintenance system: autonomous agents on GitHub Actions that keep the codebase secure, release-ready, and steadily improving. 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, eight workflows, eighteen skills, organized around a daily Plan-Do-Study-Act loop.
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. Do.
Security Engineer
The night watch. Patches dependencies, hardens supply chain, enforces security policies. Do, Study, Act.
Product Manager
The merge gate. Triages issues and PRs, merges fix/bug/spec PRs, runs evaluations. The sole external merge point. Do, 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) intodesign.md(WHICH/WHERE) thenplan-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.mddocuments on pushed spec branches. A local commit is not a PR — the URL is the only valid completion signal.fix/andspec/branches never mix.
The Trust Boundary
The Product Manager is the sole external merge point. All other merge paths operate on trusted sources (our agents, Dependabot).
| 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;
forward-impact-ci PRs are trusted by identity. A
compromised top contributor cannot inject code via this pipeline —
specs merge only the document, not code.
The Workflows
Seven scheduled workflows run on a three-shift Europe/Paris rhythm — night by 07:00, storyboard at 08:00, day by 15:00, swing by 23:00 — plus an event-driven agent-conversation workflow on PR and discussion activity.
| Workflow | Schedule (Paris, CEST) | Agent |
|---|---|---|
| kata-storyboard | Daily 08:00 | improvement-coach (facilitates 5 agents) |
| kata-coaching | workflow_dispatch |
improvement-coach (facilitates 1 agent) |
| agent-product-manager | Night 03:23 · Day 12:17 · Swing 20:17 | product-manager |
| agent-staff-engineer | Night 04:11 · Day 13:11 · Swing 21:11 | staff-engineer |
| agent-security-engineer | Night 04:53 | security-engineer |
| agent-technical-writer | Night 05:37 | technical-writer |
| agent-release-engineer | Night 06:23 · Day 14:23 · Swing 22:23 | release-engineer |
| agent-conversation | On PR/discussion activity | product-manager (facilitates 4 agents) |
Each shift forms a producer → reviewer → shipper chain: the product manager triages and merges so staff has a fresh backlog, staff implements, release ships. The night shift slots security-engineer and technical-writer between staff and release.
Coordination Channels
Five channels carry agent-to-agent and agent-to-human collaboration, distinguished by time horizon and persistence.
| Channel | Use for | Lifetime |
|---|---|---|
| Wiki | Permanent curated memory: summaries, weekly logs, decisions | Persistent |
| Storyboard | Daily current condition and next experiment | One day; captured into wiki |
| Discussion | Open questions before they become decisions — RFCs, cross-policy | Until resolved into spec / wiki |
| PR / issue thread | Real-time response on a specific artifact | Lives with the artifact |
| Sub-agent | Specialized inline work within one run | Ephemeral (one task) |
Per-output coordination is governed by coordination-protocol.md; shared memory mechanics by memory-protocol.md.
Metrics
Agents record time-series data to
wiki/metrics/{agent}/{domain}/{YYYY}.csv after each
run. The kata-metrics skill defines the CSV schema (six
fields: date, metric, value, unit, run, note), storage convention,
and metric design. 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
forward-impact-kata, 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 (agent-conversation) |
| 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 |
Further Reading
- KATA.md — Canonical reference, read by every agent at the start of every run.
- Kata Brand — Brand implementation: palette, typography, motifs, and design tokens.
- Kata Scenes — Production-floor scenes: storyboard, gemba walk, Ohno circle, andon cord, merge gate, drafting bench, shipping bay, archivist's desk, trace tape.
- Kata Icons — Six agent icons and the suite mark.
-
CHECKLISTS.md
— How
<read_do_checklist>and<do_confirm_checklist>work. - CONTRIBUTING.md — Universal READ-DO and DO-CONFIRM checklists every Kata run runs.
"Without standards, there can be no kaizen."
— Taiichi Ohno