From f91babcacd8b47b1a552598995ae49604a33ec49 Mon Sep 17 00:00:00 2001 From: Defame1297 Date: Mon, 14 Sep 2026 20:31:40 +0000 Subject: [PATCH] docs: dedupe structure and stack descriptions (finding 32) 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 Claude-Session: https://claude.ai/code/session_01YR2CjVumUbEGWcMikcoXBD --- AGENTS.md | 6 ++++-- docs/VISION.md | 10 +--------- 2 files changed, 5 insertions(+), 11 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index b0375f1..8a520a3 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -6,8 +6,10 @@ This file carries only what applies to **every** session. Setup, prerequisites, ## Structure -- `plugins/` — six installable plugin units, each an apm package (`apm.yml` + `.apm/`). Root `apm.yml` declares all six as `dependencies.apm`; `apm install` deploys them into `.claude/skills/` and `.claude/agents/`, both gitignored install output. -- `providers/claude-code/` — Claude Code adapter, deployed to `~/.claude/` via `scripts/install.sh`. +- `plugins//.apm/` is the only authoring source for plugin content. `.claude/skills/` and `.claude/agents/` are gitignored `apm install` output — never edit them. +- `providers/claude-code/` is the Claude Code adapter, deployed to `~/.claude/` by `scripts/install.sh`. + +Repo layout table: `README.md`. Deployment mechanics and plugin boundaries: `docs/spec/architecture.md`. ## Prefer plugin skills over raw shell diff --git a/docs/VISION.md b/docs/VISION.md index b605996..4025d2c 100644 --- a/docs/VISION.md +++ b/docs/VISION.md @@ -48,18 +48,10 @@ Browse, edit, and configure AI development config through a proper product UI. **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 +**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. -**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.