Proposal: update specification — restructure monolithic docs/specification.md (46,564 lines) into docs/specification/ directory #2521

New issue

Open

opened 2026-04-03 18:44:56 +00:00 by freemo · 1 comment

freemo commented

2026-04-03 18:44:56 +00:00

Owner

Spec Update Proposal

Triggered By

Proactive structural scan — no specific merged PR triggered this. The specification has grown to 46,564 lines / 3.1 MB, far exceeding the ~3,000 line threshold for restructuring.

Change: Monolithic → Split Specification

Current State

docs/specification.md is a single file with 46,564 lines and 3.1 MB of content. This makes it:

Impossible to read in full in a single context window
Difficult to navigate and maintain
Slow to load in editors and documentation tools
Hard to review in PRs (diffs are enormous)
Impossible to search efficiently

Proposed Structure

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

docs/specification/
├── index.md                    # Overview, glossary, table of contents, links to all sections
├── architecture.md             # High-level architecture, layered design, core concepts
├── glossary.md                 # All glossary entries (Plan, Action, Resource, etc.)
├── cli/
│   ├── index.md                # CLI command synopsis and overview
│   ├── plan.md                 # agents plan * commands
│   ├── resource.md             # agents resource * commands
│   ├── actor.md                # agents actor * commands
│   ├── skill.md                # agents skill * commands
│   ├── tool.md                 # agents tool * commands
│   ├── project.md              # agents project * commands
│   ├── session.md              # agents session * commands
│   ├── config.md               # agents config * commands
│   └── system.md               # agents system * commands
├── plan-lifecycle.md           # Plan lifecycle, phases, decision tree, corrections
├── projects-resources.md       # Projects, resources, DAG, resource types
├── actors-sessions.md          # Actors, sessions, LangGraph integration
├── skills-tools.md             # Skills, tools, MCP, Agent Skills
├── a2a-protocol.md             # A2A wire format, extension methods, streaming
├── acms.md                     # ACMS, UKO, CRP, context strategies
├── storage-persistence.md      # Database schema, storage model, migrations
├── configuration.md            # Configuration system, config.toml, env vars
├── tui.md                      # TUI architecture, widgets, persona system
├── server-mode.md              # Server mode, multi-user, authentication
├── observability.md            # Logging, tracing, metrics
├── security.md                 # Security, sandbox, permissions
└── extensibility.md            # Custom resource types, strategies, plugins

Migration Approach

Create docs/specification/ directory
Split docs/specification.md into sub-documents by section headers
Create docs/specification/index.md with overview and cross-links
Update mkdocs.yml navigation to reference the new structure
Add a redirect or note in the old docs/specification.md pointing to the new location (or replace it with a stub that links to docs/specification/index.md)
Update any internal cross-references (e.g., [Plan Lifecycle](#plan-lifecycle) → [Plan Lifecycle](plan-lifecycle.md))

Rationale

The specification has grown organically to 46,564 lines. This is well beyond the ~3,000 line threshold at which a single-file spec becomes unmanageable. Splitting it into logical sub-documents:

Makes each section independently reviewable in PRs
Allows targeted updates without touching unrelated sections
Enables efficient navigation in editors and documentation tools
Reduces context window pressure for AI agents reading the spec
Follows the pattern already established by docs/reference/ and docs/adr/

Scope

Section	Change Type
`docs/specification.md`	Split into `docs/specification/` directory
`mkdocs.yml`	Update navigation to reference new structure
All internal cross-references	Update anchor links to file-relative links

Awaiting human approval before any branch or PR is created.

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

## Spec Update Proposal ### Triggered By Proactive structural scan — no specific merged PR triggered this. The specification has grown to **46,564 lines / 3.1 MB**, far exceeding the ~3,000 line threshold for restructuring. --- ## Change: Monolithic → Split Specification ### Current State `docs/specification.md` is a single file with **46,564 lines** and **3.1 MB** of content. This makes it: - Impossible to read in full in a single context window - Difficult to navigate and maintain - Slow to load in editors and documentation tools - Hard to review in PRs (diffs are enormous) - Impossible to search efficiently ### Proposed Structure Restructure into `docs/specification/` directory with logical sub-documents: ``` docs/specification/ ├── index.md # Overview, glossary, table of contents, links to all sections ├── architecture.md # High-level architecture, layered design, core concepts ├── glossary.md # All glossary entries (Plan, Action, Resource, etc.) ├── cli/ │ ├── index.md # CLI command synopsis and overview │ ├── plan.md # agents plan * commands │ ├── resource.md # agents resource * commands │ ├── actor.md # agents actor * commands │ ├── skill.md # agents skill * commands │ ├── tool.md # agents tool * commands │ ├── project.md # agents project * commands │ ├── session.md # agents session * commands │ ├── config.md # agents config * commands │ └── system.md # agents system * commands ├── plan-lifecycle.md # Plan lifecycle, phases, decision tree, corrections ├── projects-resources.md # Projects, resources, DAG, resource types ├── actors-sessions.md # Actors, sessions, LangGraph integration ├── skills-tools.md # Skills, tools, MCP, Agent Skills ├── a2a-protocol.md # A2A wire format, extension methods, streaming ├── acms.md # ACMS, UKO, CRP, context strategies ├── storage-persistence.md # Database schema, storage model, migrations ├── configuration.md # Configuration system, config.toml, env vars ├── tui.md # TUI architecture, widgets, persona system ├── server-mode.md # Server mode, multi-user, authentication ├── observability.md # Logging, tracing, metrics ├── security.md # Security, sandbox, permissions └── extensibility.md # Custom resource types, strategies, plugins ``` ### Migration Approach 1. Create `docs/specification/` directory 2. Split `docs/specification.md` into sub-documents by section headers 3. Create `docs/specification/index.md` with overview and cross-links 4. Update `mkdocs.yml` navigation to reference the new structure 5. Add a redirect or note in the old `docs/specification.md` pointing to the new location (or replace it with a stub that links to `docs/specification/index.md`) 6. Update any internal cross-references (e.g., `[Plan Lifecycle](#plan-lifecycle)` → `[Plan Lifecycle](plan-lifecycle.md)`) ### Rationale The specification has grown organically to 46,564 lines. This is well beyond the ~3,000 line threshold at which a single-file spec becomes unmanageable. Splitting it into logical sub-documents: - Makes each section independently reviewable in PRs - Allows targeted updates without touching unrelated sections - Enables efficient navigation in editors and documentation tools - Reduces context window pressure for AI agents reading the spec - Follows the pattern already established by `docs/reference/` and `docs/adr/` --- ## Scope | Section | Change Type | |---------|-------------| | `docs/specification.md` | Split into `docs/specification/` directory | | `mkdocs.yml` | Update navigation to reference new structure | | All internal cross-references | Update anchor links to file-relative links | --- **Awaiting human approval before any branch or PR is created.** --- **Automated by CleverAgents Bot** Supervisor: Spec Evolution | Agent: ca-spec-updater

Rows
Columns