holoctl-foreign-bootstrap

name	holoctl-foreign-bootstrap
description	| Use when this capability is needed.

Bootstrap a non-Claude assistant from a holoctl workspace

This repo is managed by holoctl. The canonical source of truth lives in .holoctl/ — it is tool-neutral. holoctl's CLI (hctl, on PATH) compiles that source into Claude Code's native files only (CLAUDE.md, .claude/).

If you are Claude Code, ignore this skill — your config is already in .claude/.

If you are any other assistant, you have no compiler maintained for you. Instead, do the translation yourself: read .holoctl/ and write the equivalent into your own tool's native config location. Read .holoctl/ as the source — NOT .claude/ (that one is already shaped for Claude).

Step 1 — read the canonical source

Read these, in order, skipping any that don't exist:

1. .holoctl/instructions.md — the project's primary agent instructions (objective, architecture, conventions, merged).
2. .holoctl/context/*.md — objective.md, architecture.md, conventions.md and any documents/.
3. .holoctl/agents/*.md — active personas (each has name / description / tools / paths frontmatter).
4. .holoctl/memory/MEMORY.md — always-on durable memory index, plus .holoctl/memory/topics/*.md (each topic has a scope: of always_on / lazy / glob).
5. .holoctl/commands/*.md — reusable slash-command-style workflows.

Step 2 — materialize into your native config dir

Write the content into the location your tool reads. Pick your row:

Your tool	Where to write
GitHub Copilot	.github/copilot-instructions.md (from instructions.md) + .github/prompts/<name>.prompt.md (one per command) + .github/instructions/holoctl-memory-<topic>.instructions.md with applyTo: (one per glob/always_on topic)
OpenAI Codex	.codex/AGENTS.override.md (instructions + inlined memory index + persona list) + .codex/config.toml ([mcp_servers.holoctl])
Cursor	.cursor/rules/*.mdc (instructions + per-glob memory as scoped rules)
Aider / Zed / Junie / goose / other AGENTS.md-aware	the root AGENTS.md already carries the pointer; inline the instructions there if your tool needs more
anything else	follow your tool's documented "project instructions" convention, using .holoctl/instructions.md as the body

For exact frontmatter and MCP-server snippets per tool, see Per-tool format hints — in references/format-hints.md, or appended at the end of this file (if you're reading .holoctl/foreign-bootstrap.md).

Step 3 — record what you generated (drift guard)

Claude Code gets a hand-edit guard for free (holoctl tracks every file it emits in .holoctl/.compiled.json and refuses to clobber a hand-edited output). Give yourself the SAME protection: after writing your native files, record their hashes in a manifest at .holoctl/.foreign-compiled.json.

Format (one entry per file you generated; sha256 is the hex SHA-256 of the file's UTF-8 bytes exactly as written):

{
  "version": 1,
  "generated": "<UTC ISO-8601, e.g. 2026-06-09T12:00:00Z>",
  "tool": "<your tool name, e.g. copilot / codex / cursor>",
  "files": {
    ".github/copilot-instructions.md": { "sha256": "<hex digest>" },
    ".github/prompts/status.prompt.md": { "sha256": "<hex digest>" }
  }
}

Write this manifest every time you (re-)bootstrap, recording the files you just produced. It is the foreign-assistant equivalent of .holoctl/.compiled.json.

Step 4 — on re-bootstrap, WARN before overwriting a hand-edit

When you re-run this bootstrap (after hctl upgrade or any .holoctl/ change):

1. Load the previous .holoctl/.foreign-compiled.json (if it exists).
2. For each file you are about to (re)generate, compute the on-disk file's current SHA-256 and compare it to the sha256 recorded in that manifest.
3. If the on-disk hash DIFFERS from the recorded hash, the file was hand-edited since you last generated it. Do NOT silently overwrite it. WARN the user first — name the file, say it diverged from the last generated version, and ask whether to overwrite (losing the hand-edit) or skip it. Treat a missing manifest entry as "not previously generated by me" and write normally.
4. After resolving each file, refresh the manifest with the new hashes (Step 3).

This mirrors Claude Code's behavior: holoctl preserves hand-edited .claude/ outputs rather than clobbering them. Foreign-generated files deserve the same respect.

Step 5 — wire up the holoctl MCP server (optional but recommended)

holoctl ships a stdio MCP server (hctl serve --mcp) exposing board / memory / journal / curator tools. If your tool supports MCP, register it in your native MCP config with:

command = "hctl"   (or $HOLOCTL_BIN if hctl isn't on PATH)
args    = ["serve", "--mcp"]

If your tool doesn't speak MCP, the hctl CLI is the full fallback — every MCP tool maps 1:1 to an hctl subcommand.

Hard rules (never violate)

• Never edit .holoctl/board/index.json or .holoctl/memory/MEMORY.md by hand — they are derived. Use hctl <subcommand> (e.g. hctl board add, hctl memory add).
• Never read .holoctl/board/tickets/<ID>-*.md directly — use hctl board show <ID>.
• Treat the files you generate (.github/…, .codex/…, .cursor/…) as derived. Re-run this bootstrap after hctl upgrade (or whenever .holoctl/ changes) to keep them in sync. Don't hand-edit them — change .holoctl/ and regenerate.
• Always record what you generate in .holoctl/.foreign-compiled.json (Step 3) and, on re-bootstrap, WARN before overwriting any generated file whose on-disk hash differs from the recorded one (Step 4) — that divergence means a hand-edit you must not silently destroy.
• If hctl returns an error, read the literal error, report it, and stop.

---

Source: FelipeCarillo/holoctl — distributed by TomeVault.