Skip to main content

Directory structure and composition rules

About the point in time this series describes

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 shows how the 5 facets (takt-derived) + orchestrator (takt-inspired) covered so far are actually laid out on disk.

Three things are covered:

  • The overall shape of the post-rebuild directory layout (what was retired, what was newly introduced, and what keeps growing usage-driven)
  • The criticality-based 3-tier delivery rule for composition
  • Two design decisions that prevent context loss along the subagent path (no path-scoping + absolute-path injection)

4.1. The directory layout, overall​

ls-ing ~/.claude/ shows a layout roughly like this (the contents of rules/skills/hooks/output-contracts/knowledge grow and shrink usage-driven, so only representative examples are listed below):

~/.claude/
├── CLAUDE.md           # philosophy and index only
├── rules/              # Policy: verification.md / fact-check.md / git.md / interaction.md, etc.
├── skills/             # Instruction: autodev/SKILL.md / spec-design/SKILL.md / harness-prune/SKILL.md, etc.
├── agents/             # Persona
│   ├── architect.md
│   ├── auditor.md
│   ├── developer.md
│   ├── devil-advocate.md
│   └── plan-reviewer.md
├── hooks/              # Computational Sensor: check-git-commit-gate.sh / check-plain-question.sh, etc.
│   └── tests/          # hook test scripts
├── output-contracts/   # Output Contract (new): plan.md / review.md / done.md, etc.
├── knowledge/          # shared Knowledge (grows usage-driven)
├── repos/              # per-repo Knowledge (generated by project-init)
│   └── <repo>/
│       ├── .repo_root
│       ├── CLAUDE.md
│       ├── CONTEXT.md
│       ├── INDEX.md
│       ├── mcp.json
│       ├── specs/
│       ├── adr/
│       ├── knowledge/
│       └── handoff/
├── learnings/          # /learn output (per-domain categories)
├── plans/              # plan files (cold-start prompts)
├── projects/           # auto-memory (per-project memory store)
└── settings.json

Four directories were removed: commands/ / references/ / teams/ / scripts/. Reasons:

Removed dirPre-rebuild useWhy / where it went
commands/Custom slash commandsTrigger words now live in skills/; the dir was not independently useful
references/Anthropic doc excerpts / pricing / industry articlesReplaced by on-demand fetch (WebSearch / MCP); stale local copies can't keep up
teams/Shared team personasOnly one file existed; Persona was consolidated into agents/
scripts/Monthly health-check / metrics aggregationConsolidated into /harness-prune skill

4.2. Evolution of the structure (what was retired, what was newly introduced, what keeps growing)​

As covered in Chapter 1, the zero-rebuild wasn't a one-time "compress and done" act — it has to be evaluated together with the usage-driven additions that followed. Here are the changes, organized by directory, into three highlights.

Change 1: norm bodies consolidated (rules / agents) → re-expanded via usage-driven additions

Before the rebuild, rules/ often mixed norms, concrete examples, and procedures together, and the same norms (verification / fact-check / git / interaction, etc.) were duplicated. At bootstrap, everything was cut down hard into a one-file-one-concern shape, and afterward, following the discipline of faceting only when the pattern "I gave the same correction by hand twice" surfaced during actual operation (Chapter 7), it grew back little by little. agents/ similarly was narrowed down in the zero-rebuild, and later grew with the addition of devil-advocate for pre-presentation critique on the main-agent path.

Change 2: deterministic enforcement (hooks)

Before the rebuild there were almost no hooks; norms relied solely on rules (Inferential Guides). The new harness shifted policy — out of the norms written as Inferential Guides, the ones that truly can't be compromised on get stopped deterministically by a Computational Sensor instead — and grew hooks ahead of the other facets. Examples of hooks introduced:

  • check-git-commit-gate.sh (commit-discipline enforcement)
  • check-plain-question.sh (plain-question prohibition enforcement)
  • check-action-completion.sh (detect completion claims without verification)
  • check-pre-edit-search.sh (detects missing pre-edit Read before Edit / Write / MultiEdit; a log-only Computational Sensor)

