octocode-awareness - Claude MCP Skill

# 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.