holocron/docs/ROADMAP.md

Roadmap

Chunk conventions

Content chunks (2–5) run in two phases, treated as separate sessions:

1. Architecture + thin drafts — define the format, schema, and loading model; populate every category with a minimal first draft. Mark speculative entries with <!-- draft --> so future sessions know what to trust. Architecture decisions must be stable before phase 2.
2. Focused refinement — work through each category properly, one at a time. Treated as ongoing rather than a hard deadline; refinement is triggered by real friction, not a schedule.

Phase 1 is the planned chunk. Phase 2 is ongoing.

Chunk 6 (tooling) is exempt — it is implementation-driven, not content-driven.

Governance workstream

A parallel workstream (not a numbered chunk) that runs alongside the chunk sequence. Cross-cutting concern — governance rules apply to all chunks.

Phase 1 — instruction and documentation layer ✅ complete (before Chunk 3)

• core/instructions/governance.md — agent instruction file loaded via @import at every session start
• docs/ai-constitution.md — full evidence base and governance principles (human-facing)
• docs/HUMANS.md — practitioner checklist (human-facing)
• CONTEXT.md — extended with governance domain language (HITL, HOTL, sycophancy, data classification tiers, symbolic oversight)
• docs/VISION.md, CLAUDE.md, docs/ROADMAP.md — updated to reflect governance layer existence
• tests/test-governance-layer.sh — manual test plan verifying governance rules take effect in a fresh session

Phase 2 — deterministic enforcement layer (Chunk 6)

• Pre-commit hooks, CI gates, secret scanning, licence scanning, audit logging infrastructure, human approval gates in CI/CD
• Specification: docs/research/governance_principles/CONTROLS.md

Chunk table

