holocron/docs/spec/overview.md

Overview

Current deployed state of this repo — what you get if you run install.sh today. Updated at the close of each chunk and in the same PR as any behavior change.

Last updated: 2026-06-20 (kyberforge plugin — marketplace skill consolidation)

What is deployed

Plugins

1 plugin registered in the marketplace (holocron marketplace, .claude-plugin/marketplace.json):

• kyberforge — marketplace management toolkit. Contains create-plugin, marketplace-architect, write-skill, write-eval skills plus bundled assets (assets/plugin-template/), reference docs, scripts, and evals. Install: claude plugin install kyberforge@holocron. Source: plugins/kyberforge/. Research doc: plugins/kyberforge/docs/plugin-marketplace-architecture.md.

Skills

13 skills deployed directly to ~/.agents/skills/ via install.sh. Available as slash commands in Claude Code via ~/.claude/skills/ → ~/.agents/skills/ symlink. Factory and marketplace skills (write-eval, write-skill, create-plugin, marketplace-architect) have moved to the kyberforge plugin and are only available after plugin install.

Factory bootstrap (now in kyberforge plugin):

• write-eval — produces eval.yaml test files for skills. Hand-written (bootstrap). Eval at plugins/kyberforge/tests/evals/write-eval/eval.yaml.
• write-skill — authors new SKILL.md files and converts placeholders to canonical format. Hand-written (bootstrap). Eval at plugins/kyberforge/tests/evals/write-skill/eval.yaml. Invokes write-eval as part of its own process.
• write-docs — produces technical documentation derived from code and spec; never invents behaviour. First factory-authored skill (SKILL.md produced via write-skill, eval via write-eval). Eval at .agents/evals/implement/write-docs/eval.yaml. Sources: anthropics/skills doc-coauthoring, mattpocock/skills write-a-skill, bmad-code-org/BMAD-METHOD bmad-advanced-elicitation.

Current skills (direct): caveman, diagnose, gitleaks, grill-me, grill-with-docs, improve-codebase-architecture, prototype, tdd, to-issues, to-prd, triage, write-docs, zoom-out.

Chunk 3 target: 42 skills across 9 categories. PRD: docs/prd/chunk-3-skills-library.md. Canonical build reference: docs/research/ai-coding-factory/ai-coding-factory-skills-index.md (delete once all skills exist). Skills stored flat (skill-name/SKILL.md) per ADR-0009; category in metadata.category frontmatter. Categories: design, factory, implement, test, review, deploy, operate, cross-cutting, iac (2 skills only — docker-compose + iac-security-review). Role skills (6) deferred to Chunk 5. Gitea skills moved to providers/gitea/ provider adapter.

Skill implementation workflow: each skill follows the per-skill process in docs/notes/skill-implementation-workflow.md (produced by issue 0016). Sub-agents handle source discovery, source review, and conflict checking; synthesis grill and HITL test are human steps. Bootstrap: write-eval (hand-written) → write-skill (hand-written) → write-docs (first factory-authored) → all others via factory.

Claude Code configuration

• ~/.claude/CLAUDE.md — thin adapter; imports ~/.agents/AGENTS.md (Communication + Behavior) and governance.md; content index pointers only
• ~/.agents/AGENTS.md — global always-on rules (Communication + Behavior); provider-agnostic source of truth
• ~/.claude/core/instructions/ — coding, git, testing, governance instruction files
• ~/.claude/settings.json — Claude Code settings

Governance layer

core/instructions/governance.md loads into every Claude Code session via @import in ~/.claude/CLAUDE.md. Covers: hard prohibitions on secrets and data, data classification tiers, HITL requirements, sycophancy resistance, deterministic execution preference.

What works end-to-end

