Synapse Agent Architecture — The {domain}-director Pattern

This article is a senior-engineer-level disclosure of Synapse’s responsible-agent architecture. The structure — placing {domain}-director pattern agents as domain leads, extracting skills into .claude/skills/, and delegating work through skill invocation — is presented here in full, including the actual .claude/agents/ definition files that Yakumo runs in production.

If you are looking for a way to design a cross-functional agent organization, this article serves as a working implementation reference. We extract the blog-operations slice of Synapse (Yakumo’s cross-functional agent organization built on Claude Code) and disclose the design of @blog-director / @editor-in-chief / @seo-director, along with the implementation patterns of the /blog-* skill suite they invoke.

The business perspective — why Synapse was built and how an AI agent organization integrates into business operations — is covered in How to Launch an AI Agent Organization. This article focuses on the engineering implementation details.

Synapse’s Overall Architecture — Designing a Cross-Functional Agent Organization

Directory Structure of .claude/agents/ and .claude/skills/

Claude Code follows the convention of placing agent definitions and skill definitions under .claude/ at the project root. Yakumo’s Synapse uses this structure as follows:

.claude/
├── README.md              # Overall guide for the agent organization
├── agents/                # Responsible agent definitions (Tier 1)
│   ├── blog-director.md
│   ├── editor-in-chief.md
│   └── seo-director.md
└── skills/                # Deterministic skills (7 of the 15 total, covering core blog operations)
    ├── README.md
    ├── blog-audit/
    │   └── SKILL.md
    ├── blog-classify/
    │   └── SKILL.md
    ├── blog-tech-write/
    │   └── SKILL.md
    ├── blog-review/
    │   └── SKILL.md
    ├── blog-meta/
    │   └── SKILL.md
    ├── blog-translate/
    │   └── SKILL.md
    └── blog-publish/
        └── SKILL.md

Agent definitions are Markdown files whose frontmatter carries name / description / model / tools. Skills are written as procedure documents (shell scripts + prompts) in SKILL.md.

Responsible Agents by Domain

The blog-operations portion of Synapse is composed of three responsible agents (Tier 1):

The core of the design is not creating “task agents” but instead establishing “responsible agents.” The latter makes the locus of decision-making explicit; the former produces a state where someone is assigned but accountability is vague.

Agent Delegation Flow

Synapse’s delegation flow operates in two layers:

User (main-thread)
  │
  ├── Consults @blog-director
  │     → Returns execution plan to main-thread
  │
  ├── main-thread reads the plan and directly launches /blog-* skills
  │
  └── Skills make internal LLM calls (absorbing decision chains)

@blog-director is an advisor, not an executor. It returns the execution plan to main-thread; the actual skill invocations are performed by main-thread.

The {domain}-director Pattern — Defining Responsible Agents

The Concept of the {domain}-director Pattern

The {domain}-director pattern is a design in which a “responsible agent for that area” is established as {domain}-director.md for each business domain. Examples: blog-director.md / sales-director.md / dev-director.md / seo-director.md / editor-in-chief.md.

The {domain}-director pattern defines agents along three dimensions: domain of responsibility × authority × delegation target.

The philosophy is “establishing a responsible agent” rather than “creating a task agent.” The former makes the locus of decision accountability clear; the latter produces assignment without clear ownership.

Implementing this pattern on Claude Code means each agent’s Markdown file contains the following:

• Domain section: An enumeration of matters the agent can decide on its own
• Delegation section: Which agent receives matters outside its authority
• Reference documents section: A list of configuration files that serve as the basis for decisions

Structure of a Responsible Agent Definition File

Looking at the actual @blog-director definition file structure reveals the pattern’s implementation:

---
name: blog-director
description: Responsible party for the entire blog business. Determines cross-cutting
             decisions, track assignments, and priorities, then returns guidance to
             @seo-director / @editor-in-chief as an advisor.
model: claude-sonnet-4-6
tools: Read, Glob, Grep, Bash
---

