A workshop project exploring Multi-Agent Workflow (MAW), voice notifications, and Claude Code subagents. Built through iterative learning - each failure became a feature, each correction became documentation.

Run multiple AI agents (Claude, Codex) in parallel using git worktrees and tmux.

agents/
├── 1/    # Agent 1 worktree (branch: agents/1)
├── 2/    # Agent 2 worktree (branch: agents/2)
└── 3/    # Agent 3 worktree (branch: agents/3)

macOS speech integration with unique voices per agent.

Custom AI agents defined in .claude/agents/:

Safety principles for multi-agent coordination:

Know who you are (main or agent), sync from the right source (remote or local main), never force anything (-f), respect all boundaries (stay in your worktree).

# Setup MAW agents
.agents/setup.sh

# Launch tmux session
.agents/start-agents.sh profile0

# Smart sync all agents
scripts/smart-sync.sh

.
├── .claude/
│   ├── agents/              # 9 custom subagents
│   ├── commands/            # 17+ slash commands
│   └── settings.json        # Hook configuration
├── .agents/                 # MAW toolkit
│   ├── agents.yaml          # Agent registry
│   ├── profiles/            # Tmux layouts (0-5)
│   └── scripts/             # Setup, start, sync
├── scripts/
│   ├── agent-voices.toml    # Voice configuration
│   ├── agent-*-notify.sh    # Notification hooks
│   ├── smart-sync.sh        # Intelligent sync
│   └── agent-lock.sh        # Lock mechanism
├── ψ-docs/                  # Technical documentation
├── ψ-learnings/             # Distilled wisdom
└── ψ-retrospectives/        # Session retrospectives

The system uses Claude Code hooks to announce agent activity:

# scripts/agent-voices.toml
[voices]
main = "Samantha"
agent_1 = "Daniel"
agent_2 = "Karen"
agent_3 = "Rishi"

Hooks configured:

• SessionStart → Announce session beginning
• Stop → Announce agent completion
• SubagentStop → Announce subagent completion

Speech queue prevents overlapping announcements.

# In Claude Code, subagents are auto-invoked or use Task tool:
Task(subagent_type="thai-translator", prompt="Translate this retrospective")
Task(subagent_type="multi-agent-workflow-monitor", prompt="Check agent status")

Key insights from development:

1. 001-force-push: Safety rules are infrastructure, not guidelines
2. 002-golden-rule: Distill complexity into memorable principles
3. 003-upstream-first: Create upstream issues instead of local patches
4. 004-psi-naming: Use ψ (psi) prefix for meta-directories

"The system works not because it was perfectly designed from the start, but because each iteration learned from the last. Each failure became a feature. Each correction became documentation."

Period: November 30 - December 6, 2025 Focus: Multi-agent coordination, voice notifications, AI self-improvement