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.

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	First skills — initial slash commands for day-to-day use; changelog tooling (follow-on to Chunk 2 conventional commits); catalogue existing skills incl. zoom-out which is installed but undocumented	Skills are the most immediately useful output; validates the full pipeline
4	Workflows — formalize the workstream workflow (kick-off types → grill → artifact → issues → implement → QA → commit); feature, bug, architecture, improvement, feedback patterns	Higher-level patterns built on top of a working skills foundation; grill feedback intake design before starting
5	Agents — role definitions (reviewer, architect, developer)	More abstract definitions; benefits from workflow patterns being established first
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	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	Chunk 3 grill
Content index frontmatter — replace inline when: hints in CLAUDE.md content index with a when: field in each instruction/skill file so the agent discovers load conditions from the file itself. Cover before implementing Chunk 3 skills.	Chunk 3 grill
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). Needs its own grill session → PRD before implementation.	Future workstream, post Chunk 2

Housekeeping reminders

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