HOLO

HOLO is a Claude Code plugin that pairs an on-disk AI working-memory framework with a workflow skill suite — the two together make AI-paired sessions resumable across days, weeks, and maintainers.

HOLO turns Claude Code into a structured engineering loop. Every change moves through discuss → land → review → ship, with each stage leaving its own trail on disk — so the next session, whether tomorrow or a month from now, resumes from exactly where the last one stopped.

Features · Quick Start · Initialize · Skills & Commands · Engineering Loop · Configuration

---

✨ Features

• 🎓 Knows your project inside out
  HOLO builds a genuine understanding of your requirements, architecture, and roadmap and keeps it current, so it reasons like a seasoned engineer who's been on the team for months — not a newcomer you brief from scratch each time.
• 🧠 No forgetting, no drift
  A purpose-built set of on-disk memory files — context, decisions, conventions, current state — is re-read at the start of every session, so the AI resumes with the full picture days or weeks later, and won't drift off it mid-session.
• ✂️ No over-engineering
  The AI pushes back instead of building whatever's asked — it questions whether a step is even needed, reaches for the simplest approach, and resists "while I'm here" rewrites, so you get the change you wanted, not a gold-plated one.
• 🔄 Professional, repeatable processes
  Each skill follows its own well-defined, professional process and applies it the same way every time, so the AI works predictably — consistent quality and working state run after run, not a different improvised approach each time.
• 🧩 Flexible, composable workflow
  The skills are building blocks you mix and match to fit how you work and the size of the job — from a quick one-line fix to a sweeping, multi-file change — so your workflow stays flexible while every task still lands as expected.
• 📒 Everything on the record
  Every discussion, decision, change, and review is written to disk, so there's always a trail to follow — when a bug surfaces or a decision gets questioned, you can retrace exactly what happened and why, instead of guessing.
• 🤝 Multi-agent collaboration
  For anything big — a deep review, a whole-repo audit, a large cleanup — HOLO splits the work across several AI agents that run in parallel and cross-check each other, landing it faster and more thoroughly than one agent alone.

---

🚀 Quick Start

1. Install

In Claude Code:

/plugin marketplace add https://github.com/LeanderLXZ/holo.git
/plugin install holo

2. Initialize a project

From inside a new or existing project (details under Initialize a Project):

/holo:init

3. Update

When a new plugin version ships, in Claude Code:

/plugin marketplace update holo
/reload-plugins

Then, inside each project that uses holo, sync any template / skills drift from the new version:

/holo:update

---

🏗️ Initialize a Project

/holo:init (see Quick Start) detects current state, copies the template (silent for new files, interactive keep / overwrite / merge for conflicts), asks a Step 0 language question plus three rounds of setup questions, and verifies that no <...> placeholders remain.

What it asks

