Proposal: restructure docs/specification.md into docs/specification/ directory — monolithic file exceeds 46,000 lines #3395

New issue

Open

opened 2026-04-05 16:24:24 +00:00 by freemo · 0 comments

freemo commented

2026-04-05 16:24:24 +00:00

Owner

Spec Restructure Proposal

Triggered by: Proactive spec scan — Cycle 1 (2026-04-05)

Issue: Specification file has grown to 46,597 lines (3.1 MB)

docs/specification.md is a single monolithic file of 46,597 lines (~3.1 MB). This exceeds the 3,000-line threshold for restructuring into a docs/specification/ directory.

Problems with the current monolithic structure:

Agents and tools that read the spec must download the entire 3.1 MB file even when they only need one section
Line number references in issues and PRs become stale as the file grows
Searching for specific sections requires scanning the entire file
Git diffs for spec changes are hard to review when the file is this large
The file is too large for many tools to process in a single context window

Proposed Restructure

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

docs/specification/
├── index.md                    # Root index with links to all sections
├── overview.md                 # High-level architecture, glossary, design principles
├── data-model.md               # Domain entities: Plan, Action, Decision, Resource, Actor, Tool, Skill, Session, etc.
├── plan-lifecycle.md           # Four-phase lifecycle: Action, Strategize, Execute, Apply
├── cli.md                      # CLI commands reference (agents plan, agents session, etc.)
├── actors.md                   # Actor system: graph topology, YAML schema, multi-actor config
├── context.md                  # ACMS: context strategies, hot/warm/cold context, enrichment
├── tools.md                    # Tool system: MCP, LSP, builtin, agent skills, adapters
├── infrastructure.md           # Infrastructure layer: database, sandbox, registries, adapters
├── lsp.md                      # LSP integration: registry, binding, runtime, lifecycle
├── tui.md                      # TUI: MainScreen, widgets, persona system, command routing
├── server.md                   # Server mode: A2A protocol, REST API, authentication
├── providers.md                # LLM providers: registry, cost tracking, fallback selection
├── configuration.md            # Configuration system: settings, profiles, safety
└── adr-index.md                # Index of Architecture Decision Records

Migration approach:

Extract each logical section from docs/specification.md into its own file
Create docs/specification/index.md with links to all sub-documents
Update mkdocs.yml to reference the new structure
Update any internal cross-references (links between sections)
Keep docs/specification.md as a redirect/stub pointing to docs/specification/index.md for backward compatibility with existing links

Backward compatibility:

Any existing links to docs/specification.md will continue to work via the stub
Line number references in existing issues will become stale, but this is unavoidable and acceptable given the benefits

Scope

docs/specification.md → docs/specification/ (14 sub-documents + index)
mkdocs.yml — update navigation
Any files that reference docs/specification.md directly

Classification

Major restructure — requires human approval before implementation. This is a structural change to the documentation, not a content change.

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

## Spec Restructure Proposal **Triggered by**: Proactive spec scan — Cycle 1 (2026-04-05) --- ### Issue: Specification file has grown to 46,597 lines (3.1 MB) `docs/specification.md` is a single monolithic file of **46,597 lines** (~3.1 MB). This exceeds the 3,000-line threshold for restructuring into a `docs/specification/` directory. **Problems with the current monolithic structure:** - Agents and tools that read the spec must download the entire 3.1 MB file even when they only need one section - Line number references in issues and PRs become stale as the file grows - Searching for specific sections requires scanning the entire file - Git diffs for spec changes are hard to review when the file is this large - The file is too large for many tools to process in a single context window --- ### Proposed Restructure Split `docs/specification.md` into a `docs/specification/` directory with logical sub-documents: ``` docs/specification/ ├── index.md # Root index with links to all sections ├── overview.md # High-level architecture, glossary, design principles ├── data-model.md # Domain entities: Plan, Action, Decision, Resource, Actor, Tool, Skill, Session, etc. ├── plan-lifecycle.md # Four-phase lifecycle: Action, Strategize, Execute, Apply ├── cli.md # CLI commands reference (agents plan, agents session, etc.) ├── actors.md # Actor system: graph topology, YAML schema, multi-actor config ├── context.md # ACMS: context strategies, hot/warm/cold context, enrichment ├── tools.md # Tool system: MCP, LSP, builtin, agent skills, adapters ├── infrastructure.md # Infrastructure layer: database, sandbox, registries, adapters ├── lsp.md # LSP integration: registry, binding, runtime, lifecycle ├── tui.md # TUI: MainScreen, widgets, persona system, command routing ├── server.md # Server mode: A2A protocol, REST API, authentication ├── providers.md # LLM providers: registry, cost tracking, fallback selection ├── configuration.md # Configuration system: settings, profiles, safety └── adr-index.md # Index of Architecture Decision Records ``` **Migration approach:** 1. Extract each logical section from `docs/specification.md` into its own file 2. Create `docs/specification/index.md` with links to all sub-documents 3. Update `mkdocs.yml` to reference the new structure 4. Update any internal cross-references (links between sections) 5. Keep `docs/specification.md` as a redirect/stub pointing to `docs/specification/index.md` for backward compatibility with existing links **Backward compatibility:** - Any existing links to `docs/specification.md` will continue to work via the stub - Line number references in existing issues will become stale, but this is unavoidable and acceptable given the benefits --- ## Scope - `docs/specification.md` → `docs/specification/` (14 sub-documents + index) - `mkdocs.yml` — update navigation - Any files that reference `docs/specification.md` directly ## Classification **Major restructure** — requires human approval before implementation. This is a structural change to the documentation, not a content change. --- **Automated by CleverAgents Bot** Supervisor: Spec Evolution | Agent: ca-spec-updater

Rows
Columns