holocron/docs/VISION.md

Vision

Purpose

A global AI development configuration repository — the authoritative source for agent definitions, skills, workflows, and prompts across all projects. Provides a consistent, provider-agnostic foundation that individual projects can inherit and extend.

Designed to start as a personal homelab tool and grow into something shareable with a team and potentially the open source community.

Goals

• Single source of truth — one place to define and evolve AI development configs across all projects
• Provider-agnostic core — content works across AI coding tools (Claude Code, GitHub Copilot, etc.) through thin provider adapters
• Layered override model — global defaults defined here, project-level overrides live in each project
• Pull-based distribution — projects opt into updates consciously; no automatic or silent changes
• Scales gracefully — works solo today, designed to onboard a team and open source later
• Governance layer — hard prohibitions on secrets and data, data classification framework, HITL requirements, sycophancy resistance, and deterministic execution preference; loaded into every session via @import, not left to per-prompt instruction

Non-Goals (for now)

• Automatic push-based sync to projects
• Runtime dependency from projects back to this repo
• Bootstrapping new projects (init-project.sh comes in chunk 6)
• GitHub Copilot support (chunk 7)

Current architecture

See docs/spec/architecture.md for the deployed directory structure, content deployment model, governance layer, provider model, and architectural decisions.

V1 Definition

V1 is "ready to develop" — not a finished product. It means this repo is structured, Claude Code is wired up to it, and there is enough initial content to start building incrementally.

V1 = Chunk 1 complete — ✅ done.

Everything from chunk 2 onward is content and tooling built on top of that foundation.

Long-term: Management Application

A product for making it easy to manage and update AI development configs. Lives in a separate repo. The UX speaks in domain concepts — skills, workflows, agents, providers. Git is the persistence layer, invisible to the user. Saving a skill commits under the hood; the user just clicks Save.

The app is repo-agnostic — it works with any git repo that follows these conventions. This repo is the canonical default content: the official starter pack referenced in the app's setup flow.

Phase 1 — Config Management

Browse, edit, and configure AI development config through a proper product UI.

Core features: browse the skill/workflow/agent/prompt library; create and edit config content; manage provider settings.

Design principle: This is a product, not a file browser. Users never see git operations, file paths, or commit messages. The UI presents domain concepts (skills, workflows, agents, providers) and handles persistence silently. Any feature that exposes git internals to the user is out of scope.

Architecture:

• Stack: React + TypeScript + Vite (frontend), Node.js + Fastify + TypeScript (backend), PostgreSQL (introduced only when a specific feature requires state with no natural home in git)
• Stack rationale: single language across the full stack keeps the codebase navigable for junior developers and AI coding agents; TypeScript's explicit types make intent clear without comments; React → React Native is the cleanest path to mobile in Phase 3; simple-git covers all required git operations without needing a Python backend
• Git operations via simple-git; git repo stays the source of truth
• Deployment: Docker (Nginx + Node containers), k8s-ready
• Hosting: self-hosted first, cloud-hosted option later
• Users: solo-first, multi-user-ready data model from day one

Start trigger: after Chunk 6 of this repo (sync.sh + init-project.sh). Full content model and sync tooling must be stable before building a UI over them.

Mobile/desktop (Phase 3): React → React Native for mobile; Tauri to wrap the web app for desktop.

Phase 2 — Agent & Fleet Management

Runtime orchestration: push config updates to machines, see running agents, manage task queues and outputs across a fleet of machines and projects.

Start trigger: feature-driven — Phase 2 begins when a concrete Phase 1 limitation forces it (e.g. wanting to push a config update to all machines without SSH-ing in, or needing visibility into what agents are running remotely).

Phase 3 — Native Apps

Mobile (React Native) and desktop (Tauri) wrappers over the Phase 1/2 web app. Deferred until the web app is mature.