# Coding Conventions

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

## Codebase Nature

This is a two-file skill for Claude Code: a bash script (`owl.sh`) and a markdown prompt document (`SKILL.md`). There is no application code in a traditional programming language. Conventions center on bash scripting style and markdown documentation structure.

## Naming Patterns

**Files:**
- Shell scripts: lowercase with `.sh` extension: `owl.sh`
- Markdown documents: UPPERCASE for top-level docs (`SKILL.md`, `CLAUDE.md`), UPPERCASE for docs subdirectory (`DEPLOY.md`, `SKILL_SPEC-LIVE.md`)
- Use hyphens to separate words in filenames: `SKILL_SPEC-LIVE.md` (mixed underscore/hyphen -- not fully consistent)

**Bash Functions:**
- Private/internal helper functions prefixed with underscore: `_get_pid()`, `_check_alive()`, `_write_msg()`, `_poll_once()`
- Use snake_case for function names: `_poll_once`, `_check_alive`

**Bash Variables:**
- UPPERCASE for all variables: `OWLERY`, `PERCH`, `ID`, `MODE`, `TARGET_ID`, `FROM_ID`, `BODY`
- UPPERCASE for environment constants: `$OWL`, `$HOME`
- lowercase only for short-lived loop/local variables: `cmd`, `msg`, `d`, `pid`

**Identifiers (runtime):**
- Owl IDs are short single-word strings: `deployah`, `waffle`
- Ephemeral reply IDs use shell variable interpolation: `reply-$$-$RANDOM`
- Psyche IDs follow `{self_id}-psyche` pattern (per `docs/SKILL_SPEC-LIVE.md`)

**Output Messages:**
- Status outputs use `TAG:value` format with no space after colon: `READY:$ID`, `SENT:$TARGET_ID`, `STOPPED:$ID`
- Error outputs use `TAG: message` format with space after colon: `NO_PERCH: $id is not listening`, `STALE: $id's poll process is dead`

## Code Style

**Formatting:**
- No automated formatter or linter configured
- 2-space indentation in bash (observed in `owl.sh`)
- No trailing whitespace issues observed

**Linting:**
- No ShellCheck configuration (`.shellcheckrc`) present
- No CI linting pipeline

**Shell Script Structure in `owl.sh`:**
1. Shebang line: `#!/usr/bin/env bash`
2. Header comment describing purpose
3. Global constants
4. Helper functions (underscore-prefixed)
5. `case` statement dispatching on subcommand
6. Each case block handles one subcommand

**Quoting:**
- Variables are generally quoted in conditionals: `[ ! -f "$target/ready" ]`
- Some unquoted expansions exist in non-critical positions (e.g., arithmetic contexts)

## Import Organization

Not applicable -- single bash script with no imports or sourcing.

## Error Handling

**Patterns:**
- `_check_alive()` prints a diagnostic message and calls `exit 1` on failure
- Commands that can fail harmlessly use `2>/dev/null` redirection: `shift 2>/dev/null || true`
- Cleanup of missing files uses `|| true` to suppress errors: `rm -f "$PERCH/inbox/"*.msg 2>/dev/null || true`
- `rmdir` used (not `rm -rf`) for parent directories to avoid removing non-empty dirs: `rmdir "$PERCH" 2>/dev/null || true`

**Exit codes:**
- `exit 1` for errors (unknown command, dead target)
- `exit 0` for empty list result
- Implicit 0 exit for successful operations

## Logging

**Framework:** stdout/stderr only (no logging framework)

**Patterns:**
- Normal output goes to stdout: `echo "SENT:$TARGET_ID"`
- Setup messages during combined operations go to stderr: `echo "READY:$ID" >&2` (in `poll --setup`)
- Send confirmations during combined operations go to stderr: `echo "SENT:$TARGET_ID" >&2` (in `send`)
- This stdout/stderr split allows the caller to distinguish between "data output" (message content on stdout) and "status output" (confirmations on stderr)

## Comments

**When to Comment:**
- Each helper function has a one-line comment explaining purpose
- Inline comments for non-obvious logic (e.g., `# --setup flag: create perch inline`)
- File-level comment on line 2 of `owl.sh`: purpose + dependency note

**Style:**
- Single `#` with one space before comment text
- Comments on their own line, not trailing

## Documentation Conventions

**SKILL.md (prompt document):**
- YAML frontmatter with `name` and `description` fields
- Markdown with tables for command reference
- Fenced code blocks for all bash examples
- Numbered step lists for procedural instructions
- Bold for emphasis on critical rules
- `---` horizontal rules to separate major sections

**CLAUDE.md:**
- Brief project description
- Points to `docs/DEPLOY.md` for workflow instructions

**docs/DEPLOY.md:**
- Step-by-step deployment guide with fenced code blocks
- Covers: local install, env var setup, bundling, installing from bundle, committing

## Commit Message Convention

Prefix with `owl:` followed by description of change:
```
git commit -m "owl: <describe change>"
```
(Per `docs/DEPLOY.md` line 57)

## Module Design

**Exports:** Not applicable (single script, no module system)

**Barrel Files:** Not applicable

**Subcommand dispatch:** `case` statement in `owl.sh` routes to: `setup`, `poll`, `deliver`, `reply`, `send`, `list`, `stop`

---

*Convention analysis: 2026-03-28*