> **[Claude Code runtime constraint]**
>
> A sub-agent cannot spawn further sub-agents or skills.
> Therefore blog-director acts strictly as an advisor that constructs an execution plan
> and returns it to main-thread.
> Actual skill / agent invocations are performed by main-thread.

# Blog Business Responsible Agent (Blog Director)

## Domain
- **Track strategy**: Balance and prioritization between tech and case volumes
- **Audience classification**: Determining which track to assign new and existing articles to

## Delegation
- **SEO and traffic perspective** → `@seo-director`
- **Editorial policy, tone, detailed audience classification** → `@editor-in-chief`

It carries model: claude-sonnet-4-6 and tools: Read, Glob, Grep, Bash. Even if Agent or Skill were added to tools, they would not be injected by the Claude Code runtime — this is the rationale for the “absorb decision chains inside skills” design detailed in the next section.

@editor-in-chief shares the same structure:

---
name: editor-in-chief
description: Editor-in-chief overseeing editorial policy, audience classification, tone,
             and handling of proper nouns. Owner of the rewrite-tech / rewrite-case pipelines.
model: claude-sonnet-4-6
tools: Read, Glob, Grep, Bash
---

## Domain

### Editorial policy layer
- **Audience classification**: Rigorously determining whether an article is written for tech or case readers
- **Tone governance**: Ensuring compliance with the voice and prohibited expressions in `src/_docs/BRAND.md`
- **Proper noun handling**: Managing the level of detail in introductions of Synapse / montage / medallion
- **Pipeline management**: Constructing invocation instructions for each stage of rewrite-tech / rewrite-case

@seo-director owns the specialized SEO domain and is responsible for keyword strategy and cannibalization (same-keyword competition) avoidance:

---
name: seo-director
description: Responsible party for SEO, keyword strategy, title/description optimization,
             and traffic perspective. Returns /blog-meta invocation instructions to main-thread
             as an advisor.
model: claude-sonnet-4-6
tools: Read, Glob, Grep, Bash
---

## Domain (excerpt)
- Maintaining the cluster SEO map: keeping the correspondence between pillar primary_keywords
  and spoke secondary_keywords within each cluster, and preventing intra-cluster cannibalization

All three agents share the behavior spec “act strictly as advisors,” which is declared at the top of each agent definition file under [Claude Code runtime constraint].

Declaring the Harness and Invocation Conventions in CLAUDE.md

The rules for using the agents and skills under .claude/ are declared in CLAUDE.md. Yakumo’s CLAUDE.md contains the following conventions:

## Invariant Rules

- **Implementation delegation**: Code, config, skill/agent definitions, and structured YAML edits
  are delegated in principle to `web-developer` / `system-developer` / the relevant director agent.
  Main-thread handles requirement clarification, instruction drafting, diff review, and commits.
- **Blog operations**: Any business work involving articles must go through a responsible agent
  (`@blog-director` / `@seo-director` / `@editor-in-chief`).

By writing invocation conventions in CLAUDE.md, the agent launch flow remains consistent as long as Claude Code holds the conversation context.

Skill Delegation — Designing .claude/skills/

Why Skills Are Necessary in Claude Code — Handling the Sub-Agent Constraint

There is one important design decision in the {domain}-director pattern. In Claude Code, a sub-agent (an agent launched via the Agent tool) cannot spawn further sub-agents or skills — a runtime constraint.

What this constraint implies:

• Launch @editor-in-chief from @blog-director → cannot call /blog-tech-write from within @editor-in-chief
• A three-level call chain — “agent calls another agent which calls a skill” — does not work

Synapse’s chosen response to this constraint is the design of “absorbing decision chains inside skills.”

❌ Structure that does not work:
main-thread → @blog-director → @editor-in-chief → /blog-tech-write

✅ Structure that works:
main-thread → @blog-director (returns execution plan)
main-thread → /blog-tech-write (invoked directly)
               ↓
         Internal LLM call inside the skill (handles decisions and writing)

A skill is a “deterministic procedure document,” and the LLM is called from within that document. This allows decision logic that would otherwise require chained agent calls to be encapsulated inside the skill.