• install.sh runs idempotently — safe to re-run after changes
• Provider adapter pattern: providers/*/provider-manifest.sh auto-discovered by install.sh
• Governance rules take effect at session start without any manual loading step
• Skills available as slash commands immediately after install

What is not yet deployed

• sync.sh — pulls updates into existing projects (Chunk 6)
• init-project.sh — bootstraps a new project (Chunk 6)
• Copilot provider adapter (Chunk 7)
• Formal CI/pre-commit enforcement of governance rules (Chunk 6)
• setup-gitleaks.sh not yet wired into init-project.sh (Chunk 6) — run manually against new repos

For chunk planning and open questions, see docs/ROADMAP.md.

Recent changes

• 2026-06-20 — kyberforge plugin created and registered in holocron marketplace. Consolidates create-plugin, marketplace-architect, write-skill, and write-eval skills (previously in .agents/skills/) plus their evals, bundled scripts, references, and the plugin-marketplace-architecture research doc into a single installable plugin at plugins/kyberforge/. Plugin template (templates/plugin/) bundled into plugins/kyberforge/skills/create-plugin/assets/plugin-template/ and removed from repo root. Evals moved from .agents/evals/marketplace/ and .agents/evals/factory/write-eval/ into plugins/kyberforge/tests/evals/. These four skills are no longer available as standalone slash commands — install the plugin to use them.

• 2026-06-20 — Gitleaks secret scanning added. scripts/setup-gitleaks.sh installs gitleaks v8.24.2, seeds .gitleaks.toml (first run only — project-owned after that), and writes a managed pre-commit hook block that is replaced on re-run. scripts/gitleaks.toml is the base config template extending gitleaks defaults. tests/test-setup-gitleaks.sh covers 6 behaviors (reject non-git dir, config deploy, hook create, append, stale-block replace, idempotency). .gitleaks.toml in repo root adds path allowlist for docs/research/ (high-entropy terminal captures). gitleaks skill added (cross-cutting) covering full lifecycle: install, update, tune allowlist, scan modes, resolve real findings. Key lesson: v8.24.2 uses [allowlist] (singular); v8.25.0+ uses [[allowlists]] — wrong syntax silently does nothing.

• 2026-05-18 — Issue 0018 phase 1 refactor complete: write-skill redesigned from scratch. New files added to skill directory: SKILL-TEMPLATE.md (authoritative 6-section template with XML blocks, human-usable), META-TEMPLATE.md (provenance schema with inline-commented YAML), CATEGORIES.md (self-contained category table), META.md (write-skill's own provenance). SKILL.md rewritten: 6 sections replacing 8 (Role and When/When not dropped — not in agentskills.io spec); frontmatter reduced to 3 fields (name, description, metadata.category); provenance fields (version, updated, when, source, references) moved to META.md (progressive disclosure — not loaded at startup). docs/notes/skill-implementation-workflow.md updated to reference SKILL-TEMPLATE.md as the authoritative template.

• 2026-05-17 — Issue 0018 phase 2 complete: write-docs skill written and deployed. First skill produced end-to-end by the factory (SKILL.md via write-skill, eval via write-eval). Category: implement. Key decisions: file-approval gate before reading (user names files or approves proposals); gap check before drafting (user fills what code doesn't explain); stage skipping allowed with logged reason; full revised section shown before confirmation gate; surgical edits only with per-round delta summary; Reader Testing via scoped sub-agent (doc + questions only, no source files); summary/overview sections written last. Sources: anthropics/skills doc-coauthoring (Reader Testing stage, surgical-edit constraint), mattpocock/skills write-a-skill (trigger pattern), bmad-code-org/BMAD-METHOD bmad-advanced-elicitation (confirmation gate). Open follow-up: documentation convention (file/folder/content structure, global vs repo-specific) — not yet defined.

• 2026-05-17 — Issue 0018 phase 1 complete: write-skill bootstrap skill written and deployed. Hand-written (factory bootstrap). Self-authored — no upstream content adopted; agentskills.io best-practices and optimizing-descriptions docs cited as references. Speckit excluded (AGPL-3.0). Key decisions: new-skill + placeholder-conversion scope only (upgrades → upgrade-skill); trigger description tested against 3 cases before body written; write-eval invoked as step 7 in process; HITL prompt as step 8. Eval at .agents/evals/factory/write-skill/eval.yaml.

• 2026-05-17 — Issue 0017 complete: write-eval bootstrap skill written and deployed. Two sections schema (trigger_tests + output_tests), provider-agnostic string assertions, show-plan-then-merge-on-rerun behaviour, conflict flagging (B model). Sources: agentskills/agentskills, darkrishabh/agent-skills-eval, bmad-code-org/BMAD-METHOD, mattpocock/skills. Hand-written eval at .agents/evals/factory/write-eval/eval.yaml.

• 2026-05-17 — Issue 0016 complete: skill implementation workflow grill completed. docs/notes/skill-implementation-workflow.md written. All issues 0017–0028 updated with specific acceptance criteria. Key conventions: sub-agents prescribed at each research/writing step; conflict check against constitution + factory principles before synthesis grill; when: and references: fields added to authoring standard; write-docs moved to issue 0018 phase 2 (first factory-authored skill).

• 2026-05-17 — Issue 0015 complete: AGENTS.md refactor implemented. Two AGENTS.md files created (AGENTS.md at repo root, core/AGENTS.md deployed to ~/.agents/AGENTS.md). Both CLAUDE.md files slimmed to thin adapters. deploy-manifest.sh updated. docs/spec/architecture.md updated with new structure. ADR-0012 in effect.

• 2026-05-17 — Chunk 3 issues created (0015–0028): AGENTS.md refactor prerequisite, skill workflow grill, bootstrap skills (write-eval, write-skill), factory/design/implement/test/review/deploy/operate/IaC/cross-cutting skill groups, chunk closure; all HITL; acceptance criteria for 0017–0028 to be refined after issue 0016 grill session

• 2026-05-17 — behavioral tests fully resolved: CONTEXT.md now always-loaded via @import in repo CLAUDE.md; standing rule added to check docs/adr/ and ROADMAP resolved entries before answering design questions; communication/behavior and secrets rules tightened; Chunk 2 and Governance Phase 1 ✅ complete

• 2026-05-17 — added LESSONS.md (issue 0013) and docs/spec/ (issue 0014); refactored docs/VISION.md to goals/intent only