Step / Round	Questions	Skippable?
Step 0 — Language axes (asked first)	content_language (disk-bound output) · conversation_language (AI ↔ user turns)	No — drives every subsequent skill
Round 1 — Project basics	project name · 1–2 sentence project goal · main branch · timezone (Q2's answer fans out to README description + plugin.json description + ai_context/project_background.md §Goal)	No — required for skill bookkeeping
Round 2 — Top-level directory classification	which directories are source / data-contract / example-artifact / do-not-commit	Conditional — only asked when extra directories exist (empty / standard skeleton → round skipped automatically)
Round 3 — Doc bootstrap (architecture.md + requirements.md)	per file: Auto-scan project / Manual input / Skip for now	Yes via "Skip for now" — leaves _(none yet — ...)_ markers in those files for progressive fill later

The two language axes shape every later skill invocation:

• content_language — what language the AI writes to disk (ai_context/ / docs/ / logs/ / commits / README / new code comments). Default en; accepts any ISO 639-1 code.
• conversation_language — what language AI ↔ user turns use. Default auto (per-turn match the user's last message); accepts auto or any ISO 639-1 code.

What you get

your-project/
├── CLAUDE.md                    # Claude Code entry point (auto-loaded each session)
├── AGENTS.md                    # Mirror of CLAUDE.md for Codex / Cursor / other runtimes
├── README.md                    # Starter README for your project (placeholders filled in by /holo:init)
├── .gitignore                   # Sensible defaults for this scaffold
├── ai_context/                  # Cross-session memory — read at every session start
│   ├── README.md                  # Index of ai_context/ (fast project follow-up reference)
│   ├── instructions.md            # Read-order for ai_context/ at session start
│   ├── conventions.md             # Cross-file alignment table + writing rules
│   ├── project_background.md      # Why this project exists — goals, scope, stakeholders
│   ├── requirements.md            # Mirrors docs/requirements.md (lockstep)
│   ├── architecture.md            # How the system is built — modules, boundaries, key design
│   ├── decisions.md               # Durable architecture-level decisions log ("why")
│   ├── handoff.md                 # Current state + next steps + user preferences (3-section table layout)
│   └── skills_config.md           ★ Per-project anchors read by skills — see §Configuration
├── docs/
│   ├── requirements.md            # User-facing functional spec
│   ├── todo_list.md               # Planned-but-unfinished engineering tasks
│   ├── todo_list_archived.md      # Completed / abandoned (slim)
│   └── architecture/              # Formal architecture documents
└── logs/
    ├── change_logs/               # per-change activity logs (Type: GO = PRE/POST/REVIEW from /go; Type: DO = single-segment from /do)
    └── review_reports/            # /full-review outputs (one file per run)

Files marked ★ are the active surfaces every skill touches every day; the rest of ai_context/ is read-once-per-session memory the AI relies on for cross-session continuity.

---

🛠️ Skills & Commands

holo ships two distinct entry kinds. Commands use the /holo: prefix and operate on the plugin itself. Skills are invoked by bare name and run inside your project. Full documentation for each entry lives in its source file under commands/ or skills/.

Skills

Workflow — the daily plan-to-ship pipeline:

Skill	Purpose
/plan	Lock the current message into discuss-only mode.
/do	Lightweight in-place edits for simple, small-scope changes.
/go	Full-flow plan-to-ship ceremony for multi-file changes or anything touching docs/ / ai_context/.
/commit	Drive-by commit of the current working tree, with safety-net checks.
/push	Fast-forward push the current branch to its remote.
/forward	Merge the current branch into one or more sibling branches.
/todo-add	Register a just-decided item into docs/todo_list.md.
/update-docs	Land conversation narrative into ai_context/ + docs/ files.
/compress-ai-context	Prune stale + compress bloated entries across ai_context/ (sentinel-aware, coordinator + scatter-gather, snapshot-on-plan-freeze, multi-axis verify + rollback ask).
/save-chat	Save the current (or a chosen slice of the) conversation to logs/chats/ as a self-contained HTML.

Review — audit your work:

Skill	Purpose
/post-check	Re-validate the last /go against its PRE log.
/full-review	Whole-repo alignment audit (multi-agent).
/check-review	Re-validate a stored review report against current state.
/fix	Triage findings from /post-check / /full-review / /check-review into fix / todo / skip buckets; delegate fixes to /go or /do.

Inventory — read-only views:

Skill	Purpose
/todo-check	Render the docs/todo_list.md index.
/branch-inventory	Group all local + remote branches by lifecycle bucket.
/recent-activity	Reverse-chronological timeline of recent project activity.
/monitor	Periodic progress report for declared background processes.
/run-prompt	Load a prompt file and execute its body as the current task.

Visualization — diagram generation:

Skill	Purpose
draw-diagram	Draw polished diagrams — flowcharts, pipeline / process, agentic-loop, state-machine (dark / light / mono-print themes; SVG / PNG / HTML outputs).

draw-diagram is also published as a standalone plugin — for full details see holo-diagram.

Commands

Command	Purpose
/holo:init	Materialize the project skeleton into the current directory.
/holo:update	Surface structural drift introduced by a plugin upgrade.

---

🤖 Engineering Loop

Three interlocking pipelines drive the daily cadence — planning what to do next, implementing a single change, and reviewing after a batch lands.

(a) Planning pipeline

Decide what to do next, or retire ideas that won't make the cut:

/plan and /todo-add form a tight loop — each round of discussion becomes a queue entry that iterates or finalizes for /go; abandoned ideas archive. /update-docs lands narrative bound for ai_context/ or docs/ instead of the queue.

(b) Implementation pipeline

Land a single change from queue to remote:

/go lands a finalized entry (logging + archiving it), /post-check verifies, and /fix triages any findings; /forward optionally syncs sibling branches before /push.

(c) Review pipeline

After several commits accumulate, audit the whole repo at once:

/full-review runs multi-agent scans into review_reports/; /check-review re-validates each finding — real ones flow through /fix → /commit, stale ones pass. Run it before pushing major work.

Walkthrough

A minimal sequence following the implementation pipeline:

1. /plan                            # discuss the change, no writes
2. /todo-add                        # record the decision into todo_list
3. /go                              # land: edits + cross-file review + commit
4. /post-check                      # verify the result against the PRE log
5. /fix                             # triage findings; delegate to /go or /do
6. /push                            # fast-forward push current branch

For small drive-by edits, skip /plan and /go — edit, then /commit && /push. /commit verifies tracking state and writes a properly-formatted commit, but without the full land ceremony.

---

⚙️ Configuration

Most skills read ai_context/skills_config.md in your project for per-project anchors. Missing required header → loud fail. (none) body → graceful skip of the related step. /holo:init materializes a starter skills_config.md with every header present and (none) bodies, ready to fill in.

Section	Used by	Purpose
## Background processes	/commit, /go, /monitor, /branch-inventory	pgrep patterns + artifact / log paths so skills detect in-flight long-running jobs on this branch / worktree.
## Protected branch prefixes	/commit, /go, /forward, /branch-inventory	Branch-name prefixes that must not be auto-forwarded or auto-merged.
## Main branch policy	/commit, /go, /branch-inventory	Main branch name + invariants on what may live there.
## Do-not-commit paths	/commit, /go	Project-specific paths that must never be committed, on top of .gitignore.
## Source directories	/full-review, /post-check	Directories holding code — scope for review scans.
## Data contract directories	/full-review, /post-check, /go	Schema / Protobuf / OpenAPI / Pydantic / SQL DDL directories — scope for contract validation.
## Example artifact directories	/full-review, /post-check	Sample-output / fixture directories — scope for example-vs-spec scans.
## Core component keywords	/full-review	Architectural keywords used in component-alignment audits.
## Sensitive content placeholder rules	/go, /post-check	Real-world content that must be replaced by structural placeholders in written artifacts.
## Timezone	every skill that writes a timestamp	Command template producing YYYY-MM-DD_HHMMSS. The section body documents a system-tz date fallback (declared once so skills do not encode bespoke try/except).
## Language	every skill that writes output or asks the user a question	Two independent axes: content_language (disk-bound output) and conversation_language (AI ↔ user turns).
## Activity sources	/recent-activity, /todo-add, /go, /post-check, /full-review, /check-review, /run-prompt	Paths + filename patterns + per-entry field names for change logs / todo list / archived todo / review reports / prompt sources.

Each section's body in the generated skills_config.md carries inline documentation of the contract for that section — including the exceptions to the fail-loud rule (## Timezone declares a system-tz fallback; scripts/session_branch_check.sh degrades gracefully when the section is missing, since it runs before any /holo:init).

---

📄 License

See LICENSE.