# Codebase Structure

**Analysis Date:** 2026-03-28

## Directory Layout

```
claude_skill_owl/
├── .planning/              # GSD planning documents (not part of the skill)
│   └── codebase/           # Codebase analysis documents
├── docs/                   # Design specs and deployment guide
│   ├── DEPLOY.md           # Installation, bundling, and commit instructions
│   └── SKILL_SPEC-LIVE.md  # Future "Live Agent" system spec (not yet implemented)
├── CLAUDE.md               # Claude Code project instructions
├── SKILL.md                # Skill manifest -- loaded by Claude Code's skill system
└── owl.sh                  # Bash runtime -- all messaging logic
```

## Directory Purposes

**Root (`claude_skill_owl/`):**
- Purpose: Development working directory for the owl skill
- Contains: The two deliverable files (`SKILL.md`, `owl.sh`) plus project metadata
- Key files: `SKILL.md` (skill manifest), `owl.sh` (runtime script), `CLAUDE.md` (project instructions)

**`docs/`:**
- Purpose: Documentation for developers and future design specs
- Contains: Deployment guide and specification for a planned Live Agent extension
- Key files: `docs/DEPLOY.md` (deployment workflow), `docs/SKILL_SPEC-LIVE.md` (Live Agent/Psyche/Spine spec)

**Runtime data directory (not in repo): `$HOME/.claude/owlery/`:**
- Purpose: Runtime state for all active owl perches and message queues
- Contains: Per-agent directories with `ready`, `info.json`, and `inbox/` subdirectories
- Generated: Yes, at runtime by `owl.sh`
- Committed: No -- lives outside the repo entirely

**Deployment target (not in repo): `$HOME/.claude/skills/owl/`:**
- Purpose: Where Claude Code loads the skill from at runtime
- Contains: Copies of `SKILL.md` and `owl.sh` installed via `docs/DEPLOY.md`
- Generated: Yes, by manual copy
- Committed: No

## Key File Locations

**Entry Points:**
- `owl.sh`: The single bash script that implements all messaging commands
- `SKILL.md`: The skill manifest that Claude Code loads to learn the owl API

**Configuration:**
- `CLAUDE.md`: Project-level instructions for Claude Code sessions working on this repo
- `~/.claude/settings.json`: Must contain `"env": { "OWL": "bash <path>/owl.sh" }` for runtime use (not in repo)

**Core Logic:**
- `owl.sh` lines 11-14: `_get_pid()` -- extract PID from info.json
- `owl.sh` lines 16-26: `_check_alive()` -- validate target perch is active
- `owl.sh` lines 28-33: `_write_msg()` -- write a message file to an inbox
- `owl.sh` lines 35-47: `_poll_once()` -- blocking poll loop that waits for a message
- `owl.sh` lines 49-163: Case dispatch for all subcommands (setup, poll, deliver, reply, send, list, stop)

**Documentation:**
- `docs/DEPLOY.md`: How to install, bundle, and share the skill
- `docs/SKILL_SPEC-LIVE.md`: Design spec for Live Agent system (Psyche, Spine, Touch -- not yet implemented)

## Naming Conventions

**Files:**
- Uppercase `.md` for project-level documents: `SKILL.md`, `CLAUDE.md`
- Lowercase for scripts: `owl.sh`
- Uppercase for docs subdirectory files: `DEPLOY.md`, `SKILL_SPEC-LIVE.md`

**Directories:**
- Lowercase: `docs/`
- Dot-prefixed for tooling: `.planning/`

**Runtime (owlery) naming:**
- Perch directories use the agent's chosen ID as the directory name
- Message files: `<epoch_seconds>-<random>.msg`
- Metadata: `info.json`, `ready` (marker file, no extension)

## Where to Add New Code

**New owl.sh subcommand:**
- Add a new case branch in `owl.sh` inside the `case "$cmd" in` block (line 49)
- Add corresponding usage documentation in `SKILL.md` following the existing pattern (command table + detailed section)
- If the subcommand needs the SKILL.md instruction to describe agent behavior, add a section with heading `## /owl <command>`

**New helper function:**
- Add to `owl.sh` before the `case` statement (lines 11-47 area), prefixed with underscore: `_function_name()`

**New documentation:**
- Place in `docs/` with uppercase naming: `docs/NEW_TOPIC.md`

**New skill (not owl-related):**
- This repo is owl-specific. A separate skill would be a separate repo/directory under `~/.claude/skills/`

## Special Directories

**`.planning/`:**
- Purpose: GSD planning and analysis documents
- Generated: By GSD tooling
- Committed: Depends on project preference

**`$HOME/.claude/owlery/` (external):**
- Purpose: Runtime message queue state
- Generated: Yes, by `owl.sh` at runtime
- Committed: No -- ephemeral runtime data, not in any repo

**`$HOME/.claude/skills/owl/` (external):**
- Purpose: Live deployment target where Claude Code reads the skill
- Generated: Manual copy from this working directory
- Committed: No -- deployment artifact

---

*Structure analysis: 2026-03-28*