Octocode Awareness

AGENTS routes; skill decides; CLI/SQLite acts; hooks automate deterministic edges. Memory and .octocode/ are leads. Never hand-edit .octocode/. Run live-state actions through the CLI. When the host supports delegation, ALWAYS batch routine deterministic Awareness CLI reads, writes, and maintenance into one phase. Use the smallest capable low-cost agent (for example Haiku or Composer 2.5); supply decided scope, require --compact, and cap its receipt at 512 bytes. The lead retains destructive approval, conflict handling, memory-truth judgment, and verification. Run directly only when the host cannot delegate.

Lifecycle

<cli>: local node packages/octocode-awareness/out/octocode-awareness.js; installed npx @octocodeai/octocode-awareness. Set OCTOCODE_AGENT_ID per agent/session. BEFORE/READ+REASON -> DURING/DO -> AFTER/VERIFY -> LEARN? -> CLEAN? -> PROJECT?

BEFORE: attend; follow next; state goal, acceptance, affected scope, and evidence. Use memory recall --smart only if it may change the plan; choose task or WORK.
DURING: declare paths via hooks or work start; read peers. Ordinary overlap is allowed; never bypass conflict. Hooks never choose plans, locks, success, learning, cleanup, or projection.
AFTER: check while present; task submit/work end; verify mark; verify audit. Expiry never means success.
OPTIONAL: reflect record --lesson only for verified reusable outcomes; clean only under pressure; project only for file readers. Loop: attend -> work start -> edit/check -> work end -> verify mark -> verify audit; add --exclusive when required. lock wait/prune are recovery.

Feature map — all features; load owners only for depth

Orient/state: attend, workspace status, query, session capture, agent registry. When inspecting storage/session, load references/architecture.md for storage boundaries.
Plan/task: dependencies/readiness/claim/heartbeat/submit/release. When choosing plan, task, or WORK, load references/plan-task-workflow.md for task routing.
Work/files: start/touch/end/list/show. When overlap matters, load references/files-awareness.md for peer semantics.
Exclusive work/verify: work start --exclusive, lock recovery, mark/audit. When exclusivity or debt matters, load references/lock-protocol.md for conflict gates.