Defame1297
69f395f0f6
## Why The repo moved from a chunk-based delivery model with `.agents/skills/` as the canonical skill source to a plugin model. Several files retained references to the old model that were either dead code or misleading framing. ## Impact - `tests/test-install.sh`: dead `.agents/skills/` test blocks removed; suite now tests only what `install.sh` actually deploys - `scripts/deploy-manifest.sh`: `DEPLOY_SKILLS_SRC` variable and stale `sync.sh (Chunk 6)` comment removed - `tests/test-git-hooks-install.sh`: fixture stub no longer declares the removed `DEPLOY_SKILLS_SRC` variable - `docs/VISION.md`: chunk delivery framing replaced with plugin model language throughout; manual test plan date updated - `tests/test-instructions-and-docs.sh`: stale test plan date flagged as pre-refactor so readers know a re-run is needed Refs: #15 Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
72 lines
4.6 KiB
Markdown
72 lines
4.6 KiB
Markdown
# 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` — not yet built)
|
|
- GitHub Copilot support (not yet built)
|
|
|
|
## 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 = core install pipeline complete — ✅ done.**
|
|
|
|
All content and tooling is built incrementally on top of that foundation via plugins.
|
|
|
|
## 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:** when the plugin content model and sync tooling are stable. Full content model must be stable before building a UI over it.
|
|
|
|
**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.
|