cleveragents/cleveragents-core

Fork 3

Proposal: update specification — restructure monolithic docs/specification.md into docs/specification/ directory #1466

New issue

Open

opened 2026-04-02 19:04:29 +00:00 by freemo · 2 comments

freemo commented

2026-04-02 19:04:29 +00:00

Owner

Spec Restructure Proposal

Triggered by: Routine spec monitoring — docs/specification.md has grown to 46,563 lines, far exceeding the 3,000-line threshold for splitting.

Problem

docs/specification.md is a single 46,563-line file. This causes:

Slow loading and editing in all tools
Difficult navigation — finding a section requires searching through 46K lines
High merge conflict risk — any two concurrent spec edits touch the same file
Poor readability — the file covers CLI commands, core concepts, architecture, ACMS, TUI, examples, and more in one monolith

Proposed Structure

Split into docs/specification/ directory with logical sub-documents:

docs/specification/
├── index.md              # Root index with links to all sections + overview
├── overview.md           # §Overview, §Glossary, §Standards Alignment
├── cli.md                # §CLI Commands (all agents * commands) — ~18,000 lines
├── core-concepts.md      # §Core Concepts (Plan, Actors, Resources, etc.)
├── tui.md                # §TUI (all TUI sections) — ~5,000 lines
├── architecture.md       # §Architecture Overview, §Technical Stack, §DI, §Data Validation
├── acms.md               # §ACMS (Advanced Context Management System) — ~2,500 lines
├── storage.md            # §Storage and Persistence
├── observability.md      # §Observability (Events, Logging, Metrics)
├── security.md           # §Security Model
├── extensibility.md      # §Extensibility
└── examples.md           # §Examples (all 18 workflow examples) — ~7,000 lines

The index.md becomes the new entry point, replacing docs/specification.md. It contains:

The Overview section (§Overview, §Glossary)
A navigation table linking to all sub-documents
Cross-reference notes for ADRs

Migration Plan

Create docs/specification/ directory
Split docs/specification.md into sub-documents by top-level ## sections
Update mkdocs.yml nav to reference the new structure
Update any internal cross-references ([text](#anchor) → [text](sub-doc.md#anchor))
Add a redirect or note in the old docs/specification.md pointing to docs/specification/index.md
Update CONTRIBUTING.md references to docs/specification.md
Update ca-ref-reader agent to read from the new split structure

Impact

All existing spec content is preserved — no deletions
ADR files in docs/adr/ are unaffected
The docs/timeline.md is unaffected
Git history for individual sections becomes cleaner (changes to CLI spec don't touch ACMS spec)

Scope

docs/specification.md → docs/specification/ (split into ~11 files)
mkdocs.yml (nav update)
CONTRIBUTING.md (reference update)
.opencode/agents/ca-ref-reader.md (if it references the monolithic file path)

Automated by CleverAgents Bot
Supervisor: Spec Evolution | Agent: ca-spec-updater

## Spec Restructure Proposal **Triggered by**: Routine spec monitoring — `docs/specification.md` has grown to **46,563 lines**, far exceeding the 3,000-line threshold for splitting. --- ## Problem `docs/specification.md` is a single 46,563-line file. This causes: - Slow loading and editing in all tools - Difficult navigation — finding a section requires searching through 46K lines - High merge conflict risk — any two concurrent spec edits touch the same file - Poor readability — the file covers CLI commands, core concepts, architecture, ACMS, TUI, examples, and more in one monolith ## Proposed Structure Split into `docs/specification/` directory with logical sub-documents: ``` docs/specification/ ├── index.md # Root index with links to all sections + overview ├── overview.md # §Overview, §Glossary, §Standards Alignment ├── cli.md # §CLI Commands (all agents * commands) — ~18,000 lines ├── core-concepts.md # §Core Concepts (Plan, Actors, Resources, etc.) ├── tui.md # §TUI (all TUI sections) — ~5,000 lines ├── architecture.md # §Architecture Overview, §Technical Stack, §DI, §Data Validation ├── acms.md # §ACMS (Advanced Context Management System) — ~2,500 lines ├── storage.md # §Storage and Persistence ├── observability.md # §Observability (Events, Logging, Metrics) ├── security.md # §Security Model ├── extensibility.md # §Extensibility └── examples.md # §Examples (all 18 workflow examples) — ~7,000 lines ``` The `index.md` becomes the new entry point, replacing `docs/specification.md`. It contains: - The Overview section (§Overview, §Glossary) - A navigation table linking to all sub-documents - Cross-reference notes for ADRs ## Migration Plan 1. Create `docs/specification/` directory 2. Split `docs/specification.md` into sub-documents by top-level `##` sections 3. Update `mkdocs.yml` nav to reference the new structure 4. Update any internal cross-references (`[text](#anchor)` → `[text](sub-doc.md#anchor)`) 5. Add a redirect or note in the old `docs/specification.md` pointing to `docs/specification/index.md` 6. Update `CONTRIBUTING.md` references to `docs/specification.md` 7. Update `ca-ref-reader` agent to read from the new split structure ## Impact - All existing spec content is preserved — no deletions - ADR files in `docs/adr/` are unaffected - The `docs/timeline.md` is unaffected - Git history for individual sections becomes cleaner (changes to CLI spec don't touch ACMS spec) ## Scope - `docs/specification.md` → `docs/specification/` (split into ~11 files) - `mkdocs.yml` (nav update) - `CONTRIBUTING.md` (reference update) - `.opencode/agents/ca-ref-reader.md` (if it references the monolithic file path) --- **Automated by CleverAgents Bot** Supervisor: Spec Evolution | Agent: ca-spec-updater

freemo added the

labels

2026-04-02 19:04:33 +00:00

freemo referenced this issue

2026-04-02 19:04:55 +00:00

[SPEC-UPDATER] Session State — ca-spec-updater #1461

freemo self-assigned this

2026-04-02 19:25:12 +00:00

freemo referenced this issue

2026-04-02 19:28:42 +00:00

[SPEC-UPDATER] Session State — ca-spec-updater #1461

freemo added

and removed

labels

2026-04-02 19:34:46 +00:00

freemo commented

2026-04-02 19:34:54 +00:00

Author

Owner

Approved

freemo added this to the v3.8.0 milestone

2026-04-02 23:02:37 +00:00

freemo commented

2026-04-02 23:23:21 +00:00

Author

Owner

Milestone compliance fix applied:

Assigned to milestone: v3.8.0
Reason: Per CONTRIBUTING.md, non-Epic/non-Legendary issues in State/Verified or later MUST have a milestone. This issue was in State/Verified without a milestone and has been assigned to v3.8.0 as the most appropriate active milestone.

Automated by CleverAgents Bot
Supervisor: Backlog Grooming | Agent: ca-backlog-groomer

Milestone compliance fix applied: - Assigned to milestone: `v3.8.0` - Reason: Per CONTRIBUTING.md, non-Epic/non-Legendary issues in `State/Verified` or later MUST have a milestone. This issue was in `State/Verified` without a milestone and has been assigned to `v3.8.0` as the most appropriate active milestone. --- **Automated by CleverAgents Bot** Supervisor: Backlog Grooming | Agent: ca-backlog-groomer

freemo referenced this issue

2026-04-02 23:24:09 +00:00

[Automated] Backlog Groomer Session State — v3.7.0 #1463

freemo removed the

labels

2026-04-03 00:28:24 +00:00