Adopting takt's philosophy: porting nrslib/takt to Claude Code
This series is a record based on the harness environment as it existed at the time of writing (file contents, run logs, file counts). The harness has kept evolving since this series was written, so quoted file contents, counts, and procedures may differ from the current state. The focus of this series is the design ideas (five-facet separation, verification gates, growth discipline) rather than the specific values.
This chapter covers the other core of this series — adopting takt's philosophy.
"takt" refers to nrslib/takt, an AI Agent Orchestration Framework (CLI tool, MIT License, by nrslib). This harness does not use the takt CLI. Instead, it adopts takt's design philosophy — Faceted Prompting / Output Contracts / Worktree Isolation / 8 design principles — and ports that philosophy onto Claude Code's own primitives (skills/ + agents/ + ~/.claude/repos/<repo>/handoff/ + hooks/).
The chapter first introduces takt itself (3.1-3.3), then maps how this harness re-implements those ideas on Claude Code (3.4-3.6) with a side-by-side correspondence table.
3.1. What is takt?
nrslib/takt is an OSS CLI that turns AI coding agents into "structured, repeatable development workflows."
| Field | Value |
|---|---|
| Repository | github.com/nrslib/takt |
| Author | nrslib |
| License | MIT |
| Kind | AI Agent Orchestration Framework (CLI) |
| Providers | Claude Code / Claude SDK / Codex / OpenCode / Cursor / GitHub Copilot CLI / Kiro |
| Main commands | takt (queue a task) / takt run (execute) / takt list (manage results) |
Origin of the name
From the README verbatim:
"The name TAKT comes from the German word for 'beat' or 'baton stroke,' used in conducting to keep an orchestra in time."
So the name comes from the conductor's baton stroke keeping an orchestra in time. It has nothing to do with takt time as the manufacturing line term; the metaphor is conducting, not manufacturing.
The problem it solves
Summarizing the README: AI agents struggle with long-running work — they "forget instructions, accumulate polluted context, blur implementation and review responsibilities." takt addresses this by treating agents as externally controlled entities within a defined process, not autonomous decision-makers.
3.2. takt's 8 design principles
From takt design philosophy, only the principle names in the first column are quoted verbatim. The second column summarizes the intent in the author's own words (not verbatim — see the original doc for the full text). The third column shows this harness's mapping.
| # | takt principle | Mapping in this harness |
|---|---|---|
| 1 | Agents Are Powerful, but Not Authoritative — AI output is probabilistic; process structure, not plausibility, validates decisions | VERDICT: PASS|FAIL output contract + grep '^VERDICT:' for mechanical judgment. No reliance on LLM plausibility |
| 2 | Structure Over Prompting — Explicit workflow definitions and rules replace reliance on agent memory | skills/autodev/SKILL.md declares ⓪'-⑤ steps explicitly. No memory dependence |
| 3 | Separation Improves Quality — Distinct roles and knowledge domains prevent conflicts of interest | 4 subagents (architect / plan-reviewer / developer / auditor) + tool constraints enforce Generator-Evaluator separation structurally |
| 4 | Feedback Loops Are First-Class — Review, fix, and arbitration cycles have defined boundaries | Plan bounces up to 1 / impl bounces up to 2 / same error_signature twice = stagnation detection |
| 5 | Human Judgment Is an Escalation Path — Humans decide when uncertainty or permission gaps emerge | ② human approval / AskUserQuestion 3-way (approve / specify changes / abort) / human escalation on stagnation |
| 6 | Workflows Are Process Assets — Processes are stored as YAML and shared across teams | This harness is personal, so no YAML form; instead skills/*/SKILL.md is versioned (~/.claude/ is a git repo) as personal process assets |
| 7 | Traceability Matters — Records enable inspection and continuous improvement | spec / plan / story / done / review / state.md preserved in ~/.claude/repos/<repo>/handoff/<task>/ |
| 8 | Practical Automation Over Full Autonomy — Systems remain observable and interruptible | ② human approval always pauses / handoff dir survives mid-run for resume |
All 8 principles are faithfully followed. This harness is not a direct fork of takt OSS, but it fully aligns at the design-principle level by intent.
3.3. Five takt official concepts covered in this series
From the takt README and Faceted Prompting docs, here are the 5 official concepts this series covers (takt has additional concepts such as Step Types / Loop Monitors / Promotion / Subworkflow, but we focus on those needed for this harness's mapping).
(1) Workflow YAML
takt's core data structure. A sequence of steps (= phases) declaratively defined in YAML:
steps:
- name: analyze
persona: planner
edit: false
rules:
- condition: Analysis complete
next: implement
- name: implement
persona: coder
edit: true
pass_previous_response: true
rules:
- condition: Implementation complete
next: review
- name: review
persona: reviewer
edit: false
rules:
- condition: Approved
next: COMPLETE
Each step has persona / policy / knowledge / instruction / output_contracts / edit / rules. The rules.condition (tag / ai("...") / all("...") / any("...")) decides the transition to the next step. next is either another step name, COMPLETE, or ABORT.
(2) Faceted Prompting (5 facets)
The 5 concerns each step carries. Verbatim from the canonical docs:
| facet | what kind of (takt's definition) |
|---|---|
| Persona | Who makes the judgment? — Role definition, expertise |
| Policy | What to uphold? — Prohibitions, quality standards, priorities |
| Instruction | What to do? — Goals, step-specific procedures |
| Knowledge | What to reference? — Domain context, reference materials, API specs |
| Output Contract | How to output? — Output structure, report templates |
The design rationale, verbatim:
"Apply Separation of Concerns — a foundational software engineering principle — to prompt design. Instead of one monolithic prompt per agent, decompose it into independent, reusable files organized by what concern they address. Then compose them declaratively per workflow step."
This is the origin of the 5-concern separation covered in Chapter 2. This harness maps takt's 5 facets onto Claude Code's rules/ (Policy) / skills/*/SKILL.md (Instruction) / agents/*.md (Persona) / knowledge/ + repos/<repo>/ (Knowledge) / output-contracts/*.md (Output Contract).
(3) Output Contracts
Each step's artifact format, declared in the workflow YAML via output_contracts: (see docs/workflows.md §Output Contracts (Report Files) for the field reference). The README summarizes how output contracts fit into takt as a whole:
"TAKT enforces phase transitions declaratively as a YAML state machine, formalizes the artifact of each phase with output contracts, and routes deviations back via parallel review and fix loops." (source: README)
This harness factors them out as the independent output-contracts/*.md facet (spec / plan / story / done / review). Earlier drafts of this series called Output Contracts "newly introduced here" — that was wrong; they are takt's official concept.
(4) Worktree Isolation
"Tasks run in isolated worktrees, and each step leaves logs and reports so the path from task to PR remains traceable." (source: README "Why TAKT")
Each task runs in an isolated worktree, protecting the main branch. This harness replicates the same shape — in autodev SKILL ③, the developer creates its own git worktree add (see Chapter 6 §6.7).
takt's own task configuration still uses the term "worktree," but its actual implementation has moved from a real git worktree to git clone --shared (a lightweight clone with its own independent .git) (source: docs/task-management.md). This harness's developer / auditor flow, by contrast, literally runs git worktree add / git worktree remove. It's worth keeping in mind that the same word "worktree" refers to different implementations in takt itself versus this harness.
(5) Repertoire
"Repertoire packages let you install and share TAKT workflows and facets from GitHub repositories."
A package management system for installing reusable workflows / facets from GitHub, referenced via scoped syntax @owner/repo/facet-name.
This harness is personal-use, so it doesn't adopt Repertoire — facets live directly under ~/.claude/skills/. Moving to Repertoire form is a candidate for the future if team-sharing is required.
3.4. The independent port — no CLI, re-implemented on Claude Code
This harness does not use the takt CLI. Reasons:
- The harness is specialized to Claude Code (one LLM provider); takt's multi-provider orchestration isn't needed
- Claude Code's subagent / skill / hook primitives can re-implement takt's ideas
- Managing the personal
~/.claude/structure as a versioned (private git) repo is lighter than introducing workflow YAML + Repertoire
Instead, takt's philosophy is mapped onto Claude Code primitives:
| takt mechanism | This harness's substitute |
|---|---|
~/.takt/workflows/*.yaml | ~/.claude/skills/autodev/SKILL.md (the orchestrator executes ⓪'-⑤ as a procedure) |
step (name / persona / rules) | subagent spawn (architect / plan-reviewer / developer / auditor) |
rules: condition for transitions | VERDICT: PASS|FAIL output contract + main agent's grep '^VERDICT:' branch |
output_contracts: field | output-contracts/*.md (5 files: spec / plan / story / done / review) |
edit: true/false permission | tool constraints in agents/<name>.md frontmatter (architect / plan-reviewer / auditor have Write restricted to handoff dir only) |
| Worktree Isolation | orchestrator manually git worktree add /tmp/<repo>-<task> in autodev SKILL ③; worktree_path pinned in state.md |
quality_gates: type: command | developer subagent runs pass conditions inside the worktree and records evidence in done.md |
Repertoire (@owner/repo/...) | Not adopted (personal use, ~/.claude/skills/ direct) |
pass_previous_response: true | orchestrator composes handoff derivatives (plan.md → story.md) and passes to the next subagent |
~/.takt/personas/ | ~/.claude/agents/*.md body (system prompt) |
The full autodev flow (recap):
The annotations persona= / edit= next to each node align with takt's workflow YAML vocabulary. This harness expresses the same constraints via agents/<name>.md frontmatter rather than YAML.
3.5. takt official ⇔ this harness (detailed map)
Per-concept correspondence table.
Faceted Prompting (5 facets)
| takt facet | Location in this harness | Size cap | Delivery |
|---|---|---|---|
| Persona | agents/*.md body + top of CLAUDE.md | ≤40 (gating ≤60) | inline in agent body |
| Policy | rules/*.md | ≤30 | always loaded (no paths:) |
| Instruction | skills/*/SKILL.md | ≤80 (autodev ≤100) | trigger word loads it into the main agent; reaches subagents via composition/embedding into story.md / the spawn prompt |
| Knowledge | knowledge/*.md + ~/.claude/repos/<repo>/ | (no cap, managed per file) | index + on-demand Read |
| Output Contract | output-contracts/*.md | ≤30 | named in the agent body's ## Output Contract section; the subagent reads it itself |
Workflow (plan → implement → review)
| takt YAML | autodev step (⓪'-⑤) in this harness | Owner subagent |
|---|---|---|
persona: planner / edit: false | ① architect spawn | agents/architect.md |
persona: reviewer / edit: falserules: Approved → next | ①' plan-reviewer spawn | agents/plan-reviewer.md |
| (no human-approval step in takt) | ② human approval (AskUserQuestion 3-way) | main agent |
persona: coder / edit: truepass_previous_response: true | ③ developer spawn (in worktree) | agents/developer.md |
persona: reviewer / edit: falserequired_permission_mode: readonly | ④ auditor spawn (read-only fresh --bare) | agents/auditor.md |
rules: Approved → COMPLETE | ⑤ ff merge + cleanup | main agent |
Output Contracts
| takt concept | Implementation in this harness (output-contracts/*.md) |
|---|---|
| Each step's report file format | spec.md (acceptance / SHA freeze) / plan.md (impl plan + column-form doc obligations) / story.md (developer's sole input) / done.md (execution evidence) / review.md (first line VERDICT: PASS|FAIL) |
Worktree Isolation + related step settings
| takt behavior / setting | Implementation in this harness |
|---|---|
| Each task runs in an isolated worktree | orchestrator manually git worktree add /tmp/<repo>-<task>; agents/developer.md deliberately omits isolation: worktree (to avoid doubled worktrees — see Chapter 8 Iteration 3) |
allow_git_commit: false (default; step setting) | This harness instead lets developer commit, defended by hooks/check-git-commit-gate.sh against runaway commits (Chapter 8 Iteration 1) |
3.6. What is unique to this harness (not in takt itself)
This harness layers some disciplines on top of takt's philosophy. These are this harness's own integration, not in takt itself.
| Unique part | Content | Chapter |
|---|---|---|
| 5 disciplines | usage-driven add / size cap / one-file-one-concern / reverse ratchet / hooks-after-evidence | Chapter 7 |
| Reverse ratchet and inverted approval | Monthly /harness-prune detects 30-day-zero-references etc. with inverted approval (ask why to keep) | Chapter 7 |
| Computational Sensors (hooks) | takt enforces workflow via CLI; this harness uses Claude Code's PreToolUse / Stop / PostToolUse hooks to deterministically enforce individual norms (commit gate / plain-question detection / pre-edit read check, etc.) | Chapter 5's hooks section |
| Understanding gates (smi-auto-dev) | autodev's quality gates layered with G1/G2/G3 understanding gates (learning-friendly flow) | ~/.claude/skills/smi-auto-dev/SKILL.md |
| Per-repo zero-footprint scaffold | /project-init skill places the personal layer in ~/.claude/repos/<repo>/ without touching the team repo at all | ~/.claude/skills/project-init/SKILL.md |
| Subagent norm-delivery design | No paths: (always loaded) + absolute-path explicit injection (specific to Claude Code's context-loss workaround) | Chapter 4 §4.4 |
3.7. Sources and license
Primary sources from nrslib/takt referenced in this series:
- nrslib/takt GitHub (MIT License)
- README (origin / problem / CLI usage)
- Faceted Prompting (canonical definition of the 5 facets)
- Design Philosophy (8 design principles)
- Workflows (YAML schema)
- Builtin Catalog (built-in workflows / personas)
- Repertoire (reusable packages)
This harness respects nrslib/takt's MIT License and adopts its philosophy (5 facets / 8 design principles / Workflow Output Contracts / Worktree Isolation). There is no code-level dependency; what we have is an independent port to Claude Code (skills + agents + handoff dir + hooks).
3.8. Summary of this chapter
- takt = nrslib's AI Agent Orchestration Framework (CLI, MIT). The name comes from the conductor's "baton stroke" (no relation to the manufacturing line term takt time)
- 8 design principles (Not Authoritative / Structure Over Prompting / Separation Improves Quality / Feedback Loops / Human Judgment Escalation / Process Assets / Traceability / Practical Automation) are fully followed at principle level
- Of the 5 official concepts covered in this series (Workflow YAML / Faceted Prompting / Output Contracts / Worktree Isolation / Repertoire), this harness adopts the philosophy only — without using YAML or Repertoire — and re-implements it on Claude Code
- The correspondence table maps takt → this harness (Faceted Prompting → 5 facet directories / Workflow step → subagent spawn / Output Contracts → output-contracts/ / Worktree Isolation → autodev SKILL ③)
- Unique parts (5 disciplines / reverse ratchet / Computational Sensors / understanding gates etc.) are clearly marked as the author's integration not present in takt itself
The next chapter shows how the 5 facets + orchestrator (takt-inspired) are actually laid out on disk — the overall shape of the directory layout and the criticality-driven 3-tier composition rule.