Proposal: update specification — restructure monolithic spec into docs/specification/ directory #3557

Open
opened 2026-04-05 19:35:40 +00:00 by freemo · 3 comments
Owner

Proposal: Specification Restructure

Type: Spec structural change (requires human approval before implementation)

What Changed in the Implementation

No specific implementation change triggered this — this is a proactive structural improvement identified during spec-updater cycle 1 (2026-04-05).

Current State

docs/specification.md is a single monolithic file of 46,597 lines. The spec-updater guidelines specify that when the spec exceeds ~3,000 lines, it should be restructured into a docs/specification/ directory with logical sub-documents.

Proposed Change

Restructure docs/specification.md into a docs/specification/ directory with the following logical sub-documents:

docs/specification/
├── index.md              # Root index with links to all sections
├── overview.md           # Overview, standards alignment, glossary
├── cli-commands.md       # Full CLI command reference (currently the largest section)
├── architecture.md       # System architecture, layers, components
├── data-model.md         # Domain models, database schema
├── plan-lifecycle.md     # Plan phases, decisions, corrections
├── acms.md               # Advanced Context Management System
├── lsp-integration.md    # LSP integration details
├── a2a-protocol.md       # A2A protocol details
├── server-architecture.md # Server and client architecture
└── security.md           # Safety profiles, sandbox, checkpoints

Rationale

  1. Navigability: A 46,597-line file is extremely difficult to navigate, search, and maintain
  2. Parallel editing: Multiple agents working on different spec sections will have fewer merge conflicts
  3. Spec-updater guidelines: The CONTRIBUTING.md and spec-updater instructions explicitly call for this split when the spec exceeds ~3,000 lines
  4. Tooling: Most editors and diff tools struggle with files this large

Scope

  • All sections of docs/specification.md (46,597 lines)
  • mkdocs.yml navigation configuration
  • Any cross-references within the spec (internal links)
  • Any external references to docs/specification.md in other docs

Implementation Notes

  • The split should be purely structural — no content changes
  • All existing anchors/links should be preserved or redirected
  • The docs/specification/index.md should serve as the entry point
  • MkDocs navigation in mkdocs.yml will need updating

Current vs Proposed

Current: Single file docs/specification.md (46,597 lines)

Proposed: Directory docs/specification/ with ~10 sub-documents averaging ~4,600 lines each


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

## Proposal: Specification Restructure **Type:** Spec structural change (requires human approval before implementation) ### What Changed in the Implementation No specific implementation change triggered this — this is a proactive structural improvement identified during spec-updater cycle 1 (2026-04-05). ### Current State `docs/specification.md` is a **single monolithic file of 46,597 lines**. The spec-updater guidelines specify that when the spec exceeds ~3,000 lines, it should be restructured into a `docs/specification/` directory with logical sub-documents. ### Proposed Change Restructure `docs/specification.md` into a `docs/specification/` directory with the following logical sub-documents: ``` docs/specification/ ├── index.md # Root index with links to all sections ├── overview.md # Overview, standards alignment, glossary ├── cli-commands.md # Full CLI command reference (currently the largest section) ├── architecture.md # System architecture, layers, components ├── data-model.md # Domain models, database schema ├── plan-lifecycle.md # Plan phases, decisions, corrections ├── acms.md # Advanced Context Management System ├── lsp-integration.md # LSP integration details ├── a2a-protocol.md # A2A protocol details ├── server-architecture.md # Server and client architecture └── security.md # Safety profiles, sandbox, checkpoints ``` ### Rationale 1. **Navigability**: A 46,597-line file is extremely difficult to navigate, search, and maintain 2. **Parallel editing**: Multiple agents working on different spec sections will have fewer merge conflicts 3. **Spec-updater guidelines**: The CONTRIBUTING.md and spec-updater instructions explicitly call for this split when the spec exceeds ~3,000 lines 4. **Tooling**: Most editors and diff tools struggle with files this large ### Scope - All sections of `docs/specification.md` (46,597 lines) - `mkdocs.yml` navigation configuration - Any cross-references within the spec (internal links) - Any external references to `docs/specification.md` in other docs ### Implementation Notes - The split should be purely structural — no content changes - All existing anchors/links should be preserved or redirected - The `docs/specification/index.md` should serve as the entry point - MkDocs navigation in `mkdocs.yml` will need updating ### Current vs Proposed **Current:** Single file `docs/specification.md` (46,597 lines) **Proposed:** Directory `docs/specification/` with ~10 sub-documents averaging ~4,600 lines each --- **Automated by CleverAgents Bot** Supervisor: Spec Evolution | Agent: ca-spec-updater
Author
Owner

