Explains design rationale: orchestration as file manipulation
Benefits: simplicity, universal access, composability
Placement: after Architecture, before Requirements
Addresses the 'why this obscure protocol' question upfront
Backend changes:
- Add CreatedAt() to Session interface
- Implement CreatedAt() in tmux.Session (field already existed)
- Sort Manager.List() by creation time descending
Benefits:
- Deterministic ordering (no more random map iteration)
- Newest sessions appear first (most useful)
- All clients benefit immediately
- head -1 now reliably gets most recent session
README:
- Update example to use head -1 for newest session
- Document that list is sorted newest first
- Remove tail -1 hack (doesn't work - map iteration is random)
- Show listing sessions first with output format
- Document that order is non-deterministic
- Use manual ID selection (realistic workflow)
The session list iterates over a Go map, which has non-deterministic
order. Cannot rely on tail/head to get 'last created' session.
Filesystem tree fixes:
- Remove non-existent 'in' and 'out' files
- Add missing 'role', 'tasks', 'tmux' files
Example fixes:
- Use mailbox system for prompts (user/mail with JSON message)
- Show reading response from user/inbox
- Correct workflow: prompts are messages, not direct writes
The old 'in/out' interface no longer exists - all communication
is via the mailbox system
- Rename 'Example' to 'Basic Session Example' (more descriptive)
- Fix workflow: get actual session ID from list (not hardcoded)
- Add comments explaining each step
- Show both 'running' and 'idle' as possible states
Previous example used hardcoded ID that wouldn't exist
- Remove duplicate Namespaces line
- Standardize separator style: em dash (—) throughout
- Remove trailing periods from standalone statements
- Merge Acme tag and interaction notes inline
- Reorder Emacs keys to match TUI order (help before quit)
- 5 lines removed (consolidation)
- Flatten service integration into single block
- Consolidate all client sections (TUI/Emacs/web/Acme) into compact format
- Merge beads commands into single code block
- Combine events & mailbox into one section
- Merge backends, self-healing, sandboxing into unified section
- Condense workflows: merge skills, examples, patterns
- Tighten troubleshooting table
- 126 lines removed (38% reduction from previous)
- Emit initial state change event (stopped -> starting) when session is created
- Rename 'exited' state to 'killed' for clarity
- Remove duplicate killed event emission (Close() already emits via transitionToLocked)
- Set OnStateChange callback in NewManager to emit state change events
- All state changes now properly emit events via callbacks
- Wire all state changes in tmux session to use transitionToLocked (triggers OnStateChange)
- Close() exited state
- Refresh() stopped states (intentional stop, restart spam prevention, auto-restart failure, PID=0)
- Add event callbacks to mailbox manager for send/receive events
- Callbacks fire when message removed from outbox (send) and delivered to inbox (receive)
- Consistent with state change callback pattern
- Fix /events 9p read handler to respect offset/count
- Prevents infinite read loop by properly signaling EOF
- Uses readFile() pattern like /list for consistency
- Added dual-mode support: JSON stdin or event name as argument
- Updated agent config to use agent-hook with event names
- Centralizes all hook logic in one script
- Works with both wrapper scripts and direct Kiro hooks
- Added agent-hook for future use with wrapper script
- Created SKILLS_PROMPT.md for automatic skill loading
- Updated mkfile to install both
- Kept explicit commands in agent config (agent-hook needs wrapper)
- Parse JSON and format as: [Message from X] / Type / Subject / Body
- Makes it clear who the sender is for replying
- Matches original 9p-read-inbox behavior
- Read only first message (not all messages)
- Automatically mark message as complete after reading
- Matches behavior of original 9p-read-inbox script
- Reduced from 304 to 102 lines
- Removed redundancy and verbose explanations
- Kept all essential information and examples
- More scannable and focused
- Updated anvillm-communication skill to use MCP tools
- Changed session.go to instruct agents to use send_message
- Updated manager.go to tell agents to use read_inbox
- Updated Claude hook to mention read_inbox tool
- Cleaner, more consistent interface across all documentation
- Remove mcpServers from agent config
- Add includeMcpJson: true to use ~/.kiro/settings/cli.json
- Allows agent to access MCP servers from global config
- Simplified Claude hooks to use AGENT_ID instead of PID lookup
- Updated 9p-read-inbox to use AGENT_ID env var
- Removed temporary file creation in tmux.go
- Much cleaner and more reliable approach
Levi Neely
Levi Neely