All of these are predicated on a corresponding Policy facet existing under rules/ (orphan hooks are forbidden). The exception is infrastructure-leaning hooks like say-notify.sh, used for notification and with no direct Policy-facet counterpart. check-pre-edit-search.sh is an example of a usage-driven addition after bootstrap — introduced at the same time as rules/search-before-coding.md was added (an application of the "hooks come after evidence" discipline's exception clause — bootstrap-concurrent allowance — covered in Chapter 7).

Change 3: the Output Contract layer is new

output-contracts/ is nrslib/takt's official facet (corresponding to the output_contracts: field each step carries in takt's workflow YAML), factored out as its own directory in this rebuild. It did not exist pre-rebuild, when subagent output formats were written ad-hoc in each agent body. The new harness independently templatizes:

  • spec.md (spec-design output)
  • plan.md (architect output)
  • story.md (developer's single input merged from spec + plan by the orchestrator)
  • done.md (developer execution evidence)
  • review.md (plan-reviewer / auditor VERDICT)

Each agent body only needs to carry a reference like "the VERDICT contract" or "the first-line convention"; the template bodies can evolve independently of the agent bodies.

4.3. Composition rule: 3-tier criticality delivery​

Even with the directory in shape, how they reach Claude (the composition strategy) is a separate problem. Claude Code lacks a composer (assembler), so "Read everything to compose" probabilistically silent-drops (Chapter 1 symptom 4).

The new harness splits delivery into 3 tiers by criticality:

Each tier:

Tier 1: gating facet → inline + hooks​

Norms that determine the loop verdict (gating facets, corresponding to takt principles 1 "Agents Are Powerful, but Not Authoritative" and 2 "Structure Over Prompting") get their body inlined into the agent body. The Read path is probabilistic; norms that can't afford probabilistic failure go in the agent body.

Example: the output-contract section of agents/plan-reviewer.md:

## Output contract (output-contracts/review.md)
- Write review.md into the handoff dir (first line VERDICT + primary signal + findings)
- The **first line of the final utterance** must also be `VERDICT: PASS|FAIL`,
  followed by a 1-3 line summary and the review.md handoff path
- **First line of the utterance is `VERDICT: PASS|FAIL`** (review.md first line
  too). After emitting VERDICT, terminate without further commentary
  (VERDICT presence is confirmed by the orchestrator on review.md)

"Always emit VERDICT: PASS|FAIL as the first line of the final utterance" is the gating contract that makes the autodev flow's fail-closed branching (grep '^VERDICT:') possible. The loop can't advance if it drops.

In addition, the Stop-sensor hook check-action-completion.sh warns when "completed" is claimed without a verification command. This Inferential Guide + Computational Sensor pair enforces the norm.

Tier 2: Instruction → composed/embedded into story.md / the spawn prompt​

Procedures (Instructions, = SKILL.md) are loaded by the main agent (= the orchestrator) itself, which then runs the procedure directly — but there's no path that hands the body itself to a subagent. The orchestrator instead composes/embeds the procedure and acceptance criteria a subagent needs into story.md (or the spawn prompt).

In the autodev flow, when the orchestrator spawns a developer subagent, it injects into the spawn prompt the path to a story.md composed from spec + plan, plus absolute paths for per-repo knowledge. The body of agents/developer.md itself carries only Persona and constraints; the concrete procedure is embedded in story.md.

---
name: developer
description: Implement inside the worktree with story.md as the sole input,
             run pass conditions, record evidence.
model: inherit
tools: Read, Write, Edit, Bash
---
You are a spec-faithful implementer. story.md is your sole primary input;
implement inside the worktree (branched from HEAD).

The body of agents/developer.md carries only Persona and constraints; concrete procedures arrive as story.md (the orchestrator's derived artifact merging plan.md + spec.md). This keeps agents/developer.md under 30 lines, and procedure evolution happens independently in story.md / SKILL.md.

Tier 3: Knowledge / descriptive Policy → index + on-demand Read​

Descriptive Knowledge and Policy that comes up probabilistically at runtime is delivered via reference from an index (CLAUDE.md / INDEX.md) + Read on demand.

Body-copy is forbidden here (the silent-drop avoidance via body-copy is permitted only at tier 1). Knowledge bodies live in exactly one file, and other places only reference them.

For per-repo knowledge, ~/.claude/repos/<repo>/INDEX.md plays the index role. INDEX.md is a 1-line-per-file index with use-case hooks; the orchestrator reads it during /autodev ⓪' and Reads only the task-relevant files on demand (see Chapter 3 on how this maps to takt's official concepts).

4.4. Two principles to prevent subagent context loss​

In addition to the composition rule, two principles guarantee that norms reach subagents.

Principle 1: Policies that subagents depend on must not be path-scoped​

Writing paths: in a rules/*.md frontmatter scopes the rule to a path. That's handy on the main agent but doesn't reach subagents.

Subagents launch via their own system-prompt path and don't have a route to load the main agent's path-scoped rules. If a Policy needed by developer / auditor in the autodev flow doesn't reach them, implementation discipline and audit discipline inside the worktree break.

In the new harness, Policies that subagents must reach are constantly loaded (no paths:). For example:

  • rules/verification.md (evidence discipline, depended on by developer / auditor)
  • rules/git.md (commit discipline, depended on by developer)
  • rules/fact-check.md (pre-statement source-checking, depended on by all agents)
  • rules/interaction.md (AskUserQuestion discipline, depended on by main agent)
  • rules/search-before-coding.md (symbol grounding, depended on by developer / architect)
  • rules/handoff-discipline.md (cross-session discipline, depended on by orchestrator / developer / auditor)

rules/ keeps growing usage-driven from here, but the principle itself — Policies that subagents depend on are, without exception, constantly loaded with no paths: — doesn't change. It's operational hygiene to make Policy only what is truly needed everywhere; domain-specific items (e.g. Terraform / Docker) live elsewhere (knowledge referenced on demand from the CLAUDE.md index).

@import is not expanded inside agent bodies

Using @import in rules/*.md frontmatter might look like "you can pull in other rules," but Claude Code's current spec does not expand @import in agent bodies. That is another typical subagent-context-loss pitfall, and this harness avoids @import (it loads whole files only).

Principle 2: per-repo knowledge is injected explicitly by absolute path​

~/.claude/repos/<repo>/CLAUDE.md and CONTEXT.md sit outside the main agent's workspace (under ~/.claude/), so subagent path-scoped auto-loading can't reach them.

Example: phase ① architect spawn in the autodev flow:

## ① architect spawn (read-only, fresh)
Inject into the spawn prompt: spec.md + **per-repo knowledge by absolute path**
(`~/.claude/repos/<repo>/CLAUDE.md` policy / `CONTEXT.md` glossary / selected
knowledge — these don't reach across the worktree, and being **pointer-layer =
outside the worktree, are not developer commit targets**) → architect produces
plan.md

The orchestrator injects absolute paths (/Users/<name>/.claude/repos/<repo>/...). ~ expansion may not work in the subagent's context, so fully-expanded absolutes are used.

With this:

  • architect can reference spec + per-repo CLAUDE.md (per-repo Policy) + CONTEXT.md (glossary) while generating plan.md
  • developer takes story.md (the orchestrator's embedded derived artifact) as its single input — per-repo knowledge is already inline (SELECTIVE extraction)
  • auditor receives per-repo knowledge absolute paths re-injected into the spawn prompt

With these two principles, norms reach subagents structurally even as new subagent kinds are added.

4.5. The role of CLAUDE.md (index + philosophy)​

A note on why CLAUDE.md, which was long before the rebuild, has stayed short after it.

The new CLAUDE.md only contains:

# CLAUDE.md — faceted harness (takt / Faceted Prompting philosophy)

## Who we're talking to                                  (Persona overview)
## How we ask (source of truth: rules/interaction.md)     (AskUserQuestion discipline)
## How we present (source of truth: rules/adversarial-review.md) (devil-advocate invocation norm)
## Harness structure (Faceted Prompting = 5-concern separation) (the 5-facet table + the role of hooks)
## Composition rule (splitting delivery method by criticality) (3-tier criticality delivery)
## Growth discipline (structural prevention of re-bloat) (the 5-discipline table)
## Autonomous dev flow                                    (one-line entry to /spec-design + /autodev)

Only philosophy and index are written here; no concrete norms or procedures.

  • Norms refer to rules/<name>.md
  • Procedures refer to skills/<name>/SKILL.md
  • Output contracts refer to output-contracts/<name>.md
  • Knowledge refers to knowledge/<name>.md or repos/<repo>/...

With that, CLAUDE.md serves as a panoramic index and each facet body evolves independently. Pre-rebuild, main norms lived directly in CLAUDE.md, which caused CLAUDE.md itself to swell with every revision (a feedback loop).

Index vs body, separated

Confining CLAUDE.md to "index + philosophy" greatly improved revision speed. To add a new norm:

  1. Classify it into a facet (5 + 1 hooks)
  2. Edit the facet body (rules/<name>.md etc.)
  3. Don't touch CLAUDE.md (it's an index, and subagents reach the new rule automatically)

That makes revision cost O(1) (one place — the body).

4.6. Summary of this chapter​

Key points
  • The whole harness is organized into 5 facets (rules/ skills/ agents/ output-contracts/ knowledge/) plus hooks. After the zero-rebuild compressed things down hard, it kept growing under usage-driven addition while staying disciplined; output-contracts/ adopts takt's official facet
  • The 4 removed directories (commands / references / teams / scripts) were absorbed into skills or replaced by on-demand fetch
  • The composition rule is 3-tier criticality: gating inline / Instruction composed into story.md or the spawn prompt / Knowledge from index + on-demand
  • Two principles prevent subagent context loss: no path-scoping (always loaded) and absolute-path explicit injection (per-repo knowledge)
  • CLAUDE.md is kept short, restricted to "index + philosophy"; revisions complete on the facet body

The next chapter walks through each of the 5 facets + hooks + knowledge, with real-code excerpts, as a dictionary of responsibilities and boundaries — the role and representative examples of each of rules/ skills/ agents/ hooks/ output-contracts/ knowledge/.