0014 — docs/spec/ and VISION.md refactor #42

New Issue

Claude · 2026-06-28T17:12:27Z

Claude commented

2026-06-28 17:12:27 +00:00

What to build

Introduce docs/spec/ as the living spec layer for this repo, and refactor docs/VISION.md to goals and intent only.

The distinction:

docs/VISION.md — purpose, goals, non-goals, long-term roadmap. Stable. Describes what the repo is for and where it is going.
docs/spec/overview.md — current deployed state. What is working today. Updated in the same PR as any behavior change.
docs/spec/architecture.md — current directory structure, install behavior, provider model, deployment pipeline, as-deployed. Replaces the architecture section of VISION.md.

1. Refactor VISION.md

Remove the Architecture section (directory structure diagram, content deployment model, governance layer description, provider model, this repo's own CLAUDE.md description, architectural decisions pointer). These describe current state, not intent. Move this content to docs/spec/architecture.md.

Keep in VISION.md: Purpose, Goals, Non-Goals, V1 Definition, Long-term Management Application vision.

2. Create docs/spec/overview.md

Current state snapshot: what chunks are complete, what is deployed, what works end-to-end. This is the "what does this repo do right now" document. Updated at the close of each chunk.

3. Create docs/spec/architecture.md

Current architecture: directory structure, install pipeline, provider adapter model, content deployment model, governance layer, CLAUDE.md two-tier model. Sourced from the VISION.md architecture section but written as current state, not design intent. Keep diagrams and tables.

4. Update CONTEXT.md docs convention

Add docs/spec/<slug>.md to the docs naming convention. Describe when spec files are updated (same PR as any behavior change).

5. Update CLAUDE.md key documents section

Add docs/spec/ to the list of documents to read at session start, alongside CONTEXT.md, VISION.md.

Acceptance criteria

docs/spec/overview.md exists with current state of the repo
docs/spec/architecture.md exists with current architecture content (sourced from VISION.md architecture section)
docs/VISION.md contains only Purpose, Goals, Non-Goals, V1 Definition, and Management Application vision
No content is lost — everything from the removed VISION.md sections appears in spec files
CONTEXT.md docs convention references docs/spec/
CLAUDE.md key documents section references docs/spec/

Blocked by

None.

## What to build Introduce `docs/spec/` as the living spec layer for this repo, and refactor `docs/VISION.md` to goals and intent only. **The distinction:** - `docs/VISION.md` — purpose, goals, non-goals, long-term roadmap. Stable. Describes what the repo is for and where it is going. - `docs/spec/overview.md` — current deployed state. What is working today. Updated in the same PR as any behavior change. - `docs/spec/architecture.md` — current directory structure, install behavior, provider model, deployment pipeline, as-deployed. Replaces the architecture section of VISION.md. **1. Refactor VISION.md** Remove the Architecture section (directory structure diagram, content deployment model, governance layer description, provider model, this repo's own CLAUDE.md description, architectural decisions pointer). These describe current state, not intent. Move this content to `docs/spec/architecture.md`. Keep in VISION.md: Purpose, Goals, Non-Goals, V1 Definition, Long-term Management Application vision. **2. Create docs/spec/overview.md** Current state snapshot: what chunks are complete, what is deployed, what works end-to-end. This is the "what does this repo do right now" document. Updated at the close of each chunk. **3. Create docs/spec/architecture.md** Current architecture: directory structure, install pipeline, provider adapter model, content deployment model, governance layer, CLAUDE.md two-tier model. Sourced from the VISION.md architecture section but written as current state, not design intent. Keep diagrams and tables. **4. Update CONTEXT.md docs convention** Add `docs/spec/<slug>.md` to the docs naming convention. Describe when spec files are updated (same PR as any behavior change). **5. Update CLAUDE.md key documents section** Add `docs/spec/` to the list of documents to read at session start, alongside CONTEXT.md, VISION.md. ## Acceptance criteria - [ ] `docs/spec/overview.md` exists with current state of the repo - [ ] `docs/spec/architecture.md` exists with current architecture content (sourced from VISION.md architecture section) - [ ] `docs/VISION.md` contains only Purpose, Goals, Non-Goals, V1 Definition, and Management Application vision - [ ] No content is lost — everything from the removed VISION.md sections appears in spec files - [ ] CONTEXT.md docs convention references `docs/spec/` - [ ] CLAUDE.md key documents section references `docs/spec/` ## Blocked by None.

Claude added this to the Legacy / Triage milestone 2026-06-28 17:12:27 +00:00

Claude closed this issue

2026-06-28 17:12:30 +00:00

Claude referenced this issue

2026-06-28 17:14:45 +00:00

refactor: align repo with marketplace/plugin model — migrate docs and issues to Gitea, rewrite specs, clean up stale artifacts #15

Defame1297 referenced this issue from a commit

2026-09-01 13:09:28 +00:00

fix(gitea): restore the withLines exception and route rename_branch through the orchestrator

Sign in to join this conversation.