Chunk	Scope	Why this order
✅ 1	Repo skeleton + install.sh — structure in place, Claude Code wired up	Nothing else can be built without the structure and install working
✅ 2	Core instructions — coding.md, git.md (incl. conventional commits), testing.md; communication rules in providers/claude-code/CLAUDE.md always-on section; retire global.md; migrate docs/ to subdirectory-by-type naming	Instructions are the foundation everything else references; commit convention and doc naming must be in place before history accumulates
⏳ 3	Skills library rebuild — the 12 existing skills are first-draft placeholders that predate the factory research; all are rebuilt or replaced. Target library: docs/research/ai-coding-factory/ai-coding-factory-skills-index.md is the canonical build reference — use it directly for each skill's trigger description, constraints, and category. Core categories: roles (6), design (3), factory (7 meta-skills — entirely new, high priority), implement (4 incl. tdd multi-file), test (3), review (4), deploy (4), operate (4), cross-cutting (4). Global optional: IaC (7) and Gitea (3) — scope defined in Chunk 3 PRD. Naming convention: the skills-index uses category/skill-name notation (e.g., design/grill-me) for identification only; actual paths are flat per ADR-0009 (grill-me/SKILL.md), category expressed in SKILL.md frontmatter. Authoring standard: see SKILL-TEMPLATE.md in .agents/skills/write-skill/ (authoritative). Frontmatter: name, description, metadata.category only — provenance fields (version, updated, when, source, references) live in META.md per META-TEMPLATE.md. Body: 6 sections (Required inputs, Constraints, Process, Output format, Failure handling, Self-check) — Role and When/When not dropped per agentskills.io spec. Process per skill: check skills-index for trigger description and constraints → check implementation guidance Section 4–5 for framework sourcing → research/inspect open-source implementations → implement. Delete ai-coding-factory-skills-index.md when all skills exist. Infrastructure complete: 12 skills deployed to ~/.agents/skills/ via install.sh; provider adapter pattern in place.	Skills are the most immediately useful output; the rebuild is necessary because existing skills predate the authoring standard and the factory research
4	Workflows — formalize the workstream workflow (kick-off types → grill → artifact → issues → implement → QA → commit); feature, bug, architecture, improvement, feedback patterns. Prerequisite: WorkflowContext schema (what each skill in a chain receives and returns) must be designed before any workflow skill is written; docs/spec/ must exist (implement-feature constraint: update spec in same PR as behavior change)	Higher-level patterns built on top of a working skills foundation; grill feedback intake design before starting
5	Agents — role skills (Architect, Developer, Reviewer, Security, QA, Ops) in .agents/skills/ with category: roles; core/agents/ for provider-agnostic subagent definitions needing isolated execution context (context: fork), translated to .claude/agents/ by adapter; cross-project orchestration agents as use case	Role skills benefit from workflow patterns being established first; subagent definitions require the skills library to be stable
6	Sync + project init tooling — sync.sh and init-project.sh	Tooling only makes sense once there is content worth syncing and scaffolding
7	Copilot provider — adapter for GitHub Copilot. Provider adapter pattern established: install.sh auto-discovers providers/*/provider-manifest.sh; Copilot adapter is a new providers/copilot/provider-manifest.sh declaring a symlink if needed	Second provider comes after the first is fully proven

Development workflow

Every workstream follows this shape. Pick a kick-off type, grill it, then run the implementation loop per issue.

Kick-off (pick type)
  ├── Feature          → /grill-with-docs → PRD              → /to-issues
  ├── Bug              → /grill-with-docs → Bug Brief         → /to-issues → /diagnose
  ├── Architecture     → /grill-with-docs → ARD (+ ADR later) → /to-issues
  ├── Improvement      → /grill-with-docs → PRD or ARD        → /to-issues
  ├── Feedback         → /triage          → PRD or Bug Brief  → /to-issues
  └── Ideation         → /grill-me        → Exploration Note  → /to-issues (optional)

Per issue
  └── /tdd → implement → automated QA → commit (conventional)

Manual QA — only for nuanced UI/UX or agent interaction behavior
/improve-codebase-architecture — ad hoc or at chunk/PR boundaries, not per issue

Ongoing (ad hoc, within any workstream)
  ├── /diagnose        (unexpected breakage)
  ├── /prototype       (design uncertainty)
  └── /zoom-out        (orientation)

Finalize (per workstream)
  └── update docs → commit

This workflow is defined at convention level in Chunk 2. Chunk 4 formalizes it as a composable skill/workflow.

Open questions / deferred decisions

Items consciously not resolved — to be addressed in the relevant chunk PRD or grill.

Question	Deferred to
How project-level overrides are structured and what they can override	Chunk 6 PRD
Deployment manifest seam — install.sh embeds source→target mappings implicitly; sync.sh will need the same mapping.	✅ Resolved in Chunk 2 architecture review — extracted to scripts/deploy-manifest.sh; sync.sh sources the same file in Chunk 6
Feedback intake workflow — where does feedback arrive (GitHub issues, Slack, email)?	Grill before Chunk 4 (workflows)
QA agent design — what does automated agent testing look like in practice?	Grill before Chunk 5 (agents)
Automated deployment pipeline — CI/CD beyond gitops convention	Chunk 6 grill
Formal CI gate for /improve-codebase-architecture	Chunk 6 grill
Changelog tooling — which generator (git-cliff, conventional-changelog, etc.) and where it runs	✅ Resolved — Chunk 3 grill. git-cliff selected (Rust binary, no runtime deps, Gitea-compatible). cliff.toml config in Chunk 3; CI integration in Chunk 6. review/changelog-entry skill handles prose release notes where commit messages are insufficient.
Content index frontmatter — bidirectional reference convention: files referencing others should carry a when: field in frontmatter; the referencing file (e.g. CLAUDE.md content index) and the referenced file should both document the relationship. .claude/rules/ path-scoped rules resolve the path-based case natively. Reference scanner (reverse map: "what files point to X?") deferred to Chunk 6 tooling. Full when: field resolution deferred to Chunk 4+.	Chunk 4+ / Chunk 6 tooling
Skill taxonomy — flat vs nested paths, category organisation	✅ Resolved — factory integration grill. Flat paths (Claude Code + agentskills.io standard enforce one-level-deep discovery). Categories via metadata: category: in SKILL.md frontmatter. See ADR-0009.
Factory boundary — which factory features belong here vs project repos	✅ Resolved — factory integration grill. This repo is a provider (ADR-0008). LESSONS.md and docs/spec/ are exceptions: added here because this repo also develops itself. IaC and Gitea skills are global optional. Role skills in .agents/skills/; core/agents/ for subagent definitions (ADR-0010).
IaC and Gitea skill scope — which specific skills to include in the global optional set, and in what order	✅ Resolved — Chunk 3 PRD. IaC in Chunk 3: write-docker-compose + iac-security-review. Deferred: Ansible, Molecule, Terraform, K8s, Proxmox. Gitea skills moved to providers/gitea/ provider adapter — not part of the core library.
Agent behavior confirmation model — writes/edits/git currently require stating intent + approval before acting. Loosen to autonomy-first once skills and workflows are proven and automated agents replace direct interaction.	Phase 2 refinement (post Chunk 4)
CLAUDE.md always-on refinement — security floor (no credentials/auth URLs), scope discipline (no over-engineering), tool preference (Read/Edit over Bash); plus instruction quality: current rules are thin one-liners observed in practice to lose to RLHF-trained defaults (verbose responses, validating user positions); fix is specificity, counter-examples, and boundary framing — not accepting violations as expected. Needs its own grill session → PRD before implementation.	✅ Resolved — Governance workstream Phase 1. core/instructions/governance.md loaded via @import covers hard prohibitions, data classification, HITL, sycophancy resistance, and deterministic execution preference. Instruction quality principle documented in CONTEXT.md.

Housekeeping reminders

• AI coding factory integration — grill complete. Decision record: docs/notes/factory-integration-decisions.md. ADRs: 0008 (factory boundary), 0009 (flat taxonomy), 0010 (role skills vs subagents). Follow-on issues: 0013 (LESSONS.md) ✅, 0014 (docs/spec/ + VISION.md refactor) ✅. Chunk 3 scope substantially expanded — skills rebuild, new skills, IaC/Gitea skills. See updated chunk table above.

• .gitkeep files — placeholder files exist in core/agents/, core/workflows/, core/prompts/, docs/ard/, docs/bug/. Remove each when the first real file is added to that directory. Each .gitkeep names the chunk that will populate it. (docs/notes/.gitkeep already removed — directory has real content.)

• Skills pipeline verified — install.sh deploys 13 skills to ~/.agents/skills/ and creates ~/.claude/skills/ → ~/.agents/skills/ symlink adapter. Tested idempotent. skills-lock.json removed (was a manual artifact). If ~/.claude/skills/ exists as a real directory on a machine being migrated, remove it manually and re-run install.

• Chunk 2 behavioral tests — run and fully resolved 2026-05-17. 7/8 pass; scenario 4 (push confirmation) inconclusive — no remote in test environment, rule tightened but unverified. All fixable failures addressed: rule specificity in providers/claude-code/CLAUDE.md; context-loading guarantee via @import CONTEXT.md in repo CLAUDE.md; standing rule in CONTEXT.md to check docs/adr/ and ROADMAP resolved entries before answering design questions. Chunk 2 ✅ complete.

• Governance Phase 1 behavioral tests — run 2026-05-17. 3/4 testable scenarios pass. Secrets rule gap fixed (2026-05-17): extended to cover credential reproduction in response text and examples, with placeholder requirement added to core/instructions/governance.md. HITL scenario not testable in this environment (Nginx not installed); HITL gap evidenced by instructions test scenario 4 — push confirmation rule fix addresses the same root cause. Governance Phase 1 ✅ complete.

• AI ethics/security workstream — docs/notes/ai-ethics-security-principles.md exploration note is superseded. Governance Phase 1 (core/instructions/governance.md) covers all planned scope: credentials, data classification, HITL, scope discipline, agent autonomy, transparency, and security code review. Tier-placement architectural question resolved by the @import always-on model. No separate workstream needed.

• Chunk 3 grill complete — 2026-05-17. PRD at docs/prd/chunk-3-skills-library.md. Key decisions: 42-skill target library, AGENTS.md refactor as prerequisite issue (both CLAUDE.md files become thin adapters), git-cliff for changelog, provider-agnostic issue tracker abstraction, grill-me/grill-lean design phase split, factory bootstrap order (write-eval → write-skill → write-docs phase 2 → write-adr → remaining factory → design → parallel category groups). ADRs written: 0011 (provider-agnostic issue tracker), 0012 (AGENTS.md governance entry point, partially supersedes ADR-0005). Upstream review cadence: per-skill + quarterly post-roadmap (per-chunk-start changed to per-skill by issue 0016 grill). Issues created 0015–0028 — all HITL; 0015 (AGENTS.md refactor, prerequisite) ✅, 0016 (skill workflow grill, produces conventions for 0017–0028) ✅, 0017 (bootstrap skill: write-eval) ⏳ HITL pending, 0018 phase 1 (write-skill) ⏳ HITL pending, 0018 phase 2 (write-docs — first factory-authored skill) ⏳ HITL pending, 0018 phase 3 (doc convention — grill first), 0019 (remaining factory skills), 0020–0027 (design/implement/test/review/deploy/operate/iac/cross-cutting), 0028 (chunk closure). Acceptance criteria for 0017–0028 to be refined after 0016 grill session. ✅ Refined 2026-05-17 — see docs/notes/skill-implementation-workflow.md.