Decision Criteria for Distributing Responsibilities Between Skills and Agents

Given this constraint, the criteria for “what to place in agents vs. what to place in skills” become clear:

What @blog-director handles:
  "This article is tech track → hand to @editor-in-chief
   → please launch /blog-classify from phase 1 of the rewrite-tech pipeline"

What /blog-tech-write handles:
  "Read the brief, consult audience-tracks.json,
   generate body text using an LLM within BRAND.md constraints,
   and write it to draft_v{n}.md"

Designing the Skill I/O Contract

Every skill must have a three-element I/O contract:

I/O contract for /blog-tech-write:

Input:
  - slug (argument)
  - blog-ops/articles/{slug}.yaml (brief)
  - src/_docs/BRAND.md (voice and prohibited expressions)
  - src/config/brand.ts (prohibited terms)
  - blog-ops/config/audience-tracks.json (tech structure)

Output:
  - blog-ops/output/rewrite/{slug}/draft_v{n}.md (body Markdown)

Precondition:
  - Brief YAML must exist
  - cluster: tech must be explicitly set

Declaring the I/O contract in SKILL.md keeps it aligned with the pipeline DAG (blog-ops/config/pipelines/new-article-pillar.json).

Choosing Between Deterministic Skills and Judgment Agents

Another decision point is whether to use a “deterministic skill” or a “judgment agent”:

Even judgment agents ultimately output “instruction text for main-thread.” Generating actual artifacts (files) is the skill’s job.

Full Disclosure of Implementation — Representative {domain}-directors in Synapse

@blog-director Definition and Delegated Skills

@blog-director operates in two modes as the responsible party for the entire blog business:

Audit mode (@blog-director audit):

## Behavior during audits (`@blog-director audit`)

1. Read blog-ops/config/pipelines/audit.json and construct the execution plan
2. Return the following instructions to main-thread:
   [phase 1] Run /blog-audit
   [phase 2] Read the result and re-invoke blog-director
3. Upon receiving the result, select the top 5 rewrite candidates and
   return instructions to output them to blog-ops/output/audit/plan_{date}.md

Rewrite assignment mode (@blog-director rewrite <slug>):

## Rewrite assignment (`@blog-director rewrite <slug>`)

1. Read the target article
2. Determine tech / case / split-recommended based on the decision flow in
   blog-ops/specs/audience-tracks.md
3. Return one of the following to main-thread:
   - tech assignment → return instruction to invoke `@editor-in-chief rewrite-tech <slug>`
   - case assignment → return instruction to invoke `@editor-in-chief rewrite-case <slug>`
   - split recommended → request user confirmation

@blog-director can only return instruction text. Actual invocations of /blog-audit and @editor-in-chief are entirely main-thread’s responsibility. This is the honest implementation of the runtime constraint.

@editor-in-chief Definition and Delegated Skills

As the owner of the tech-rewrite pipeline, @editor-in-chief returns a six-phase execution plan to main-thread:

## Behavior during tech rewrites (`@editor-in-chief rewrite-tech <slug>`)

1. Read blog-ops/config/pipelines/rewrite-tech.json and confirm the DAG
2. Read src/content/magazine/{track}/{category}/{slug}.md to understand the current article
3. Confirm the tech track structure in blog-ops/specs/audience-tracks.md
4. Confirm the tech-track tone requirements in src/_docs/BRAND.md
5. Return the following invocation instructions to main-thread in order:
   [phase 1] /blog-classify {slug}
   [phase 2] /blog-pattern {slug}
   [phase 3] /blog-tech-write {slug}
   [phase 4] /blog-review {slug} track=tech
             → proceed only if pass. Fail triggers a request for user confirmation.
   [phase 5] /blog-meta {slug} track=tech
   [phase 6] /blog-publish {slug} (after final user confirmation)

The notable detail is → proceed only if pass in phase 4. @editor-in-chief explicitly declares where in the pipeline it “returns a decision to the human.” Non-stop automated execution is prohibited — the design principle is to return decision authority to main-thread at each judgment checkpoint.

The declaration of reference documents is also important:

## Reference configuration

All editorial decisions must reference the following before proceeding. Do not hardcode.

| Document | When to reference |
|---|---|
| `blog-ops/specs/audience-tracks.md` | Audience classification flow, structure, evaluation criteria |
| `src/_docs/BRAND.md` | Tone, prohibited expressions, recommended expressions, product introduction conventions |
| `src/config/brand.ts` | Proper noun enums and prohibited term lists (machine-readable) |
| `blog-ops/config/audience-tracks.json` | Machine-readable version of track definitions |

Declaring inside the agent definition that “judgments must always reference files — never hardcode” maintains SSOT (Single Source of Truth) alignment.

@seo-director Definition and Delegated Skills

@seo-director owns the specialized SEO domain and returns /blog-meta invocation instructions:

## Behavior during meta optimization (`@seo-director meta <slug>`)

1. Read src/content/magazine/{cluster}/{category}/{slug}.md to review the current frontmatter and body
2. Check category and tag count limits in blog-ops/config/sites/corporate.json
3. Understand keyword trends corresponding to the article's track in blog-ops/config/audience-tracks.json
4. Return the following to main-thread:
   Please invoke /blog-meta with these parameters:
   - slug: {slug}
   - track: {tech|case} (include rationale)
   - site_config: blog-ops/config/sites/corporate.json

@seo-director’s distinguishing feature is maintaining the cluster SEO map. It maintains a two-cluster design of business cluster / tech cluster, preserving the structure where spoke articles descend from each cluster’s pillar primary_keyword:

## Operating the 2-cluster design

- **business cluster**: primary_keywords target management decision and investment decision queries
- **tech cluster**: primary_keywords target design patterns, implementation patterns, and tool queries
- **Avoid primary_keyword overlap between the 2 clusters** (cannibalization prevention)

The @seo-director keyword <slug> mode returns a YAML draft of the seo: section for the article brief. Main-thread writes it to a file and uses it as input for the next skill (/blog-plan):

seo:
  primary_keyword: "AI agent organization design Claude Code"
  secondary_keywords:
    - "Claude Code agent design implementation"
    - "{domain}-director pattern agent"
  longtail_clusters:
    - "How to design a cross-functional agent organization with Claude Code"
  search_intent: "informational"
  serp_title_finalized: "Synapse Agent Architecture — The {domain}-director Pattern"
  cluster_position: "tech cluster pillar (tech axis of the synapse-org series)"

Fallback Design

How Responsibility Flows on Agent Failure

Synapse’s fallback design operates at three levels:

Processing failure inside a skill
  → Attach HUMAN_INPUT markers and return the draft
  → Explicitly signal to main-thread that human confirmation is required

/blog-review returns a fail verdict
  → Halt the pipeline and request user confirmation
  → Output the fail reasons structured in 04_review.md

Agent cannot make a decision (split recommended, etc.)
  → Halt the flow and request user confirmation
  → Present decision materials (rationale and multiple options)

The HUMAN_INPUT markers in the /blog-tech-write skill are a canonical fallback example. Markers are embedded for information the AI cannot verify (specific figures, failure cases, concrete names of rejected alternatives), leaving space for humans to fill in later:

{{HUMAN_INPUT: When production operation of Synapse began (when did Synapse go live)}}
<!-- Currently .claude/skills/ has 15 skills defined (blog-audit / blog-case / blog-case-write / blog-classify / blog-fill-ssot / blog-fact-check / blog-meta / blog-pattern / blog-plan / blog-publish / blog-retro / blog-review / blog-tech-write / blog-translate / ui-ux-pro-max) -->

If a skill produces fewer HUMAN_INPUT markers than the required minimum (5+ for tech), it automatically enters a regeneration loop. If after two retries the count is still below the threshold, the blockers are recorded in _state.json and reported to the human.

Designing Human Escalation Triggers

Synapse’s human escalation triggers fire under the following conditions:

The @editor-in-chief definition file contains the following declaration:

Non-stop automated execution is prohibited. When /blog-review produces a fail or
immediately before /blog-publish, always request user confirmation.

