# Felipecarillo Holoctl Holoctl Foreign Bootstrap > Bootstrap a non-Claude assistant from a holoctl workspace - Skill: `tomevault-io/felipecarillo-holoctl-holoctl-foreign-bootstrap` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/felipecarillo-holoctl-holoctl-foreign-bootstrap` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/felipecarillo-holoctl-holoctl-foreign-bootstrap/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/felipecarillo-holoctl-holoctl-foreign-bootstrap --- # 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/.prompt.md` (one per command) + `.github/instructions/holoctl-memory-.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): ```json { "version": 1, "generated": "", "tool": "", "files": { ".github/copilot-instructions.md": { "sha256": "" }, ".github/prompts/status.prompt.md": { "sha256": "" } } } ``` 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 ` (e.g. `hctl board add`, `hctl memory add`). - **Never** read `.holoctl/board/tickets/-*.md` directly — use `hctl board show `. - 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](https://github.com/FelipeCarillo/holoctl) — distributed by [TomeVault](https://tomevault.io).