This issue is a proposal awaiting human review (needs feedback label). I will not modify its state — a human must approve or reject it.

Summary for human reviewer: The spec-updater proposes restructuring the monolithic docs/specification.md (46,597 lines) into a docs/specification/ directory with ~10 sub-documents. This is a structural-only change with no content modifications. The rationale is sound — navigability, reduced merge conflicts, and alignment with spec-updater guidelines. However, this is a significant structural change that affects cross-references, MkDocs configuration, and all agents that reference spec line numbers.


Automated by CleverAgents Bot
Supervisor: Human Liaison | Agent: ca-human-liaison

This issue is a proposal awaiting human review (`needs feedback` label). I will not modify its state — a human must approve or reject it. **Summary for human reviewer:** The spec-updater proposes restructuring the monolithic `docs/specification.md` (46,597 lines) into a `docs/specification/` directory with ~10 sub-documents. This is a structural-only change with no content modifications. The rationale is sound — navigability, reduced merge conflicts, and alignment with spec-updater guidelines. However, this is a significant structural change that affects cross-references, MkDocs configuration, and all agents that reference spec line numbers. --- **Automated by CleverAgents Bot** Supervisor: Human Liaison | Agent: ca-human-liaison
Author
Owner

@HAL9000 approved, but aggressively check for duplicates as I think there is more than one duplicate of this ticket.

@HAL9000 approved, but aggressively check for duplicates as I think there is more than one duplicate of this ticket.
Owner

Issue triaged by project owner — approved by @freemo (2026-04-08):

  • State: Verified — @freemo explicitly approved this proposal. Duplicate check performed: #4749 was a duplicate and has been closed.
  • Priority: Medium — Important structural improvement but not blocking any milestone work. The spec is functional as-is.
  • Milestone: v3.5.0 — Autonomy Hardening milestone (documentation infrastructure is part of this milestone's scope)
  • Story Points: 8 (XL) — Splitting a 46,000+ line file into 10+ sub-documents with preserved cross-references, MkDocs navigation updates, and all agent reference updates is a 2-4 day effort
  • MoSCoW: Should Have — The spec-updater guidelines explicitly call for this split at >3,000 lines. It improves maintainability and reduces merge conflicts. Not blocking but important for long-term project health.
  • Parent Epic: #369 (Epic: Large Project Autonomy & Context) — spec maintainability directly enables autonomous agents to work effectively with the spec

Duplicate check: #4749 was a duplicate (same proposal, created 2026-04-08). Closed as duplicate.


Automated by CleverAgents Bot
Supervisor: Project Owner | Agent: project-owner

Issue triaged by project owner — approved by @freemo (2026-04-08): - **State**: Verified — @freemo explicitly approved this proposal. Duplicate check performed: #4749 was a duplicate and has been closed. - **Priority**: Medium — Important structural improvement but not blocking any milestone work. The spec is functional as-is. - **Milestone**: v3.5.0 — Autonomy Hardening milestone (documentation infrastructure is part of this milestone's scope) - **Story Points**: 8 (XL) — Splitting a 46,000+ line file into 10+ sub-documents with preserved cross-references, MkDocs navigation updates, and all agent reference updates is a 2-4 day effort - **MoSCoW**: Should Have — The spec-updater guidelines explicitly call for this split at >3,000 lines. It improves maintainability and reduces merge conflicts. Not blocking but important for long-term project health. - **Parent Epic**: #369 (Epic: Large Project Autonomy & Context) — spec maintainability directly enables autonomous agents to work effectively with the spec **Duplicate check**: #4749 was a duplicate (same proposal, created 2026-04-08). Closed as duplicate. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: project-owner
HAL9000 added this to the v3.5.0 milestone 2026-04-08 20:05:29 +00:00
Sign in to join this conversation.
No milestone
No project
No assignees
2 participants
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Blocks
#369 Epic: Large Project Autonomy & Context
cleveragents/cleveragents-core
Reference
cleveragents/cleveragents-core#3557
No description provided.