By writing this single line in the agent definition, this constraint is included in the context every time Claude Code invokes @editor-in-chief.

Design Decision Record — Why This Structure

Why We Did Not Use a Flat Structure

Initially we tried a design of “just call all skills directly from main-thread.”

The problem with a flat structure is that domain knowledge for decisions concentrates in main-thread. When all decisions — “is this article tech track or case track?”, “are the SEO keywords overlapping?” — are made by main-thread without assigning responsibility to agents:

• main-thread context balloons in size
• Reference documents must be passed in every time the same decision is made
• It becomes unclear “who holds knowledge for this domain”

The reason for introducing the {domain}-director pattern is to anchor domain knowledge and its reference sources to responsible agents. Ask @seo-director and you get an SEO decision. Ask @editor-in-chief and you get editorial policy. The location of knowledge becomes clear.

Why We Did Not Mix Skills into agents/

An implementation that writes execution procedures directly into .claude/agents/ is also conceivable. However, Synapse separates agents from skills.

The reason is reusability. Skills such as /blog-tech-write:

• Can be invoked directly from main-thread
• Can be referenced from the pipeline DAG (JSON)
• Can be listed as “next actions” in an agent’s execution plan

Mixing procedures into agent definitions makes skills unable to be shared across multiple pipelines. /blog-tech-write is used in both the new-article-pillar pipeline and the rewrite-tech pipeline. Separation made reuse possible.

Keep CLAUDE.md to Delegation Conventions Only — Writing Details Breaks SSOT

The delegation rules written in CLAUDE.md should be limited to “declarations of the invocation route.”

## Invariant Rules (CLAUDE.md)

- Blog operations: Any business work involving articles must go through a responsible agent

The internal rules of each agent (reference documents, per-mode behavior, fallback) belong in agents/*.md. Writing too much detail in CLAUDE.md multiplies the number of places where rules must be updated, breaking SSOT.

The separation criteria:

Update frequency also justifies the separation. Invocation routes almost never change, but skill procedures are improved frequently. Do not place things with different rates of change in the same file — that is why CLAUDE.md is kept minimal.

Synapse Harness Design Checklist — Summary

When building a cross-functional agent organization on Claude Code, here are the principles extractable from Synapse’s design.

Checklist for Introducing the {domain}-director Pattern

• Are agents defined along three dimensions: domain of responsibility × authority × delegation target?
• Does each agent act strictly as an advisor, returning execution plans to main-thread?
• Are you avoiding the creation of “task agents” (which violates Claude Code’s sub-agent constraint)?
• Is the invocation route — “which agent to launch through” — declared in CLAUDE.md?

Quality Checklist for .claude/agents/ Definitions

• Does the frontmatter include name / description / model / tools?
• Is the domain section (matters the agent can decide on its own) explicitly stated?
• Is the delegation section (where to escalate matters outside its authority) explicitly stated?
• Is there a reference documents section listing the file paths that serve as the basis for decisions?
• Are “no non-stop automated execution” and “return to main-thread at each judgment checkpoint” declared?

I/O Contract Checklist for .claude/skills/

• Are the inputs (files read and arguments) explicitly stated in SKILL.md?
• Are the outputs (files written) explicitly stated in SKILL.md?
• Are the preconditions (state the skill expects) explicitly stated?
• Is alignment with the pipeline DAG (blog-ops/config/pipelines/\*.json) maintained?

Fallback Design Checklist

• Does each skill use HUMAN_INPUT markers to explicitly flag information requiring human confirmation?
• Is the pipeline designed to halt on review fail and request user confirmation?
• Is there always a human-confirmation step immediately before publish?

Synapse makes full use of Claude Code’s agent capabilities, yet the mechanism itself is nothing more than placing Markdown files in .claude/agents/ and .claude/skills/. Even a complex-looking agent organization can be derived from just two principles: the {domain}-director pattern and skill separation.

For the business perspective — how Synapse is integrated into business operations and how to structure an engineering team to collaborate with agents — see How to Launch an AI Agent Organization.