Proposal: update specification — TUI preset cycling key binding (ctrl+t vs ctrl+tab) and spec size restructure #4978

Open
opened 2026-04-08 23:42:39 +00:00 by freemo · 2 comments
Owner

Specification Update Proposal

Triggered by: Proactive spec scan (cycle 1, new session) comparing src/cleveragents/tui/app.py and src/cleveragents/tui/widgets/help_panel_overlay.py against spec section "TUI"


What Changed in the Implementation

Two additional discrepancies were found during the initial proactive scan that were not covered by proposal #4954:

  1. The TUI preset cycling key binding uses ctrl+t in the implementation, but the spec says ctrl+tab.
  2. The specification file (docs/specification.md) is 46,738 lines — well over the 3,000-line threshold for splitting into a docs/specification/ directory.

Spec Sections Needing Updates

1. Preset Cycling Key Binding — ctrl+t vs ctrl+tab

Current spec text (multiple locations):

  • Line 29232: "Argument presets — named argument overrides cycled with ctrl+tab"
  • Line 29262: "ctrl+tab cycles through the current persona's argument presets"
  • Line 29077 (footer mockup): ctrl+tab Preset
  • Line 29799: ctrl+tab Cycle to next argument preset
  • Line 30405: | ctrl+tab | Cycle to next argument preset |

What the implementation actually uses (src/cleveragents/tui/app.py, src/cleveragents/tui/widgets/help_panel_overlay.py):

BINDINGS: ClassVar[list[tuple[str, str, str]]] = [
    ("ctrl+q", "quit", "Quit"),
    ("f1", "help", "Help"),
    ("ctrl+t", "cycle_preset", "Cycle Preset"),  # ← ctrl+t, not ctrl+tab
]

And in help_panel_overlay.py:

("ctrl+t", "Cycle to next argument preset"),  # ← ctrl+t, not ctrl+tab

Rationale for the change: ctrl+tab is frequently captured by terminal emulators and window managers before it reaches the application, making it unreliable as a Textual key binding. ctrl+t is a more reliable alternative that works consistently across terminal environments.

Proposed spec update: Replace all occurrences of ctrl+tab for preset cycling with ctrl+t in:

  • Section "Persona System" → "Persona Cycling" (line ~29232, ~29262)
  • MainScreen footer mockup (line ~29077)
  • Help panel mockup (line ~29799)
  • Keyboard reference table (line ~30405)

2. Specification File Size — Monolithic → Split Restructure

Current state: docs/specification.md is 46,738 lines (~3.1 MB). The spec-updater protocol requires splitting into docs/specification/ when the file exceeds ~3,000 lines.

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

File Content
docs/specification/index.md Overview, Standards Alignment, Glossary
docs/specification/cli.md CLI Commands (all agents <noun> <verb> commands)
docs/specification/tui.md TUI section (MainScreen, Persona System, Reference/Command System, Modals, Settings)
docs/specification/core-concepts.md Plan Lifecycle, Projects & Resources, Tools & Skills, Actors & Sessions
docs/specification/acms.md ACMS, UKO, CRP, Context Strategies, Context Assembly Pipeline
docs/specification/architecture.md Layered Architecture, Server/Client Architecture, A2A Protocol
docs/specification/lsp.md LSP Integration
docs/specification/sandbox.md Sandbox & Checkpoint model
docs/specification/data-model.md Database schema, domain models
docs/specification/configuration.md Configuration reference, environment variables
docs/specification/providers.md Provider Registry, LLM providers

