{"id":49986236,"url":"https://github.com/felipecarillo/holoctl","last_synced_at":"2026-06-16T17:00:55.496Z","repository":{"id":355726347,"uuid":"1229330187","full_name":"FelipeCarillo/holoctl","owner":"FelipeCarillo","description":"Project structure for AI coding agents — kanban board, named agents, slash commands, decisions log, live dashboard. Versioned in .holoctl/ next to your code. Compiles to Claude Code, Cursor, Windsurf, GitHub Copilot, Devin, Aider.","archived":false,"fork":false,"pushed_at":"2026-06-09T19:52:19.000Z","size":1431,"stargazers_count":1,"open_issues_count":5,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-09T20:08:51.389Z","etag":null,"topics":["agent-orchestration","agents","ai","ai-agents","aider","claude-code","claude-code-skill","cli","copilot","cursor","developer-tools","devin","dossier","holoctl","kanban","project-management","windsurf"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/holoctl/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/FelipeCarillo.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-04T23:54:45.000Z","updated_at":"2026-05-29T17:52:34.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/FelipeCarillo/holoctl","commit_stats":null,"previous_names":["felipecarillo/projctl","felipecarillo/holoctl"],"tags_count":21,"template":false,"template_full_name":null,"purl":"pkg:github/FelipeCarillo/holoctl","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FelipeCarillo%2Fholoctl","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FelipeCarillo%2Fholoctl/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FelipeCarillo%2Fholoctl/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FelipeCarillo%2Fholoctl/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/FelipeCarillo","download_url":"https://codeload.github.com/FelipeCarillo/holoctl/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FelipeCarillo%2Fholoctl/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34415248,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-16T02:00:06.860Z","response_time":126,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-orchestration","agents","ai","ai-agents","aider","claude-code","claude-code-skill","cli","copilot","cursor","developer-tools","devin","dossier","holoctl","kanban","project-management","windsurf"],"created_at":"2026-05-18T23:06:16.036Z","updated_at":"2026-06-16T17:00:55.477Z","avatar_url":"https://github.com/FelipeCarillo.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# holoctl\n\n\u003e **A living project operating system for Claude Code.** One source of truth in `.holoctl/`, compiled into Claude Code's native config (`CLAUDE.md`, `.claude/`). Every other assistant (Copilot, Codex, Cursor, Aider, Zed, Junie, …) self-configures from the same source via a portable **bootstrap skill** — holoctl emits a minimal `AGENTS.md` that points it there. Durable memory, autonomous curator, MCP server, web dashboard — all version-controlled next to your code.\n\n\u003cp align=\"center\"\u003e\n  🇺🇸 \u003ca href=\"README.md\"\u003eEnglish\u003c/a\u003e |\n  🇧🇷 \u003ca href=\"docs/README.pt-br.md\"\u003ePortuguês\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://pypi.org/project/holoctl/\"\u003e\u003cimg src=\"https://img.shields.io/pypi/v/holoctl?color=blue\" alt=\"PyPI\"/\u003e\u003c/a\u003e\n  \u003ca href=\"https://pypi.org/project/holoctl/\"\u003e\u003cimg src=\"https://img.shields.io/pypi/dm/holoctl?color=blue\u0026label=downloads\" alt=\"Downloads\"/\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/FelipeCarillo/holoctl/actions/workflows/ci.yml\"\u003e\u003cimg src=\"https://github.com/FelipeCarillo/holoctl/actions/workflows/ci.yml/badge.svg\" alt=\"CI\"/\u003e\u003c/a\u003e\n  \u003ca href=\"LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/badge/license-MIT-yellow\" alt=\"MIT\"/\u003e\u003c/a\u003e\n  \u003ca href=\"https://www.python.org\"\u003e\u003cimg src=\"https://img.shields.io/badge/python-≥3.11-brightgreen\" alt=\"Python\"/\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n---\n\n## TL;DR — three commands\n\n```bash\n# 1. Install (pick one — see \"Installation\" if `hctl` is not on PATH)\nuv tool install holoctl                      # recommended\n# or:  pipx install holoctl\n# or:  pip install holoctl                   # ⚠️ requires an active venv (see below)\n\n# 2. Plant the global router (once per machine)\nhctl setup-global --target claude            # Claude Code\n# (Other assistants pick up the per-project AGENTS.md shim emitted by `hctl init`,\n#  which points them at the holoctl-foreign-bootstrap skill.)\n\n# 3. Initialize a project\ncd ~/my-project \u0026\u0026 hctl init\n```\n\nOpen Claude Code (or any supported assistant) in `~/my-project` and type `/holoctl`. The agent reads the workspace, runs discovery, suggests specialist personas, populates context, and shows the overview — autonomously.\n\n---\n\n## Table of contents\n\n1. [Why holoctl](#why-holoctl)\n2. [Anatomy of `.holoctl/`](#anatomy-of-holoctl)\n3. [Installation](#installation) — including the **`pip` venv gotcha**\n4. [Per-machine global setup](#per-machine-global-setup)\n5. [Per-project initialization](#per-project-initialization)\n6. [The `/holoctl` slash command — what it actually does](#the-holoctl-slash-command)\n7. [Compilation](#compilation)\n8. [MCP vs CLI — design choice](#mcp-vs-cli)\n9. [Daily workflows](#daily-workflows)\n10. [Command reference](#command-reference)\n11. [Configuration](#configuration)\n12. [Lifecycle hooks](#lifecycle-hooks)\n13. [Per-assistant guide](#per-assistant-guide) — Claude / everything else (foreign-bootstrap)\n14. [Coverage and doctor](#coverage-and-doctor)\n15. [Privacy \u0026 coexistence](#privacy--coexistence)\n16. [Troubleshooting](#troubleshooting)\n17. [FAQ](#faq)\n18. [Migration from projctl / projhub](#migration-from-projctl--projhub)\n19. [Roadmap](#roadmap)\n20. [Documentation \u0026 license](#documentation--license)\n\n---\n\n## Why holoctl\n\nClaude Code's native primitives — skills, subagents, hooks, settings, lazy-loaded memory — are powerful but scattered across `.claude/` and easy to let rot between sessions. holoctl gives them **one source of truth** in `.holoctl/`, version-controlled next to your code, and compiles it into the right `.claude/` shapes on demand.\n\nYou write project context **once** in `.holoctl/`; `hctl compile` materializes Claude Code's native files. Plus a CLI, a Kanban board, a memory layer that survives across sessions, an event journal, an autonomous curator that proposes structural improvements, an MCP server, and a web dashboard — all built around the same source of truth.\n\n**Not on Claude Code?** holoctl maintains a deep compiler only for Claude. Every other assistant self-configures from the *same* `.holoctl/` source via the portable **`holoctl-foreign-bootstrap` skill**: holoctl emits a minimal `AGENTS.md` (the cross-tool convention) pointing the assistant at `.holoctl/foreign-bootstrap.md`, which teaches it to read `.holoctl/` and generate its own native config dir. The per-tool translation lives in one skill the assistant runs at runtime — not in N Python compilers holoctl has to keep in lockstep.\n\n**It's \"living\" because it wakes up between sessions:**\n\n- **Durable memory** at `.holoctl/memory/` — compiled into Claude as skills (always-on index + lazy/glob topics); foreign assistants read the same tree directly via the bootstrap skill.\n- **Event journal** captures every tool use, edit, and session boundary via hooks plumbed automatically.\n- **Autonomous curator** watches the journal and proposes new personas, path-scoped rules, or topic archives as `meta:curate` tickets on the board. Approve a suggestion by moving the ticket to `done` — it auto-executes.\n- **Token-economy boot** prints ≤1KB of session-zero context (top pendings, recent decisions, available topics) so the assistant doesn't burn tokens loading the whole `CLAUDE.md`.\n- **MCP server** exposes board / memory / journal / curator as standard tools (with per-tool permission gating in Claude Code).\n\n---\n\n## Anatomy of `.holoctl/`\n\n```\nyour-project/\n├── .holoctl/                       ← single source of truth, committed to git\n│   ├── config.json                 ← project name, prefix, board statuses, targets\n│   ├── instructions.md             ← compiled to CLAUDE.md (Claude); read directly by foreign assistants\n│   │\n│   ├── board/                      ← Kanban + tickets\n│   │   ├── WORKFLOW.md             ← state machine doc (template-managed)\n│   │   ├── index.json              ← auto-rebuilt projection of tickets/*.md\n│   │   └── tickets/PRJ-001-*.md    ← each ticket = one Markdown file with frontmatter\n│   │\n│   ├── agents/                     ← active personas (only `boardmaster` after `hctl init`)\n│   │   └── boardmaster.md          ← library (developer / reviewer / architect / researcher / dba / devops / security-auditor / tech-writer / agent-designer) added on demand, or design a new one with `/agent-new`\n│   │\n│   ├── commands/                   ← /board, /ticket, /spec, /sprint, /close, /decision, /status, /agent-new\n│   │\n│   ├── context/                    ← project-level prose\n│   │   ├── objective.md            ← What / Why / Success criteria\n│   │   ├── architecture.md         ← Tech stack / Structure / Patterns / Boundaries\n│   │   ├── conventions.md          ← Code style, naming, testing\n│   │   ├── decisions/              ← ADR-style hard locks\n│   │   └── documents/              ← free-form supporting docs\n│   │\n│   ├── memory/                     ← durable cross-assistant notes\n│   │   ├── MEMORY.md               ← always-on index\n│   │   ├── .gitignore              ← excludes `_archived/` by default\n│   │   └── topics/                 ← lazy / glob / always_on topics\n│   │\n│   ├── journal/                    ← daily JSONL of session events\n│   │   └── 2026-05-08.jsonl\n│   │\n│   ├── curator/                    ← curator state + per-ticket metadata\n│   │\n│   ├── hooks/                      ← (optional) declarative hooks per lifecycle event\n│   ├── rules/                      ← (optional) path-scoped rules with `paths:` frontmatter\n│   ├── skills/                     ← (optional) custom skills with progressive disclosure\n│   ├── output_styles/              ← (optional) Claude-specific output styles\n│   ├── ignore                      ← (optional) gitignore-style for assistant-specific ignore lists\n│   │\n│   └── activity.jsonl              ← raw activity log (low-level)\n│\n├── …your code\n│\n└── (compiled outputs)\n    ├── CLAUDE.md                   ← Claude Code instructions (usually .gitignored)\n    ├── .claude/                    ← Claude Code agents / commands / skills / settings.json\n    ├── AGENTS.md                   ← minimal discovery shim → points non-Claude tools at the bootstrap\n    └── .holoctl/foreign-bootstrap.md ← bootstrap procedure for non-Claude assistants\n```\n\n\u003e **Non-Claude assistants** generate their own native config (`.github/`, `.codex/`, `.cursor/`, …) by following `.holoctl/foreign-bootstrap.md` — holoctl does not emit those directories itself.\n\n\u003e **Optional folders** (`hooks/`, `rules/`, `skills/`, `output_styles/`, `ignore`) are **not created by `hctl init`**. They're opt-in surfaces you create when you need them. Compilers only emit what exists in the source — empty input produces empty output (anti-overengineering).\n\n---\n\n## Installation\n\n**Requires Python ≥ 3.11.**\n\n### Option A — `uv tool` *(recommended)*\n\n```bash\nuv tool install holoctl\nhctl --version\n```\n\n`uv tool` creates an isolated venv automatically and puts `hctl` on your PATH. **Nothing else needed.**\n\n### Option B — `pipx`\n\n```bash\npipx install holoctl\nhctl --version\n```\n\nSame isolation as `uv tool`. Requires `pipx` (`pip install pipx \u0026\u0026 pipx ensurepath`).\n\n### Option C — `pip` *(⚠️ requires an active venv)*\n\n\u003e **`pip install holoctl` from a \"naked\" Python on a modern OS will fail with `error: externally-managed-environment` (PEP 668), or — if you bypass that — install into the system Python and `hctl` may end up in a directory not on your PATH.**\n\nThe reliable way is to create a venv **specifically for holoctl** and activate it before running `hctl`:\n\n```bash\n# Linux / macOS\npython3 -m venv ~/.venvs/holoctl\nsource ~/.venvs/holoctl/bin/activate\npip install holoctl\nhctl --version\n\n# Windows (PowerShell)\npython -m venv $HOME\\.venvs\\holoctl\n\u0026 $HOME\\.venvs\\holoctl\\Scripts\\Activate.ps1\npip install holoctl\nhctl --version\n\n# Windows (cmd.exe)\npython -m venv %USERPROFILE%\\.venvs\\holoctl\n%USERPROFILE%\\.venvs\\holoctl\\Scripts\\activate.bat\npip install holoctl\nhctl --version\n```\n\n**Caveat with venv-based pip install:** `hctl` only works **while the venv is activated**. To make it always available, add a wrapper:\n\n```bash\n# Linux/macOS — add to ~/.bashrc or ~/.zshrc\nalias hctl=\"$HOME/.venvs/holoctl/bin/hctl\"\n```\n\n```powershell\n# Windows — add to $PROFILE\nfunction hctl { \u0026 \"$HOME\\.venvs\\holoctl\\Scripts\\hctl.EXE\" $args }\n```\n\nThis is exactly the kind of friction that `uv tool` and `pipx` avoid. **If you have any choice, use one of those.**\n\n### Optional ML extra\n\n```bash\nuv tool install \"holoctl[ml]\"        # ~250MB — adds ONNX paraphrase detection to the curator\n```\n\n### Verifying the install\n\n```bash\nhctl --version              # 0.20.3 or newer\nhctl --help                 # full command list\nhctl doctor --global        # checks ~/.claude router install (will report 'missing' until step 2)\n```\n\n---\n\n## Per-machine global setup\n\n`hctl setup-global` plants the **`/holoctl` router** in each AI tool's user-level config, so the slash command works in any folder — even before `hctl init`.\n\n```bash\nhctl setup-global --target claude           # Claude Code (the only supported target)\nhctl setup-global --target claude --dry-run # preview without writing\n```\n\nWhat gets installed:\n\n| Tool        | File                                                | Format                                | Idempotent block |\n|-------------|-----------------------------------------------------|---------------------------------------|------------------|\n| Claude Code | `~/.claude/commands/holoctl.md` + `~/.claude/skills/holoctl-router/` | Slash command + skill with references | replaces files   |\n\nEvery other assistant (Copilot, Codex, Aider, Zed, Junie, Jules, Factory, goose, …) picks up the per-project `AGENTS.md` discovery shim emitted by `hctl compile --target agents`, which points it at the `holoctl-foreign-bootstrap` skill. None of them expose a documented user-level surface for slash routers, so `setup-global` only targets Claude.\n\n**Detecting drift:**\n\n```bash\nhctl doctor --global\n```\n\nOutput:\n\n```\nholoctl: global-check\n  ✓ Claude         router up-to-date (~/.claude/commands/holoctl.md)\n\n  Global router up-to-date.\n```\n\n---\n\n## Per-project initialization\n\nInside a project folder:\n\n```bash\ncd ~/my-project\nhctl init\n```\n\nWhat `init` does, in order:\n\n1. Creates `.holoctl/` structure (board, agents, commands, context, memory, journal).\n2. Writes `config.json` with inferred project name (= `cwd.name`), prefix (= initials), and the shipped **provider catalog** (Linear / GitHub / Trello / Azure DevOps / Jira / Slack — URL patterns mapped to MCP fetch tools).\n3. Seeds `boardmaster.md` (the only mandatory persona — owns ticket lifecycle). All other personas (developer / reviewer / architect / researcher / dba / devops / security-auditor / tech-writer / agent-designer) stay latent in the library until `hctl agent add \u003cname\u003e` or `/agent-new` activates them.\n4. Seeds `instructions.md`, `WORKFLOW.md`, ticket `_template.md`, and eight default commands (`/status`, `/ticket`, `/spec`, `/board`, `/sprint`, `/decision`, `/close`, `/agent-new`).\n5. Plants Claude lifecycle hooks (`SessionStart` → `hctl boot`, `Stop` → `hctl handoff`, deny-list for derived files) and built-in reactive skills (`holoctl-router`, `holoctl-spec-flow`, `holoctl-provider-mcp`, `holoctl-work-item-router`, `holoctl-persona-suggester`, `holoctl-ticket-discipline`, `holoctl-memory-discipline`, `holoctl-parallel-evaluator`).\n6. Writes MCP server config (`.claude/settings.json:mcpServers.holoctl`).\n7. Compiles default targets (`agents` + `claude`).\n\n**Flags:**\n\n```bash\nhctl init --name \"My Project\" --prefix \"MP\"           # explicit\nhctl init --targets agents,claude                    # custom target set (these are the only two)\nhctl init --bare                                       # skeleton only — skip compile/hooks/MCP\nhctl init --skip-compile                               # init but don't compile yet\n```\n\nRe-running `hctl init` in an already-initialized workspace is **idempotent** — it re-syncs template-managed files (`commands/*.md`, `WORKFLOW.md`, `_template.md`, `boardmaster.md`) without touching user-owned files (tickets, hand-edited agents, context docs, custom rules/skills/hooks).\n\nIf you upgrade `holoctl` after `init`, run:\n\n```bash\nhctl upgrade --check     # show CHANGELOG slice\nhctl upgrade             # apply migrations + recompile\n```\n\n---\n\n## The `/holoctl` slash command\n\nThis is the **routing brain**. After steps 2 + 3 above, type `/holoctl` (or invoke the equivalent skill) in any assistant. The agent runs:\n\n```text\nhctl doctor\n```\n\nThe first line of output is router-friendly — one of:\n\n| First line                        | Flow      | What the agent does next                                                            |\n|-----------------------------------|-----------|-------------------------------------------------------------------------------------|\n| `holoctl: not initialized`        | Flow A    | `hctl init` → discover codebase → suggest personas → seed memory → `hctl overview`  |\n| `holoctl: outdated`               | Flow B    | `hctl upgrade --check`, ask for confirmation, then `hctl upgrade` + `hctl boot`     |\n| `holoctl: ok`                     | Flow C    | `hctl boot` (≤1KB teaser), react to pending tickets / curator suggestions          |\n\n**Flow A in detail** (the most important one — first time in a project):\n\n1. **Detect.** `hctl doctor` returns `not initialized`.\n2. **Init.** `hctl init --name \"\u003cinferred\u003e\" --prefix \"\u003cPRX\u003e\"`.\n3. **Discover.** Reads in parallel: README, package files (`package.json`, `pyproject.toml`, `Cargo.toml`, `go.mod`, …), top-level dirs, lint configs, existing AI configs (read-only — never overwrites).\n4. **Configure.**\n   - Sub-repos: if multiple sub-projects detected, **one aggregated question** (\"Found backend/, frontend/, mobile/. Register all?\"), then `hctl repo add` for each approved.\n   - Context files: writes `.holoctl/context/{objective,architecture,conventions}.md` and `.holoctl/instructions.md` directly from what was read. No per-file confirmation.\n   - Ambiguity escape: if README is generic/missing, **one question** to clarify objective. Otherwise no questions.\n5. **Suggest personas.** `hctl agent suggest` maps detected stack → personas from the expanded library (developer / reviewer / architect / researcher / dba / devops / security-auditor / tech-writer / agent-designer). Examples: SQL + `migrations/` → `dba`; `.github/workflows/` + `Dockerfile` + Terraform → `devops`; `docs/` with many `.md` → `tech-writer`. When no library entry fits the repo, `/agent-new \u003cname\u003e` invokes `agent-designer` to draft a persona tailored to your stack.\n6. **Memory seed.** Creates `.holoctl/memory/topics/project-overview.md` with a 3-5 line paragraph derived from README + package files. This is what `hctl boot` reads in session 2 so the agent \"wakes up\" knowing what the project is.\n7. **Overview \u0026 next action.** Runs `hctl overview` (canonical snapshot) and `hctl boot` (teaser). Reacts: proposes creating the first ticket, or surfaces curator suggestions, or points to next p1.\n\n**Total time**: ~30 seconds, with 1-2 questions in the path.\n\n---\n\n## Compilation\n\n`hctl compile` reads `.holoctl/` and emits Claude Code's native files, plus the cross-tool discovery shim. Two targets:\n\n```bash\nhctl compile --target claude              # CLAUDE.md + .claude/ (agents, commands, skills, settings.json)\nhctl compile --target agents              # minimal AGENTS.md shim + .holoctl/foreign-bootstrap.md\nhctl compile                              # both (config.targets[] defaults to [\"agents\", \"claude\"])\n```\n\n**The `claude` target** is the deep one — it materializes Claude Code's full native config from `.holoctl/`.\n\n**The `agents` target** emits a *minimal* `AGENTS.md` at the repo root (the [agents.md](https://agents.md/) cross-tool convention) plus `.holoctl/foreign-bootstrap.md`. The `AGENTS.md` no longer mirrors your project content — it's a **discovery shim** that points any non-Claude assistant at the bootstrap procedure. Keep `agents` in your `targets` (the default does) so foreign tools can find their way in.\n\n**Other assistants** (Copilot, Codex, Cursor, Aider, Zed, …) are **not** compiled by holoctl. They self-configure by following `.holoctl/foreign-bootstrap.md`, which teaches them to read `.holoctl/` and generate their own native config dir. See [Per-assistant guide](#per-assistant-guide).\n\n**Coverage matrix** — what each compiler emits from each `.holoctl/` source:\n\n| `.holoctl/` source            | claude                            | agents                              |\n|-------------------------------|-----------------------------------|-------------------------------------|\n| `instructions.md`             | `CLAUDE.md`                       | — (read directly via bootstrap)     |\n| `agents/*.md`                 | `.claude/agents/\u003cn\u003e.md`           | —                                   |\n| `commands/*.md`               | `.claude/commands/\u003cn\u003e.md`         | —                                   |\n| `context/*.md`                | (via instructions/memory)         | —                                   |\n| `memory/topics/*.md`          | `.claude/skills/holoctl-mem-*`    | —                                   |\n| `hooks/*.json` *(opt)*        | `.claude/settings.json` merge     | —                                   |\n| `rules/*.md` *(opt)*          | `.claude/rules/\u003cn\u003e.md`            | —                                   |\n| `skills/\u003cn\u003e/SKILL.md` *(opt)* | `.claude/skills/\u003cn\u003e/...`          | —                                   |\n| `output_styles/*.md` *(opt)*  | `.claude/output_styles/`          | —                                   |\n| MCP servers (config)          | `.claude/settings.json:mcp`       | —                                   |\n| *(discovery shim)*            | —                                 | `AGENTS.md` + `.holoctl/foreign-bootstrap.md` |\n\n\u003e See `hctl coverage` for a live, workspace-specific version of this table.\n\n---\n\n## MCP vs CLI\n\n### Current design: skills and agents prefer MCP, fall back to CLI / paste\n\nSlash commands, agents, and reactive skills **prefer the MCP server when it's running**, falling back to `hctl` CLI (or paste, for external content) when not. Examples:\n\n- Boardmaster calls `mcp__holoctl__board_create({...})` first; CLI `hctl board add '\u003cjson\u003e'` is the documented fallback.\n- `/spec` invokes the `holoctl-provider-mcp` skill to fetch an external card body via the provider's MCP (Linear / GitHub / Trello / Azure DevOps / Jira / Slack — or a custom internal board registered via `hctl provider add`); paste is the fallback, with `source_*` preserved either way. The MCP server is auto-spawned by Claude (via `.claude/settings.json:mcpServers`). Non-Claude assistants wire it into their own MCP config as part of the `holoctl-foreign-bootstrap` step.\n- `/agent-new` calls `mcp__holoctl__agent_create` to materialize a designed persona; manual `.md` editing remains the escape hatch.\n- The `/holoctl` router still runs `hctl doctor` / `hctl init` / `hctl boot` over the shell — these don't have MCP equivalents because they bootstrap or terminate the assistant session itself.\n\nThe CLI remains the **source of truth** — every MCP tool maps 1:1 to a `hctl` subcommand — but MCP is the preferred path inside the assistant's loop because of finer permission gating, in-process speed after handshake, and structured JSON output that chains naturally.\n\n### The MCP server\n\n`hctl init` writes the MCP config so each assistant can spawn `hctl serve --mcp` on demand. The server exposes **25 tools**:\n\n| Read tools (auto-approved)       | Write tools (`permissions.ask`)   |\n|----------------------------------|-----------------------------------|\n| `holoctl.board_list`             | `holoctl.board_create`            |\n| `holoctl.board_children`         | `holoctl.board_batch`             |\n| `holoctl.board_get`              | `holoctl.board_move`              |\n| `holoctl.board_show`             | `holoctl.board_set`               |\n| `holoctl.memory_list_topics`     | `holoctl.board_ack`               |\n| `holoctl.memory_read_topic`      | `holoctl.board_note`              |\n| `holoctl.memory_search`          | `holoctl.board_delete`            |\n| `holoctl.journal_recent`         | `holoctl.board_batch_move`        |\n| `holoctl.agent_list_available`   | `holoctl.board_batch_set`         |\n| `holoctl.curate_suggestions`     | `holoctl.board_batch_delete`      |\n| `holoctl.config_show`            | `holoctl.memory_add`              |\n|                                  | `holoctl.agent_add`               |\n|                                  | `holoctl.agent_create`            |\n|                                  | `holoctl.curate_silence`          |\n\n`holoctl.config_show` is what the `holoctl-provider-mcp` skill reads to discover the provider catalog at runtime — no hardcoded URL list inside the skill.\n\n### MCP-preferred trade-offs\n\n| Concern           | CLI                                                  | MCP                                                          |\n|-------------------|------------------------------------------------------|--------------------------------------------------------------|\n| Universality      | Runs in any terminal, any agent, any shell.         | Requires MCP-aware client.                                   |\n| Reproducibility   | Human can re-run the exact same command.            | Tool calls are JSON-RPC, less human-friendly to replay.      |\n| Speed             | Fork of Python (~80-150ms cold).                    | In-process after handshake (faster after first call).        |\n| Permission gating | Coarse — relies on shell allow-lists.               | **Fine-grained** — per-tool, write-tools land in `ask`.      |\n| Output            | Rich text formatted for humans.                     | Structured JSON for machines/chains.                         |\n\nThe CLI is **always** the fallback. If the MCP server is down (or never started), the assistant uses `hctl` directly and everything still works — including from a plain terminal with no AI tool at all.\n\n---\n\n## Daily workflows\n\n### Spec-Driven Development (`/spec`)\n\nTurn an external card or a multi-paragraph brief into a structured **spec** in `.holoctl/`, then automatically decompose it into parallel-safe child tasks.\n\n```text\n/spec https://linear.app/eng/issue/ENG-42\n```\n\nWhat happens:\n\n1. **Provider MCP discovery.** The `holoctl-provider-mcp` skill matches the URL against the configured provider catalog (`hctl provider list`). If the Linear MCP is connected (`.mcp.json`), it fetches the card body directly. If not, it falls back to \"paste the body here\" — with `source_provider`, `source_ref`, `source_url`, `source_label` preserved either way.\n2. **Discuss.** One batched question to refine scope, acceptance criteria, files touched, edge cases. Skips when the source content is already explicit.\n3. **Materialize spec.** `mcp__holoctl__board_create({kind: \"spec\", source_*, acceptance, context, ...})`.\n4. **Decompose.** `holoctl-parallel-evaluator` splits the work into disjoint child tasks; boardmaster calls `mcp__holoctl__board_batch({shared: {parent: SPEC_ID, source_*, ...}, tickets: [...]})`. The CLI rejects the batch if any two children touch the same file.\n5. **Propose execution.** \"Activate `developer` on `PRJ-NNN+1`?\"\n\nYou can also `/spec` with free-form text (no URL) — same flow without the MCP fetch step.\n\n### External board providers (`hctl provider`)\n\nManage the catalog that maps URL patterns → MCP fetch tool names. Shipped defaults cover Linear, GitHub, Trello, Azure DevOps, Jira, and Slack.\n\n```bash\nhctl provider list                          # show current catalog with status\nhctl provider test linear https://linear.app/eng/issue/ENG-42  # dry-run the URL match\nhctl provider enable linear                 # auto / always / disabled\nhctl provider disable jira\n\n# Add a custom internal board:\nhctl provider add acme \\\n  --mcp-fetch mcp__acme__get_card \\\n  --url-pattern '^https?://board\\.acme\\.corp/c/(?P\u003cref\u003e[A-Z0-9]+)' \\\n  --label-template '{ref}: {title}'\n```\n\nWhen the catalog and the MCP tool both line up, `/spec` and `holoctl-work-item-router` use the fetch transparently. When the MCP isn't connected, the skills fall back to paste — never silently fake a fetch.\n\n### Create a ticket\n\n```bash\nhctl board add '{\n  \"title\": \"Add JWT auth\",\n  \"agent\": \"developer\",\n  \"priority\": \"p1\",\n  \"projects\": [\"backend\"],\n  \"goal\": [\n    \"JWT signing implemented\",\n    \"Unit tests cover happy + invalid token\",\n    \"Lint and build pass\"\n  ],\n  \"context\": \"Sessions are cookie-based today; OAuth landing requires bearer.\"\n}'\n```\n\nOr in chat: *\"create a p1 ticket for JWT auth, developer persona, with goal: signing, tests, lint\"*. The agent (boardmaster) translates and runs the command.\n\n### Parallel-safe batch creation\n\n```bash\nhctl board batch '{\n  \"shared\": { \"tags\": [\"par:auth-flow\"], \"projects\": [\"backend\"] },\n  \"tickets\": [\n    { \"title\":\"JWT signing\", \"agent\":\"developer\", \"priority\":\"p1\", \"files\":[\"src/auth/jwt.py\"], \"goal\":[\"sign() emits HS256\",\"tests\"] },\n    { \"title\":\"Auth middleware\", \"agent\":\"developer\", \"priority\":\"p1\", \"files\":[\"src/middleware/auth.py\"], \"goal\":[\"verify+expiry\",\"tests\"] },\n    { \"title\":\"Auth integration tests\", \"agent\":\"reviewer\", \"priority\":\"p1\", \"files\":[\"tests/test_auth.py\"], \"goal\":[\"happy/expired/invalid\"] }\n  ]\n}'\n```\n\nThe CLI **rejects the batch** if any two tickets touch the same file (proves non-overlap before creating anything).\n\n### Move tickets\n\n```bash\nhctl board move PRJ-001 doing\nhctl board set PRJ-001 priority p0\nhctl board ls --status doing --priority p1\n```\n\n### Memory\n\n```bash\nhctl memory add api-conventions --scope glob -g \"src/api/**\" \\\n  -d \"API naming, error envelope, pagination\"\nhctl memory list\nhctl memory search \"JWT\"\nhctl memory get api-conventions          # read body\nhctl memory archive old-topic            # moves to topics/_archived/\n```\n\nTopic scopes:\n\n- `always_on` — always included in the assistant's context (use sparingly).\n- `lazy` — referenced in MEMORY.md, agent loads when relevant.\n- `glob` — only loaded when the assistant is editing files matching the glob.\n\n### Personas\n\n```bash\nhctl agent list                          # active vs library\nhctl agent suggest                       # heuristic — what to activate based on codebase\nhctl agent suggest --json                # machine-readable for automation\nhctl agent add developer                 # materialize from library\nhctl agent add custom --from developer   # copy active agent as base\nhctl agent remove developer              # deactivate (still in library)\n```\n\nLibrary: `developer`, `reviewer`, `architect`, `researcher`, `dba`, `devops`, `security-auditor`, `tech-writer`, `agent-designer`. `hctl agent suggest` matches `paths:` globs against your repo (e.g. `**/*.sql` → `dba`, `**/.github/workflows/**` → `devops`).\n\nWhen no library entry fits the repo, design a new one tailored to your stack:\n\n```text\n/agent-new payments-specialist\n```\n\nThe slash command delegates to the `agent-designer` persona, which reads the repo (README, package files, top-level dirs), drafts a schema-correct persona body (`name` / `description` / `tools` / `paths` / `model`), saves it as `.holoctl/agents/\u003cname\u003e.draft.md`, and asks for confirmation before materializing via `mcp__holoctl__agent_create`. The reactive `holoctl-persona-suggester` skill also surfaces \"want a new persona for this gap?\" whenever work touches paths no active persona owns.\n\n### Closing a session\n\n```bash\nhctl handoff                             # appends 1 line to memory/topics/session-trail.md\nhctl handoff --note \"Shipped 0.20.3\"     # plus a custom note\n```\n\nIf lifecycle hooks are installed (`hctl init` does this for Claude), `Stop` runs `hctl handoff --auto` automatically — you don't need to remember.\n\n### Session boot (cross-session continuity)\n\n```bash\nhctl boot                                # ≤1KB teaser\nhctl boot --target claude                # records source in journal\nhctl boot --plain                        # ASCII (no Rich color codes — used by hooks)\n```\n\nOutput example:\n\n```text\n## My Project — sessão 7\nPendências p0/p1: PRJ-003 Add JWT auth, PRJ-005 Fix N+1 in /tickets\nDecisões recentes: 2026-05-04-jwt-vs-sessions, 2026-05-01-monorepo\nTopics: api-conventions, decisions, session-trail\nPersonas ativas: boardmaster, developer, reviewer\n⚡ 2 sugestão do curador (PRJ-042, PRJ-043) — `hctl curate show`\n```\n\n### Curator\n\n```bash\nhctl curate run --auto                   # rate-limited (1/day, 14-day suppression per pattern)\nhctl curate show                         # open meta:curate tickets\nhctl curate apply PRJ-042                # run the proposed action manually\nhctl curate silence \u003cpattern_id\u003e         # 14-day suppression\nhctl board move PRJ-042 done             # ← approval auto-executes the action\n```\n\n### Web dashboard\n\n```bash\nhctl serve                               # http://127.0.0.1:4242\nhctl serve --host 0.0.0.0 --port 8000    # opt-in network exposure (warns: no auth)\n```\n\nTabs: **Board** (Kanban / List / Tree views with SSE updates), **Metrics** (throughput, cycle time, WIP \u0026 aging, flow efficiency, forecast — per-project), **Repos**, **Agents**, **Commands**, **Context** (expandable directory tree). The workspace home (`/`) rolls up board + metrics across all projects.\n\n### MCP server\n\n```bash\nhctl serve --mcp                         # stdio MCP server — assistants spawn this on demand\n```\n\nConfigured automatically by `hctl init` so you don't run it manually. Test it standalone with `--mcp`.\n\n---\n\n## Command reference\n\n| Command                              | What it does                                                                |\n|--------------------------------------|------------------------------------------------------------------------------|\n| `hctl init`                          | Create or sync `.holoctl/` (idempotent).                                    |\n| `hctl setup`                         | Plant `/holoctl` skill in every detected assistant (legacy — see `setup-global`). |\n| `hctl setup-global --target claude`  | Install the global `/holoctl` router for Claude Code.                       |\n| `hctl upgrade`                       | Migrate workspace + recompile to installed version.                         |\n| `hctl compile --target X`            | Generate AI-tool integration files. Default = `config.targets[]`.           |\n| `hctl serve [--mcp]`                 | Web dashboard (4242), or stdio MCP server.                                  |\n| `hctl doctor [--global]`             | Health check. First line = router-friendly.                                 |\n| `hctl coverage [--only-present] [--target X]` | Matrix of `.holoctl/` source → per-target outputs.                |\n| `hctl overview`                      | One-screen workspace snapshot.                                              |\n| `hctl boot [--target X]`             | ≤1KB session-zero context. Recorded in journal.                             |\n| `hctl handoff [--note \"...\"]`        | Append session-trail line. Auto-called by Stop hook.                        |\n| `hctl board \u003cls\\|add\\|move\\|set\\|batch\\|get\\|body\\|stat\\|rebuild-index\u003e` | Tickets.       |\n| `hctl agent \u003clist\\|suggest\\|add\\|remove\u003e` | Personas (library + active).                                           |\n| `hctl provider \u003clist\\|add\\|enable\\|disable\\|test\\|remove\u003e` | External-board catalog — URL pattern → MCP fetch tool. |\n| `hctl memory \u003clist\\|add\\|get\\|search\\|archive\\|seed\u003e` | Durable memory.                                          |\n| `hctl journal \u003crecord\\|show\\|count\\|tail\\|import\u003e` | Event journal.                                              |\n| `hctl curate \u003crun\\|show\\|apply\\|silence\u003e` | Autonomous curator.                                                    |\n| `hctl repo \u003clist\\|add\\|info\u003e`        | Subprojects (auto-discovered + manual overrides).                           |\n\nEvery command supports `--help`.\n\n---\n\n## Configuration\n\n`.holoctl/config.json` — only override what you need:\n\n```json\n{\n  \"holoctlVersion\": \"0.20.3\",\n  \"project\": {\n    \"name\": \"My Project\",\n    \"prefix\": \"MP\",\n    \"repos\": [\n      { \"path\": \"./backend\", \"name\": \"backend\", \"description\": \"FastAPI service\" }\n    ]\n  },\n  \"board\": {\n    \"statuses\": [\"backlog\", \"doing\", \"review\", \"done\", \"cancelled\"],\n    \"priorities\": [\"p0\", \"p1\", \"p2\", \"p3\"],\n    \"idPadding\": 3\n  },\n  \"git\": { \"checkDirty\": false },\n  \"targets\": [\"agents\", \"claude\"],\n  \"server\": { \"port\": 4242, \"theme\": \"dark\" },\n  \"providers\": {\n    \"linear\":  { \"enabled\": \"auto\", \"url_pattern\": \"...\", \"mcp_fetch_tool\": \"mcp__linear__get_issue\",   \"label_template\": \"{ref}: {title}\" },\n    \"github\":  { \"enabled\": \"auto\", \"url_pattern\": \"...\", \"mcp_fetch_tool\": \"mcp__github__get_issue\",   \"label_template\": \"{org}/{repo}#{ref}: {title}\" }\n    /* trello, azure_devops, jira, slack shipped too — see `hctl provider list` */\n  }\n}\n```\n\n**Notes:**\n\n- `targets` controls what `hctl compile` emits when called with no `--target`. Adding a target requires `hctl compile --target X` once to materialize.\n- `git.checkDirty` defaults to **false** — holoctl reads `.git/HEAD`/`refs`/`config` directly without spawning `git status`. Instant on Windows + corporate AV.\n- `board.idPadding: 3` produces `MP-001` (vs 2 → `MP-01`).\n- `providers` is populated additively on `load_config` — workspaces from older versions get the shipped defaults automatically. Use `hctl provider add` / `enable` / `disable` instead of hand-editing.\n- Adding a new field to a ticket: just write it in the `.md` frontmatter and run `hctl board rebuild-index`.\n\n---\n\n## Lifecycle hooks\n\n`hctl init` writes `.claude/settings.json` with hooks plumbed by default:\n\n```json\n{\n  \"hooks\": {\n    \"SessionStart\": [\n      { \"type\": \"command\", \"command\": \"hctl journal record session_start --source claude --quiet\" },\n      { \"type\": \"command\", \"command\": \"hctl boot --plain --target claude\",\n        \"description\": \"Print session-zero teaser before user types\" }\n    ],\n    \"PreToolUse\": [\n      { \"type\": \"command\", \"matcher\": \"Edit|Write\",\n        \"command\": \"hctl journal record write_attempt --stdin --quiet --deny-glob '.holoctl/board/index.json,.holoctl/memory/MEMORY.md,.holoctl/activity.jsonl'\",\n        \"description\": \"Block direct writes to derived state — force CLI usage\" }\n    ],\n    \"PostToolUse\": [\n      { \"type\": \"command\", \"command\": \"hctl journal record tool_use --stdin --quiet\" }\n    ],\n    \"Stop\": [\n      { \"type\": \"command\", \"command\": \"hctl journal record stop --quiet\" },\n      { \"type\": \"command\", \"command\": \"hctl handoff --quiet --auto\",\n        \"description\": \"Persist session-trail on every Stop. --auto skips trivial sessions.\" }\n    ]\n  },\n  \"permissions\": {\n    \"ask\": [ \"mcp__holoctl__board_create\", \"mcp__holoctl__memory_add\", \"...\" ],\n    \"deny\": [ \"Write(.holoctl/board/index.json)\", \"Edit(.holoctl/memory/MEMORY.md)\", \"...\" ]\n  }\n}\n```\n\n**The deny list is the enforcement** for the rule \"never edit derived state by hand\" — even if the agent forgets the instruction, the harness blocks the tool call.\n\nThese hooks and the deny-list are Claude Code-specific. Non-Claude assistants don't get holoctl-managed hooks — the `holoctl-foreign-bootstrap` skill carries the equivalent operating rules (e.g. \"never edit derived state by hand\") as instructions instead.\n\n---\n\n## Per-assistant guide\n\n### Claude Code\n\nAfter `hctl setup-global --target claude` and `hctl init`:\n\n- **Slash command**: `/holoctl` (your global router).\n- **Project context**: `CLAUDE.md` + `@.holoctl/memory/MEMORY.md` reference (auto).\n- **Subagents**: `.claude/agents/\u003cname\u003e.md` — invokable via the `Agent` tool.\n- **Hooks**: `.claude/settings.json:hooks` (boot teaser on SessionStart, handoff on Stop, deny-list on PreToolUse).\n- **MCP**: `.claude/settings.json:mcpServers.holoctl` runs `hctl serve --mcp`.\n\n```bash\n# Verify\nhctl doctor                        # workspace health\nhctl doctor --global               # router install drift\nls .claude/                        # agents/, commands/, settings.json\n```\n\n### Every other assistant (Copilot, Codex, Cursor, Aider, Zed, Junie, goose, …)\n\nholoctl does not maintain a compiler for these. They self-configure from the same `.holoctl/` source via the **`holoctl-foreign-bootstrap` skill**. After `hctl init`:\n\n1. The repo root has a minimal `AGENTS.md` (the cross-tool convention) that points the assistant at `.holoctl/foreign-bootstrap.md`.\n2. `.holoctl/foreign-bootstrap.md` is the procedure: read `.holoctl/` (`instructions.md`, `context/*`, `agents/*`, `memory/`, `commands/*`) and **generate your own native config dir** — Copilot → `.github/`; Codex → `.codex/`; Cursor → `.cursor/rules/`; generic AGENTS.md-aware tools → `AGENTS.md`. It carries per-tool format hints (frontmatter, MCP-server snippets) inline.\n\nSo the flow for a non-Claude assistant is: open the repo → read `AGENTS.md` → follow `.holoctl/foreign-bootstrap.md` → it writes the tool's native config from `.holoctl/`. Re-run that step after `hctl upgrade` (or whenever `.holoctl/` changes) to stay in sync — treat the generated `.github/` / `.codex/` / `.cursor/` as derived, don't hand-edit them.\n\nThis moves the per-tool translation out of holoctl's maintained Python and into one portable skill the assistant executes at runtime — which is why holoctl can support any AGENTS.md-aware tool without shipping (and keeping in lockstep) a bespoke compiler for each.\n\n---\n\n## Coverage and doctor\n\n### `hctl coverage`\n\nShows the fork between source and target:\n\n```bash\nhctl coverage                        # all sources × all targets\nhctl coverage --only-present         # only sources that exist in this workspace\nhctl coverage --target claude        # only one target column\n```\n\nOutput (filtered):\n\n```text\nhctl coverage (source → per-target outputs)\n  workspace: /home/me/my-project\n  active targets: agents, claude\n\n  Source                             | agents     | claude\n  ──────────────────────────────────────────────────────────────\n  instructions.md                    | —          | ✓ CLAUDE.md\n  agents/*.md                        | —          | ✓ .cl/agents\n  commands/*.md                      | —          | ✓ .cl/comma\n  memory/topics/*.md                 | —          | ✓ .cl/skills\n  (MCP servers)                      | —          | ✓ settings\n  (foreign-assistant bootstrap)      | ✓ AGENTS.md| —\n```\n\n### `hctl doctor`\n\n```bash\nhctl doctor                # workspace health\nhctl doctor --global       # global router install drift\n```\n\nFirst line is **router-friendly** (parsed by `/holoctl`):\n\n- `holoctl: not initialized` → no `.holoctl/` found at or above cwd.\n- `holoctl: outdated` → workspace `holoctlVersion` \u003c installed `hctl --version`.\n- `holoctl: ok` → workspace at current version.\n- `holoctl: global-check` → `--global` mode.\n\n---\n\n## Privacy \u0026 coexistence\n\n- **`hctl init` writes nothing to `$HOME`.** Only `hctl setup-global` does — and only the router files in user-scope locations of detected assistants.\n- **No machine-wide registry, no daemon, no telemetry, no auto-update check.** Workspace = `.holoctl/` next to your code. That's the entire footprint.\n- **`.holoctl/memory/.gitignore`** ships with `_archived/` excluded by default. Privacy-strict workspaces uncomment two lines to make the whole memory tree local-only.\n- **Coexists with native auto-memory.** Claude Code's auto-memory is **not** disabled. `holoctl` adds a `@.holoctl/memory/MEMORY.md` reference to `CLAUDE.md` so Claude reads both sources.\n- **Compiled outputs** are best `.gitignore`'d (`.claude/`, `CLAUDE.md`) — they're regenerated from `.holoctl/`. The `AGENTS.md` shim and `.holoctl/foreign-bootstrap.md` are usually worth committing, so a non-Claude assistant cloning the repo can bootstrap itself without `holoctl` installed. Some teams commit `.claude/` too, for new contributors who don't have `holoctl` yet.\n\n---\n\n## Troubleshooting\n\n### `hctl: command not found`\n\n- **`uv tool` / `pipx`**: should be on PATH automatically. If not, run `uv tool update-shell` or `pipx ensurepath` and reopen the terminal.\n- **`pip` install**: if you didn't use a venv, you hit PEP 668 or installed into the wrong Python. Re-do it via the venv method in [Installation](#installation).\n- **Workaround**: `python -m holoctl \u003csubcommand\u003e` works regardless of PATH (as long as the venv is active).\n\n### `/holoctl` does nothing\n\n- Run `hctl doctor --global`. Probably you skipped `hctl setup-global`. Run it.\n- For Codex/Aider/Zed/other AGENTS.md-aware tools: no global router — they consume the per-project `AGENTS.md` emitted by `hctl compile --target agents`.\n\n### `No .holoctl/ found`\n\n- You're not in a project that's been `hctl init`'d. Either run `hctl init` here, or `cd` into a project that has `.holoctl/`.\n- `find_project_root` walks up the tree looking for `.holoctl/config.json`. If you're inside a subfolder of a project, it should still find it.\n\n### `hctl init` says \"Refusing to downgrade\"\n\n- The workspace was created with a newer `hctl`. Either upgrade your `hctl` (`uv tool upgrade holoctl`) or manually edit `.holoctl/config.json:holoctlVersion` (not recommended).\n\n### Compile produces stale outputs / `hctl doctor --global` always says \"drift\"\n\n- The user-edited their global router by hand → drift detected. Run `hctl setup-global --target X --force` to overwrite, or accept the drift if intentional.\n\n### `Window edition / Powershell` / hctl path issues\n\n- The legacy global router (pre-0.14) had a hardcoded venv path. If you're upgrading from before 0.14: run `hctl setup-global --target claude` to replace it with the PATH-based version.\n\n### MCP server not responding\n\n- `hctl serve --mcp` is stdio-only. The assistant spawns it via the MCP config; check `.claude/settings.json:mcpServers.holoctl.command` resolves to a valid `hctl` (or `python -m holoctl`).\n- Set `HOLOCTL_BIN=/abs/path/to/hctl` env var to override the auto-detection.\n\n### Tests fail with `No module named 'httpx'`\n\n- `tests/test_dashboard.py` uses `fastapi.testclient` which requires `httpx`. `httpx` is declared in `pyproject.toml`'s `[dependency-groups].dev` (PEP 735) — picked up automatically by `uv sync`. If you're using plain `pip` (no uv), install it manually: `pip install httpx pytest`. The CI matrix uses `uv sync --frozen` and runs the full test suite without skipping.\n\n---\n\n## FAQ\n\n**Do I have to use the slash command? Can I use `hctl` directly?**\n\nYes. The CLI is the source of truth — slash commands are conveniences. Everything is doable from a terminal.\n\n**Can I use this without the AI assistant?**\n\nYes. `hctl board`, `hctl memory`, `hctl serve` work fine standalone. You get a Kanban + memory layer + MCP server even without any AI tool.\n\n**Does this conflict with Claude Code's auto-memory?**\n\nNo — they coexist. Claude reads both `CLAUDE.md` (which references `.holoctl/memory/MEMORY.md`) and its native auto-memory. The curator can promote durable patterns from auto-memory into versioned topics.\n\n**Can I share `.holoctl/` across multiple repos in a monorepo?**\n\nYes — that's the design. `hctl init` at the monorepo root, then `hctl repo add ./backend ./frontend ./mobile`. Tickets can declare `projects: [backend, shared]`.\n\n**How do I support a new AI tool?**\n\nYou usually don't add a compiler — that's the whole point of the redesign. Any AGENTS.md-aware (or instruction-file-aware) assistant is served by the `holoctl-foreign-bootstrap` skill, which reads `.holoctl/` and writes the tool's native config. If the tool needs format hints holoctl doesn't already carry, add them to `holoctl/templates/skills/holoctl-foreign-bootstrap/references/format-hints.md` — no Python. holoctl maintains a native compiler only for Claude Code (`compiler/claude.py`); see `CONTRIBUTING.md`.\n\n**Where's the data stored?**\n\nEverything in `.holoctl/`, in your repo, version-controlled by you. No cloud, no database, no daemon.\n\n**Can I customize the persona library?**\n\nYes. The library lives in `holoctl/templates/agents/` (read-only when installed via PyPI). To customize: clone the repo, edit, and `pip install -e .` for local dev. Or override per-project: `hctl agent add custom --from developer` then edit `.holoctl/agents/custom.md`.\n\n**The agent ignores my context files**\n\nCheck that `.holoctl/instructions.md` is being compiled (not `.holoctl/context/objective.md` directly). The compile pipeline merges context → instructions → CLAUDE.md/AGENTS.md/etc. Run `hctl coverage --only-present` to see what's flowing where.\n\n---\n\n## Migration from projctl / projhub\n\nEarlier names of this project. holoctl reads `.projctl/` and `.projhub/` directories and **auto-renames them to `.holoctl/`** on the next save. Tickets that used `scope: X` are read as `projects: [X]` and rewritten on the next `board set` or `rebuild-index`.\n\n**No manual migration needed** — open a `projctl`/`projhub` workspace with `hctl` 0.14+ and it's silently upgraded.\n\nIf you had `~/.claude/commands/projctl.md` or `projhub.md`: run `hctl setup-global --target claude` to install the new `holoctl.md` and delete the legacy ones manually.\n\n---\n\n## Roadmap\n\n- **Two-way provider sync** — close the original card on the external board when the holoctl spec reaches `done` (currently the assistant just gets a reminder).\n- **Expanded provider catalog defaults** — community-contributed entries for less common boards (ClickUp, Asana, Notion, internal RFC systems).\n- **Curator v2** — structural pattern detection (e.g., \"you keep editing the same 3 files together; want a rule?\").\n- **`.holoctl/skills/` ecosystem** — community-shared skills with progressive disclosure (cross-tool by compile).\n- **VS Code extension** — board view + memory navigation in the IDE.\n- **Multi-workspace dashboard** — `hctl serve --multi` for monorepos with many subprojects.\n\n---\n\n## Documentation \u0026 license\n\n- [CHANGELOG.md](holoctl/CHANGELOG.md) — release notes\n- [ARCHITECTURE.md](ARCHITECTURE.md) — internal design, compile pipeline, threat model\n- [SECURITY.md](SECURITY.md) — vulnerability reporting + threat model\n- [CONTRIBUTING.md](CONTRIBUTING.md) — dev setup, conventions, how to add a compile target\n- [docs/README.pt-br.md](docs/README.pt-br.md) — Portuguese version of this README\n\nMIT © [Felipe Carillo](https://github.com/FelipeCarillo)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffelipecarillo%2Fholoctl","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffelipecarillo%2Fholoctl","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffelipecarillo%2Fholoctl/lists"}