Defame1297
f91babcacd
Why: AGENTS.md's Structure bullet restated apm-install mechanics already owned by docs/spec/architecture.md:24 and README.md:55, and docs/VISION.md carried stack, framework and deployment choices for a product that lives in a separate repo. Implementation notes: AGENTS.md keeps two actionable one-liners plus pointers to the README layout table and architecture.md, preserving the session rule that .claude/skills/ and .claude/agents/ are install output and must not be edited. VISION.md's Phase 1 Architecture block becomes a one-line scope statement; the "Mobile/desktop (Phase 3)" line is dropped as an intra-file duplicate of the Phase 3 section. Impact: no behaviour change. README.md and docs/spec/architecture.md are untouched -- the finding's premise was inflated, and architecture.md had already been differentiated in a way it documents in the file itself. Refs: SIMPLIFICATION-AUDIT.md finding 32 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01YR2CjVumUbEGWcMikcoXBD
64 lines
3.9 KiB
Markdown
64 lines
3.9 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.
|
|
|
|
**Scope:** self-hosted first, cloud-hosted option later; solo-first, with a multi-user-ready data model from day one. The git repo stays the source of truth. Stack, framework and deployment choices belong to that product's own repo, not here.
|
|
|
|
**Start trigger:** when the plugin content model and sync tooling are stable. Full content model must be stable before building a UI over it.
|
|
|
|
### 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.
|