/octocode-awareness

name: octocode-awareness
description: "Use when coordinating work in a shared repo — multi-agent or solo across sessions: collision avoidance, handoffs, verification debt, durable memory/wiki, hooks setup/debug, and repo learning before planning, editing, reviewing, or testing."
hooks:
  PreToolUse: [{ matcher: "^(?:Write|Edit|MultiEdit|NotebookEdit)$", hooks: [{ type: command, command: "${CLAUDE_SKILL_DIR}/scripts/hooks/pre-edit.sh", timeout: 20 }] }]
  PostToolUse: [{ matcher: "^(?:Write|Edit|MultiEdit|NotebookEdit)$", hooks: [{ type: command, command: "${CLAUDE_SKILL_DIR}/scripts/hooks/post-edit.sh", timeout: 20 }] }]
  PostToolUseFailure: [{ matcher: "^(?:Write|Edit|MultiEdit|NotebookEdit)$", hooks: [{ type: command, command: "${CLAUDE_SKILL_DIR}/scripts/hooks/post-edit.sh", timeout: 20 }] }]
  SubagentStart: [{ hooks: [{ type: command, command: "${CLAUDE_SKILL_DIR}/scripts/hooks/notify-deliver.sh", timeout: 20 }] }]
  Stop: [{ hooks: [{ type: command, command: "${CLAUDE_SKILL_DIR}/scripts/hooks/stop-verify.sh", timeout: 20 }] }]
  SubagentStop: [{ hooks: [{ type: command, command: "${CLAUDE_SKILL_DIR}/scripts/hooks/stop-verify.sh", timeout: 20 }] }]
  PreCompact: [{ hooks: [{ type: command, command: "${CLAUDE_SKILL_DIR}/scripts/hooks/session-compact.sh", timeout: 20 }] }]
  SessionEnd: [{ hooks: [{ type: command, command: "${CLAUDE_SKILL_DIR}/scripts/hooks/session-end.sh", timeout: 20 }] }]
  UserPromptSubmit: [{ hooks: [{ type: command, command: "${CLAUDE_SKILL_DIR}/scripts/hooks/notify-deliver.sh", timeout: 20 }] }]

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?** 1. **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. 2. **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. 3. **AFTER:** check while present; `task submit`/`work end`; `verify mark`; `verify audit`. Expiry never means success. 4. **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.
• **Signals/refinements:** signal publish/list/reply/ack/resolve/prune; refinement get/set/delete. When peers interact, load `references/coordination-protocol.md` for peer flow.
• **Memory:** recall/record/forget/archive/restore; correct with `--supersedes`. When using memory, load `references/memory-recall.md` for trust rules.
• **Reflection/review:** reflect/review/export harness. When improving, load `references/improve-loop.md` for acceptance gates.
• **Knowledge/wiki:** docs/staleness, `wiki sync`, projections. When choosing output, load `references/output-routing.md` for lean routing.
• **Hooks/hosts:** install/check/remove/run across Claude/Codex/Cursor/Pi. When configuring/debugging, load `references/hooks.md`.
• **Maintenance/contracts:** maintenance and schema commands/list/path/json-schema/example/validate. When cleaning/learning, load `references/bookkeeping.md` for pressure gates.
• **Recipes:** when a start, finish, or command recipe is unknown, load `references/agent-cheatsheet.md`; unknown owner only: `docs list --compact`, then `docs show <name>`.
• **Skill evolution:** when shipping a skill change, load `references/skill-evolution.md`; use `octocode-graph-eval` for goal/KPI, `octocode-research` for evidence, and `octocode-skills` for review.

Scripts: use `scripts/awareness.mjs` for fallback, `scripts/schema.mjs` for contracts, `scripts/hook-runner.mjs` for events, `scripts/extract-hook-files.mjs` for paths, `scripts/install.mjs --compact` for diagnosis; run `scripts/smoke-multi-agent.mjs` when validating coordination.

Installation and first activation

Load `README.md`; initialize once, then `attend`. Claude uses frontmatter; do not install duplicate project hooks. When configuring Codex/Cursor, load `references/hooks.md`; Pi uses its bridge. Rebuild with `yarn workspace @octocodeai/octocode-awareness build`; never edit mirrors.