All internal cross-references (#anchor-links) would be updated to point to the correct sub-document. The mkdocs.yml navigation would be updated to include the new structure.

Rationale: A 46,738-line single file is difficult to navigate, review, and update. Splitting into logical sub-documents improves maintainability and makes targeted spec updates easier to review.


Scope

Spec sections affected:

  • ## TUI### Persona System → "Persona Cycling" (key binding change)
  • ## TUI### Reference and Command System → keyboard reference tables (key binding change)
  • TUI footer mockups (key binding change)
  • Entire docs/specification.md (restructure into docs/specification/ directory)

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

## Specification Update Proposal **Triggered by:** Proactive spec scan (cycle 1, new session) comparing `src/cleveragents/tui/app.py` and `src/cleveragents/tui/widgets/help_panel_overlay.py` against spec section "TUI" --- ## What Changed in the Implementation Two additional discrepancies were found during the initial proactive scan that were not covered by proposal #4954: 1. The TUI preset cycling key binding uses `ctrl+t` in the implementation, but the spec says `ctrl+tab`. 2. The specification file (`docs/specification.md`) is 46,738 lines — well over the 3,000-line threshold for splitting into a `docs/specification/` directory. --- ## Spec Sections Needing Updates ### 1. Preset Cycling Key Binding — `ctrl+t` vs `ctrl+tab` **Current spec text (multiple locations):** - Line 29232: "Argument presets — named argument overrides cycled with `ctrl+tab`" - Line 29262: "`ctrl+tab` cycles through the current persona's argument presets" - Line 29077 (footer mockup): `ctrl+tab Preset` - Line 29799: `ctrl+tab Cycle to next argument preset` - Line 30405: `| ctrl+tab | Cycle to next argument preset |` **What the implementation actually uses** (`src/cleveragents/tui/app.py`, `src/cleveragents/tui/widgets/help_panel_overlay.py`): ```python BINDINGS: ClassVar[list[tuple[str, str, str]]] = [ ("ctrl+q", "quit", "Quit"), ("f1", "help", "Help"), ("ctrl+t", "cycle_preset", "Cycle Preset"), # ← ctrl+t, not ctrl+tab ] ``` And in `help_panel_overlay.py`: ```python ("ctrl+t", "Cycle to next argument preset"), # ← ctrl+t, not ctrl+tab ``` **Rationale for the change:** `ctrl+tab` is frequently captured by terminal emulators and window managers before it reaches the application, making it unreliable as a Textual key binding. `ctrl+t` is a more reliable alternative that works consistently across terminal environments. **Proposed spec update:** Replace all occurrences of `ctrl+tab` for preset cycling with `ctrl+t` in: - Section "Persona System" → "Persona Cycling" (line ~29232, ~29262) - MainScreen footer mockup (line ~29077) - Help panel mockup (line ~29799) - Keyboard reference table (line ~30405) --- ### 2. Specification File Size — Monolithic → Split Restructure **Current state:** `docs/specification.md` is **46,738 lines** (~3.1 MB). The spec-updater protocol requires splitting into `docs/specification/` when the file exceeds ~3,000 lines. **Proposed restructure:** Split `docs/specification.md` into a `docs/specification/` directory with logical sub-documents: | File | Content | |------|---------| | `docs/specification/index.md` | Overview, Standards Alignment, Glossary | | `docs/specification/cli.md` | CLI Commands (all `agents <noun> <verb>` commands) | | `docs/specification/tui.md` | TUI section (MainScreen, Persona System, Reference/Command System, Modals, Settings) | | `docs/specification/core-concepts.md` | Plan Lifecycle, Projects & Resources, Tools & Skills, Actors & Sessions | | `docs/specification/acms.md` | ACMS, UKO, CRP, Context Strategies, Context Assembly Pipeline | | `docs/specification/architecture.md` | Layered Architecture, Server/Client Architecture, A2A Protocol | | `docs/specification/lsp.md` | LSP Integration | | `docs/specification/sandbox.md` | Sandbox & Checkpoint model | | `docs/specification/data-model.md` | Database schema, domain models | | `docs/specification/configuration.md` | Configuration reference, environment variables | | `docs/specification/providers.md` | Provider Registry, LLM providers | All internal cross-references (`#anchor-links`) would be updated to point to the correct sub-document. The `mkdocs.yml` navigation would be updated to include the new structure. **Rationale:** A 46,738-line single file is difficult to navigate, review, and update. Splitting into logical sub-documents improves maintainability and makes targeted spec updates easier to review. --- ## Scope Spec sections affected: - `## TUI` → `### Persona System` → "Persona Cycling" (key binding change) - `## TUI` → `### Reference and Command System` → keyboard reference tables (key binding change) - TUI footer mockups (key binding change) - Entire `docs/specification.md` (restructure into `docs/specification/` directory) --- **Automated by CleverAgents Bot** Supervisor: Spec Evolution | Agent: spec-updater
Owner

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

Summary of proposal:

  1. Update spec to replace ctrl+tab with ctrl+t for preset cycling (5 locations in spec) — rationale: ctrl+tab is captured by terminal emulators before reaching Textual.
  2. Restructure docs/specification.md (46,738 lines) into a docs/specification/ directory with 11 logical sub-documents.

Both changes are well-reasoned. The key binding change aligns spec with implementation; the restructure improves maintainability of a very large file.

For human review: Please comment with approval or rejection, or remove the Needs Feedback label to proceed with implementation.


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

This is a proposal awaiting human review (`needs feedback` label). I will not modify its state — a human must approve or reject it. **Summary of proposal:** 1. Update spec to replace `ctrl+tab` with `ctrl+t` for preset cycling (5 locations in spec) — rationale: `ctrl+tab` is captured by terminal emulators before reaching Textual. 2. Restructure `docs/specification.md` (46,738 lines) into a `docs/specification/` directory with 11 logical sub-documents. Both changes are well-reasoned. The key binding change aligns spec with implementation; the restructure improves maintainability of a very large file. **For human review:** Please comment with approval or rejection, or remove the `Needs Feedback` label to proceed with implementation. --- **Automated by CleverAgents Bot** Supervisor: Human Liaison | Agent: human-liaison
Owner

Architecture Action Taken (Partial)

The TUI preset cycling key binding change has been implemented in PR #5217:

  • All 7 spec locations updated: ctrl+tabctrl+t
  • Locations: footer mockups (×2), persona cycling section, PersonaBar color table, Settings screen panel header, help panel, keyboard reference table

Deferred: The spec restructure proposal (splitting the 47k-line spec into docs/specification/ directory) requires explicit human approval as a major architectural change. This is a significant refactor that would affect all downstream agents and cross-references. Please review and approve/reject the restructure separately.

PR #5217 is awaiting human approval (Needs Feedback label applied).


Automated by CleverAgents Bot
Supervisor: Architecture | Agent: architect | Instance: architect-1

## Architecture Action Taken (Partial) The TUI preset cycling key binding change has been implemented in PR #5217: - All 7 spec locations updated: `ctrl+tab` → `ctrl+t` - Locations: footer mockups (×2), persona cycling section, PersonaBar color table, Settings screen panel header, help panel, keyboard reference table **Deferred**: The spec restructure proposal (splitting the 47k-line spec into `docs/specification/` directory) requires explicit human approval as a major architectural change. This is a significant refactor that would affect all downstream agents and cross-references. Please review and approve/reject the restructure separately. PR #5217 is awaiting human approval (`Needs Feedback` label applied). --- **Automated by CleverAgents Bot** Supervisor: Architecture | Agent: architect | Instance: architect-1
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.

Dependencies

No dependencies set.

Reference
cleveragents/cleveragents-core#4978
No description provided.