OCTAV Bootstrap Kit

This repository contains a reusable bootstrap kit for introducing Operational Consciousness Toolkit for Agentic Vision (OCTAV) into a software project.

OCTAV is a software engineering methodology designed to help an AI model maintain an operational awareness of a project and assist its evolution under human supervision.

OCTAV does not mean fully autonomous development.

It means a project becomes:

• explicit enough to be understood by an AI;
• structured enough to be safely evolved;
• tested enough to detect regressions;
• documented enough to preserve decisions;
• observable enough to assess risks, drift and roadmap progress.

Quick Start (CLI)

Install OCTAV into any existing project with one command — no global install required:

npx octav-kit init --profile=core+tests

This copies the kit into docs/octav/, generates the project-owned files (STATE.md plus the logs for your profile), and wires your AI tool (AGENTS.md, or .cursor/rules/ if a .cursor/ directory is present) to point at docs/octav/INDEX.md. It never touches runtime code.

Then ask your AI coding assistant:

Start at `docs/octav/INDEX.md`.

Do not modify code yet.

Analyze this project and prepare an OCTAV integration plan according to the bootstrap instructions.

INDEX.md is the single entry point. The AI loads the kernel, then pulls only what the current task needs — it should not read every file. The first output is an analysis and proposal, not code changes.

CLI commands

| Command | Purpose | |---|---| | octav init [--profile=<p>] [--dir=<path>] | Install OCTAV + scaffold the chosen profile | | octav status | Show profile, capabilities and STATE.md freshness | | octav add <cap> | Add a capability (roadmap, todo, tests, decisions, risk, hypotheses, vocabulary, datamodel) | | octav remove <cap> | Remove a capability (its log is archived, not deleted) | | octav update | Refresh kernel + practices; never touches project logs | | octav doctor | Validate the installation | | octav uninstall [--all] | Remove OCTAV (reversible; runtime code untouched) |

The CLI maps directly onto the kit's layer model: static files (kernel rules + practices) are copied and refreshed by init/update, while logs (STATE.md, roadmap.md, …) are project-owned and never overwritten. A small .octav.json manifest in docs/octav/ records the active profile and kit version.

Useful flags: --profile=core+roadmap+todo+tests, --with-claude / --with-cursor / --with-agents / --no-wire (tool pointer), --yes (skip confirmations), --force (reinstall).

Manual usage (no CLI)

You can still copy this kit into docs/octav/ by hand. The generated instance files (STATE.md, roadmap.md, …) live in that same docs/octav/ directory, and you run the same initialization prompt above.

The 3-Layer Model

OCTAV files are organized by how they behave (see octav-architecture.md):

• Kernel (always loaded): octav-operating-rules.md + STATE.md.
• Logs (per-project state, loaded when relevant): roadmap.md, todo.md, decisions.md.
• Practices (knowledge, on demand): testing, blind-spots, git, rollback, roadmap, profiles.

Core Documents

| File | Layer | Purpose | |---|---|---| | INDEX.md | Kernel | Single entry point + task→file map | | octav-operating-rules.md | Kernel | AI behavior and the four validation gates | | octav-state.md | Kernel | Spec for STATE.md, the operational-awareness snapshot | | octav-philosophy.md | Meta | Principles and scope (the why) | | octav-architecture.md | Meta | The 3-layer model and file mapping | | octav-profiles.md | Practice | Composable capability/profile system | | octav-failure-modes.md | Meta | How OCTAV can harm a project + safeguards | | octav-initialization-prompt.md | Meta | Entry ritual + initialization-report template | | octav-project-analysis.md | Practice | Initial project audit | | octav-roadmap.md | Practice | Roadmap strategy → produces roadmap.md | | octav-todo.md | Practice | Tactical TODO strategy → produces todo.md | | octav-decisions.md | Practice | Decision history → produces decisions.md | | octav-testing.md | Practice | Regression and test strategy | | octav-blind-spots.md | Practice | Technical/product/legal/economic/human risks | | octav-git.md | Practice | Commit discipline | | octav-branching.md | Practice | Branch strategy + Git operations requiring human approval | | octav-rollback.md | Practice | Soft disable and hard rollback |

Files consolidated during the redesign are kept in archive/ (see archive/README.md).

Recommended First Step

For an existing project, start with:

1. project analysis;
2. OCTAV readiness assessment;
3. proposed minimal OCTAV structure;
4. no code modification;
5. human validation.

Important

OCTAV must remain:

• adaptive;
• lightweight;
• reversible;
• proportional to project complexity;
• non-invasive for runtime code.