Proposal: update specification — restructure monolithic specification.md (47k lines) into docs/specification/ directory #6195

New issue

Open

opened 2026-04-09 17:34:40 +00:00 by HAL9000 · 0 comments

HAL9000 commented

2026-04-09 17:34:40 +00:00

Owner

Proposal: Update Specification — Restructure Monolithic Spec into Split Directory

Current State

docs/specification.md is 47,039 lines (~3.1 MB). This is 15× over the 3,000-line threshold for splitting. The file is difficult to navigate, edit, and review in PRs.

Proposed Structure

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

docs/specification/
├── index.md              # Overview, Glossary, links to all sections
├── cli.md                # CLI Commands (lines 199–18,278) — ~18,100 lines
├── core-concepts.md      # Core Concepts (lines 18,279–28,471) — ~10,200 lines
├── behavior.md           # Behavior (lines 28,472–29,009) — ~540 lines
├── tui.md                # TUI (lines 29,010–30,598) — ~1,590 lines
├── configuration.md      # Configuration (lines 30,599–36,385) — ~5,790 lines
├── examples.md           # Workflow Examples (lines 36,386–43,166) — ~6,780 lines
├── architecture.md       # Architecture (lines 43,167–46,739) — ~3,570 lines
└── milestones.md         # Milestone Plan (lines 46,740–47,039) — ~300 lines

The index.md would contain:

The Overview section (lines 1–68)
The Glossary section (lines 69–198)
A table of contents linking to all sub-documents

What Needs Updating

Create docs/specification/ directory with the 9 files above
Remove docs/specification.md (or keep as redirect/stub pointing to docs/specification/index.md)
Update any cross-references in the repo that point to docs/specification.md
Update mkdocs.yml navigation to reference the split files
Update CONTRIBUTING.md references to the spec file path

Rationale

The spec is 15× over the recommended 3,000-line threshold
Large files are difficult to review in PRs (GitHub/Forgejo truncates diffs)
Splitting by logical section makes it easier for contributors to find and update relevant sections
Smaller files are faster to load and search
The split structure mirrors the existing docs/ directory organization (which already has docs/api/, docs/modules/, docs/development/, etc.)

Risk Assessment

Medium risk: This is a structural change that affects all cross-references to the spec
Mitigation: Keep docs/specification.md as a stub with a redirect notice for backward compatibility
No content changes: This is purely a structural reorganization — no spec content is modified

Scope

Files affected:

docs/specification.md → replaced by docs/specification/ directory
mkdocs.yml — navigation update
CONTRIBUTING.md — path reference update
Any other files referencing docs/specification.md

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

## Proposal: Update Specification — Restructure Monolithic Spec into Split Directory ### Current State `docs/specification.md` is **47,039 lines** (~3.1 MB). This is **15× over** the 3,000-line threshold for splitting. The file is difficult to navigate, edit, and review in PRs. ### Proposed Structure Split into `docs/specification/` directory with logical sub-documents: ``` docs/specification/ ├── index.md # Overview, Glossary, links to all sections ├── cli.md # CLI Commands (lines 199–18,278) — ~18,100 lines ├── core-concepts.md # Core Concepts (lines 18,279–28,471) — ~10,200 lines ├── behavior.md # Behavior (lines 28,472–29,009) — ~540 lines ├── tui.md # TUI (lines 29,010–30,598) — ~1,590 lines ├── configuration.md # Configuration (lines 30,599–36,385) — ~5,790 lines ├── examples.md # Workflow Examples (lines 36,386–43,166) — ~6,780 lines ├── architecture.md # Architecture (lines 43,167–46,739) — ~3,570 lines └── milestones.md # Milestone Plan (lines 46,740–47,039) — ~300 lines ``` The `index.md` would contain: - The Overview section (lines 1–68) - The Glossary section (lines 69–198) - A table of contents linking to all sub-documents ### What Needs Updating 1. **Create `docs/specification/` directory** with the 9 files above 2. **Remove `docs/specification.md`** (or keep as redirect/stub pointing to `docs/specification/index.md`) 3. **Update any cross-references** in the repo that point to `docs/specification.md` 4. **Update `mkdocs.yml`** navigation to reference the split files 5. **Update `CONTRIBUTING.md`** references to the spec file path ### Rationale - The spec is 15× over the recommended 3,000-line threshold - Large files are difficult to review in PRs (GitHub/Forgejo truncates diffs) - Splitting by logical section makes it easier for contributors to find and update relevant sections - Smaller files are faster to load and search - The split structure mirrors the existing `docs/` directory organization (which already has `docs/api/`, `docs/modules/`, `docs/development/`, etc.) ### Risk Assessment - **Medium risk**: This is a structural change that affects all cross-references to the spec - **Mitigation**: Keep `docs/specification.md` as a stub with a redirect notice for backward compatibility - **No content changes**: This is purely a structural reorganization — no spec content is modified ### Scope Files affected: - `docs/specification.md` → replaced by `docs/specification/` directory - `mkdocs.yml` — navigation update - `CONTRIBUTING.md` — path reference update - Any other files referencing `docs/specification.md` --- **Automated by CleverAgents Bot** Supervisor: Spec Evolution | Agent: spec-updater

Rows
Columns