140 lines
9.0 KiB
Markdown
140 lines
9.0 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` comes in chunk 6)
|
|
- GitHub Copilot support (chunk 7)
|
|
|
|
## Architecture
|
|
|
|
### Layered model
|
|
|
|
```
|
|
this repo (global defaults)
|
|
├── install.sh → ~/.agents/skills/ (cross-client skills, all providers)
|
|
└── install.sh → ~/.claude/ (Claude Code config + content)
|
|
|
|
project repo (local overrides)
|
|
└── .claude/settings.json, CLAUDE.md (overrides global)
|
|
```
|
|
|
|
Projects consume from this repo by pulling updates via `sync.sh` (chunk 6). Until then, install is a one-time manual step.
|
|
|
|
### Directory structure
|
|
|
|
```
|
|
ai-development/
|
|
├── docs/ # Workflow artifacts and issues (prd/, ard/, bug/, notes/, adr/, issues/) + research/ (raw research audit trail)
|
|
├── .agents/ # Agent Skills standard location (provider-agnostic)
|
|
│ └── skills/ # SKILL.md files — read natively by Claude Code, Copilot, Cursor, etc.
|
|
├── core/ # Provider-agnostic source of truth
|
|
│ ├── instructions/ # AI behavior definitions (plain markdown)
|
|
│ ├── agents/ # Agent role definitions
|
|
│ ├── workflows/ # Workflow definitions
|
|
│ └── prompts/ # Reusable prompt templates
|
|
├── providers/ # Provider-specific adapters
|
|
│ ├── claude-code/ # CLAUDE.md, settings.json
|
|
│ └── copilot/ # copilot-instructions.md, hooks, agents adapter
|
|
├── templates/ # Project scaffolding templates
|
|
├── skills-lock.json # Tracks installed skills and their sources/hashes
|
|
└── scripts/
|
|
├── deploy-manifest.sh # Source→target mappings; sourced by install.sh and sync.sh
|
|
├── install.sh # Deploys to ~/.agents/skills/, ~/.claude/, etc.
|
|
├── sync.sh # Pulls updates into an existing project
|
|
└── init-project.sh # Bootstraps a new or existing project
|
|
```
|
|
|
|
### Content deployment model
|
|
|
|
`install.sh` is a **deployer**, not a composer. It does not concatenate content into a single file. Instead:
|
|
|
|
- `.agents/skills/` → `~/.agents/skills/` — user-level cross-client skills (read by Claude Code, Copilot, Cursor, etc.)
|
|
- `core/` → `~/.claude/core/` — workflows, prompts, agent definitions; agent reads on demand
|
|
- `providers/claude-code/settings.json` → `~/.claude/settings.json`
|
|
- Writes a lean `~/.claude/CLAUDE.md` — universal rules only, plus pointers to where detailed content lives
|
|
|
|
`~/.claude/CLAUDE.md` is an index, not a content dump. It tells the agent where things are; the agent pulls what it needs using its Read tool. This keeps context size minimal — only what is needed for every session is loaded upfront.
|
|
|
|
### Governance layer
|
|
|
|
`core/instructions/governance.md` is the always-on governance instruction file. Unlike the on-demand instruction files in the content index, governance.md is loaded into every Claude session via `@import` in `providers/claude-code/CLAUDE.md`. This is a technical guarantee, not a behavioural instruction — `@import` causes Claude Code to expand and load the file at launch, before any interaction begins.
|
|
|
|
The governance layer has two phases:
|
|
- **Phase 1** (complete): instruction and documentation layer — `governance.md` loaded via `@import`; `docs/ai-constitution.md` and `docs/HUMANS.md` as human-facing reference; `CONTEXT.md` extended with governance domain language.
|
|
- **Phase 2** (Chunk 6): deterministic enforcement layer — pre-commit hooks, CI gates, secret scanning, licence scanning. Specified in `docs/research/governance_principles/CONTROLS.md`.
|
|
|
|
### This repo's own CLAUDE.md
|
|
|
|
This repo has a `CLAUDE.md` at its root — a meta file that tells Claude how to work *in this repo itself* (structure, conventions, how to add skills/workflows/providers). This is distinct from `providers/claude-code/CLAUDE.md`, which is the global config deployed to `~/.claude/` for use across all projects. Do not conflate the two.
|
|
|
|
### Provider model
|
|
|
|
`core/` is never tool-specific. `providers/` is never shared. When adding a new provider, write an adapter in `providers/<name>/` that translates core content into the tool's expected format and location. The core content itself does not change.
|
|
|
|
Skills are the strongest shared primitive — both Claude Code and GitHub Copilot use the `SKILL.md` format and follow the [Agent Skills open standard](https://agentskills.io).
|
|
|
|
### Architectural decisions
|
|
|
|
Key hard-to-reverse decisions are recorded as ADRs in `docs/adr/`. See the index there for rationale on choices like the pull distribution model, copy-not-symlink coupling, and the two-tier CLAUDE.md structure.
|
|
|
|
## 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.
|