claude-agent-org-tools

日本語ドキュメント (Japanese)

Organization-theory based tools for Claude Code Agent Teams.

8 tools derived from manufacturing, software engineering, and knowledge management patterns:

| Tool | Origin | Purpose | |------|--------|---------| | Andon Signal | Toyota Production System | Emergency stop that blocks all agent writes | | Team Topology Protocol | Team Topologies (Skelton & Pais) | Enforce file ownership boundaries | | RACI Auto-Router | RACI Matrix | Route task completion notifications by role | | Organizational Memory | Agile Retrospective | Auto-generate session retrospectives | | Workflow Blueprint | takt Pieces | Declarative step-based workflow definitions | | Quality Gate | Parallel Review | Aggregated review gates (all/any approved) | | Execution Trace | Observability | NDJSON event logging for full traceability | | Knowledge Base | SECI Model | Persistent organizational knowledge by domain |

Integration Paths

              src/hooks/  (shared core logic)
                    │
        ┌───────────┼───────────┐
        │                       │
   Hook Entrypoint         MCP Server
   (exit code 2 block)     (stdio JSON-RPC)
   Claude Code only        Claude Code + Codex CLI

Both paths call the same functions. Zero logic duplication.

Quick Start

Hook mode (Claude Code)

cd your-project
npx claude-agent-org-tools init

This single command:

1. Places the hook entrypoint at .claude/hooks/org-tools.mjs
2. Generates .claude/org-tools/config.json with defaults
3. Merges hook definitions into .claude/settings.json (safely, without breaking existing hooks)

MCP Server mode (Claude Code + Codex CLI)

# Claude Code
claude mcp add org-tools -- npx claude-agent-org-tools mcp-server

# Codex CLI
codex mcp add org-tools -- npx claude-agent-org-tools mcp-server

Or commit .mcp.json for project-wide sharing:

{
  "mcpServers": {
    "org-tools": {
      "type": "stdio",
      "command": "npx",
      "args": ["claude-agent-org-tools", "mcp-server"]
    }
  }
}

What's Enabled by Default

| Tool | Default | Why | |------|---------|-----| | Andon Signal | ON | Zero config needed. No andon files = no effect | | Organizational Memory | ON | Zero config needed. Generates retrospectives on session end | | Workflow Blueprint | ON | Zero config needed. No workflow files = no effect | | Quality Gate | ON | Zero config needed. No gate files = no effect | | Execution Trace | ON | Zero config needed. Logs events when called | | Knowledge Base | ON | Zero config needed. Stores entries when called | | Team Topology | OFF | Requires topology.json with agent ownership map | | RACI Auto-Router | OFF | Requires raci.json with routing matrix |

CLI Commands

claude-org init                          # Initialize in current project
claude-org status                        # Show tool status
claude-org enable <tool>                 # Enable a tool
claude-org disable <tool>                # Disable a tool
claude-org andon <team> "reason"         # Trigger emergency stop
claude-org andon <team> --release        # Release emergency stop
claude-org mcp-server                    # Start MCP Server (stdio)

How It Works

A single JavaScript file (.claude/hooks/org-tools.mjs) handles all hook events:

PreToolUse (Write|Edit|Bash)  → Andon check + Topology boundary check
PostToolUse (TaskUpdate)      → RACI routing suggestion
Stop                          → Retrospective generation

Tool ON/OFF is controlled via .claude/org-tools/config.json, not by editing settings.json.

Tool Details

Andon Signal

Trigger an emergency stop when a critical issue is detected:

claude-org andon backend "DB schema migration in progress"

This creates .claude/org-tools/andon/backend.json. While this file exists, all Write, Edit, and Bash tool calls are blocked with exit code 2.

Release when resolved:

claude-org andon backend --release

Team Topology Protocol

Define agent file ownership in .claude/org-tools/topology.json:

{
  "agents": [
    {
      "name": "frontend",
      "type": "stream-aligned",
      "owns": ["src/frontend/**", "src/components/**"],
      "interactionMode": "collaboration"
    },
    {
      "name": "platform",
      "type": "platform",
      "owns": ["infra/**"],
      "interactionMode": "facilitating"
    }
  ]
}

• facilitating mode: Write/Edit to owned files is blocked
• collaboration mode: Cross-team writes produce warnings

RACI Auto-Router

Define routing rules in .claude/org-tools/raci.json:

{
  "matrix": [
    {
      "taskPattern": "deploy.*production",
      "responsible": "sre",
      "accountable": "tech-lead",
      "consulted": ["qa"],
      "informed": ["product-manager"]
    }
  ]
}

When a TaskUpdate sets status to completed and the subject matches a pattern, a routing suggestion is logged.

Organizational Memory

On session end (Stop hook), generates a Markdown retrospective per active team:

.claude/org-tools/retrospectives/{team-name}-{date}.md

Workflow Blueprint (v0.4)

Define recommended step sequences in .claude/org-tools/workflows/feature.yaml:

name: feature
description: Feature development workflow
initial_step: plan
steps:
  - name: plan
    description: Create implementation plan
    role: planner
    edits_allowed: false
    transitions:
      - condition: plan_complete
        next: implement
  - name: implement
    description: Write code
    role: implementer
    edits_allowed: true
    transitions:
      - condition: code_complete
        next: review
  - name: review
    description: Review code
    role: reviewer
    edits_allowed: false
    parallel_reviewers:
      - security-reviewer
      - code-reviewer
    gate: all_approved
    transitions:
      - condition: approved
        next: COMPLETE
      - condition: needs_fix
        next: implement

MCP tools: list_workflows, get_workflow_step

Quality Gate (v0.4)

Parallel review aggregation with configurable gate modes:

configure_quality_gate → submit_review (×N) → check_quality_gate

• all_approved: Every required reviewer must approve
• any_approved: One approval is sufficient

MCP tools: configure_quality_gate, submit_review, check_quality_gate, list_quality_gates

Execution Trace (v0.4)

NDJSON event logging for full session traceability:

log_trace_event → query_trace (filter by agent/event/task)

Events stored in .claude/org-tools/traces/{session-id}.ndjson.

MCP tools: log_trace_event, query_trace

Knowledge Base (v0.4)

Persistent organizational knowledge organized by domain:

save_knowledge → query_knowledge (by domain/category/tags/text)

Entries stored in .claude/org-tools/knowledge/{domain}/{id}.json.

MCP tools: save_knowledge, query_knowledge

MCP Tool Reference

| Tool | Input | Output | |------|-------|--------| | check_andon | {projectDir?} | {status, team?, severity?, reason?} | | trigger_andon | {team, reason, severity?} | {triggered, team, severity} | | release_andon | {team} | {released, team} | | check_topology | {filePath, callerAgent?} | {violation, block?, reason?} | | suggest_raci | {taskSubject, status?} | {matched, accountable?, consulted?, informed?} | | generate_retrospective | {outputDir?} | {generated, files} | | list_workflows | {projectDir?} | {workflows} | | get_workflow_step | {workflowName, currentStep?, condition?} | {found, step, next_step?} | | configure_quality_gate | {taskId, gate, required_reviewers} | {configured, taskId, gate} | | submit_review | {taskId, reviewer, verdict, comment?} | {submitted, gate_status} | | check_quality_gate | {taskId} | {passed, approved_count, pending_reviewers} | | list_quality_gates | {projectDir?} | {gates} | | log_trace_event | {event, agent?, taskId?, data?} | {logged, event} | | query_trace | {sessionId?, agent?, event?, limit?} | {events, total, filtered} | | save_knowledge | {domain, title, content, tags?} | {saved, entry} | | query_knowledge | {domain?, search?, tags?, limit?} | {entries, total} |

File Structure

.claude/
  hooks/
    org-tools.mjs                # Single hook entrypoint (auto-generated)
  org-tools/
    config.json                  # Tool enable/disable config
    andon/                       # Andon signal files (per-team)
    retrospectives/              # Generated retrospective reports
    workflows/                   # Workflow blueprint YAML files
    quality-gates/               # Quality gate state (per-task)
    traces/                      # Execution trace logs (NDJSON)
    knowledge/                   # Knowledge base entries (per-domain)
    topology.json                # [User-created] Agent ownership map
    raci.json                    # [User-created] RACI routing matrix
    raci-suggestions.jsonl       # [Auto-generated] RACI routing log

Requirements

• Node.js >= 18 (or Bun >= 1.0)
• Claude Code with hooks support (hook mode)
• Claude Code or Codex CLI (MCP Server mode)

Development

bun install
bun test        # 69 tests
bun run build   # Compile TypeScript to dist/

License

MIT