Proposal: update specification — resource stop/rebuild scope, A2A facade caching, TUI optional dependency, devcontainer module split, and spec restructuring #6873

Open
opened 2026-04-10 04:31:40 +00:00 by HAL9000 · 2 comments
Owner

Background and Context

This proposal was triggered by analysis of recently merged PRs (2026-04-09 to 2026-04-10) comparing the implementation against docs/specification.md. The spec is the authoritative source of truth, and these changes reflect implementation discoveries that represent better approaches than what the spec currently describes.

Merged PRs analyzed:

  • fix(resources): allow agents resource stop to stop container-instance and devcontainer-instance resources (#3250)
  • feat: add pr-merge-pool-supervisor as 17th supervisor to product-builder
  • chore(policy): reduce PR review requirement from 2 approvals to 1
  • refactor(agents): reorganize PR agents and rename supervisors to *-pool-supervisor pattern
  • fix: remove hardcoded worker numbers, use CA_MAX_PARALLEL_WORKERS
  • feat(agents): enhance automation tracking with announcements and cross-agent awareness
  • feat: enhance async-agent-manager with retry logic and improved UX

What Changed in the Implementation

Change 1: agents resource stop and agents resource rebuild now apply to all container-type resources

Merged PR: #3250fix(resources): allow agents resource stop to stop container-instance and devcontainer-instance resources

The implementation was fixed so that agents resource stop and agents resource rebuild work on both container-instance AND devcontainer-instance resources (not just devcontainers). Previously the handlers only handled devcontainer-instance.

Current spec text (in ## CLI Commands > Command Reference and ## Core Concepts > Resources):

agents resource stop <NAME> — described only in context of devcontainer resources

Proposed spec text: Clarify that agents resource stop and agents resource rebuild apply to all container-type resources (container-instance and its subtypes including devcontainer-instance). The stop command halts the running container; rebuild tears down and recreates it. Both commands are valid for any resource whose type inherits from container-instance.


Change 2: A2A Local Facade — handler dispatch caching (PERF-1)

Source: src/cleveragents/a2a/facade.py

The A2aLocalFacade implementation added a performance optimization: the operation→handler dispatch dict is built once and cached in self._handler_map. It is invalidated (set to None) when register_service() is called. This avoids rebuilding the dict on every dispatch() call.

Current spec text (in ## Architecture > A2A Integration Architecture):

Describes A2aLocalFacade as routing operations to service methods, but does not mention caching.

Proposed spec text: Add a note that A2aLocalFacade caches its operation→handler dispatch map for performance. The cache is invalidated when new services are registered via register_service(). This is a better design than rebuilding the map on every request.


Change 3: TUI — Textual as optional dependency with graceful fallback

Source: src/cleveragents/tui/app.py

The TUI implementation uses a graceful optional-dependency pattern: Textual is imported at module load time inside a try/except. If Textual is not installed, CleverAgentsTuiApp resolves to _FallbackCleverAgentsTuiApp, which raises an actionable RuntimeError with installation instructions when .run() is called.

Current spec text (in ## TUI > TUI Architecture Overview):

States Textual ≥ 1.0 is required, but does not document the optional-dependency fallback pattern.

Proposed spec text: Document that Textual is an optional extra (pip install 'cleveragents[tui]'). When Textual is not installed, the TUI module loads successfully but raises an actionable error at runtime. This is a better UX than a hard import failure at module load time.


Change 4: Devcontainer handler split into focused sub-modules

Source: src/cleveragents/resource/handlers/devcontainer*.py

To comply with the 500-line file limit (architectural invariant #9), the devcontainer handler was split into 4 focused modules:

  • _devcontainer_internals.py — shared registry state, accessors, parsing
  • devcontainer_health.py — background health check threads
  • devcontainer_lifecycle.py — activate / stop / rebuild operations
  • devcontainer_cleanup.py — session cleanup and tracker eviction

The main devcontainer.py re-exports all public symbols for backward compatibility.

Current spec text (in ## Architecture > Extensibility and ## Core Concepts > Resources > Devcontainer):

Does not document the internal module structure of the devcontainer handler.

Proposed spec text: Add a note in the Devcontainer section documenting the 4-module split pattern and the re-export approach. This is a good pattern for other large handlers to follow.


Change 5: Spec monolithic→split restructuring (MAJOR)

Current state: docs/specification.md is a single file of 47,039 lines (~3.1 MB). This significantly exceeds the 3,000-line threshold for restructuring.

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

File Content Approx Lines
index.md Overview, Glossary, Standards Alignment ~250
cli.md CLI Commands (Synopsis + Reference) ~18,100
core-concepts.md Core Concepts (Plan, Action, Strategy, Execute, Apply, Project, Actor, etc.) ~10,200
behavior.md Behavior (Automation Profiles, Guardrails, Corrections, Human-in-the-Loop) ~540
tui.md TUI (all TUI subsections) ~1,590
configuration.md Configuration (all config subsections) ~5,790
workflow-examples.md Workflow Examples (all 18 examples) ~6,780
architecture.md Architecture (all architecture subsections) ~3,575
milestone-plan.md Milestone Plan ~300

Each sub-document would have its own H1 heading and cross-link to others via relative paths. The index.md would serve as the entry point with a table of contents linking all sub-documents.

Rationale: The current monolithic file is difficult to navigate, slow to load in editors, and makes targeted updates error-prone. Splitting follows the existing ADR directory pattern and makes the spec more maintainable.


Spec Sections Affected

  1. ## CLI Commands > Command Reference > agents resource stop/rebuild — scope clarification
  2. ## Architecture > A2A Integration Architecture > A2aLocalFacade — dispatch caching note
  3. ## TUI > TUI Architecture Overview — optional dependency pattern
  4. ## Core Concepts > Resources > Devcontainer — module split documentation
  5. Entire spec — monolithic→split restructuring (major change)

Rationale

All proposed changes reflect implementation discoveries that represent better approaches:

  • Changes 1–4 are minor clarifications where the implementation found a better or more complete design
  • Change 5 is a structural improvement that makes the spec more maintainable and navigable

None of these changes remove planned features or alter the core domain model.


Scope

  • Changes 1–4: Minor clarifications to existing spec sections
  • Change 5: Major structural change (monolithic→split) requiring careful execution

Subtasks

  • Get human approval on this proposal
  • For Changes 1–4: Create branch spec/update-v3.7.0-minor-clarifications, commit targeted edits, create PR
  • For Change 5: Create branch spec/restructure-monolithic-to-split, execute the split, update all cross-references, create PR
  • Add needs feedback label to both PRs
  • Post announcement issue when PRs are created

Definition of Done

This proposal is complete when:

  • All subtasks above are completed
  • PRs are created with needs feedback label
  • A human has reviewed and merged the PRs
  • This issue is closed

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

## Background and Context This proposal was triggered by analysis of recently merged PRs (2026-04-09 to 2026-04-10) comparing the implementation against `docs/specification.md`. The spec is the authoritative source of truth, and these changes reflect implementation discoveries that represent **better approaches** than what the spec currently describes. **Merged PRs analyzed:** - `fix(resources): allow agents resource stop to stop container-instance and devcontainer-instance resources` (#3250) - `feat: add pr-merge-pool-supervisor as 17th supervisor to product-builder` - `chore(policy): reduce PR review requirement from 2 approvals to 1` - `refactor(agents): reorganize PR agents and rename supervisors to *-pool-supervisor pattern` - `fix: remove hardcoded worker numbers, use CA_MAX_PARALLEL_WORKERS` - `feat(agents): enhance automation tracking with announcements and cross-agent awareness` - `feat: enhance async-agent-manager with retry logic and improved UX` --- ## What Changed in the Implementation ### Change 1: `agents resource stop` and `agents resource rebuild` now apply to all container-type resources **Merged PR**: #3250 — `fix(resources): allow agents resource stop to stop container-instance and devcontainer-instance resources` The implementation was fixed so that `agents resource stop` and `agents resource rebuild` work on both `container-instance` AND `devcontainer-instance` resources (not just devcontainers). Previously the handlers only handled `devcontainer-instance`. **Current spec text** (in `## CLI Commands > Command Reference` and `## Core Concepts > Resources`): > `agents resource stop <NAME>` — described only in context of devcontainer resources **Proposed spec text**: Clarify that `agents resource stop` and `agents resource rebuild` apply to all container-type resources (`container-instance` and its subtypes including `devcontainer-instance`). The `stop` command halts the running container; `rebuild` tears down and recreates it. Both commands are valid for any resource whose type inherits from `container-instance`. --- ### Change 2: A2A Local Facade — handler dispatch caching (PERF-1) **Source**: `src/cleveragents/a2a/facade.py` The `A2aLocalFacade` implementation added a performance optimization: the operation→handler dispatch dict is built once and cached in `self._handler_map`. It is invalidated (set to `None`) when `register_service()` is called. This avoids rebuilding the dict on every `dispatch()` call. **Current spec text** (in `## Architecture > A2A Integration Architecture`): > Describes `A2aLocalFacade` as routing operations to service methods, but does not mention caching. **Proposed spec text**: Add a note that `A2aLocalFacade` caches its operation→handler dispatch map for performance. The cache is invalidated when new services are registered via `register_service()`. This is a better design than rebuilding the map on every request. --- ### Change 3: TUI — Textual as optional dependency with graceful fallback **Source**: `src/cleveragents/tui/app.py` The TUI implementation uses a graceful optional-dependency pattern: Textual is imported at module load time inside a `try/except`. If Textual is not installed, `CleverAgentsTuiApp` resolves to `_FallbackCleverAgentsTuiApp`, which raises an actionable `RuntimeError` with installation instructions when `.run()` is called. **Current spec text** (in `## TUI > TUI Architecture Overview`): > States Textual ≥ 1.0 is required, but does not document the optional-dependency fallback pattern. **Proposed spec text**: Document that Textual is an optional extra (`pip install 'cleveragents[tui]'`). When Textual is not installed, the TUI module loads successfully but raises an actionable error at runtime. This is a better UX than a hard import failure at module load time. --- ### Change 4: Devcontainer handler split into focused sub-modules **Source**: `src/cleveragents/resource/handlers/devcontainer*.py` To comply with the 500-line file limit (architectural invariant #9), the devcontainer handler was split into 4 focused modules: - `_devcontainer_internals.py` — shared registry state, accessors, parsing - `devcontainer_health.py` — background health check threads - `devcontainer_lifecycle.py` — activate / stop / rebuild operations - `devcontainer_cleanup.py` — session cleanup and tracker eviction The main `devcontainer.py` re-exports all public symbols for backward compatibility. **Current spec text** (in `## Architecture > Extensibility` and `## Core Concepts > Resources > Devcontainer`): > Does not document the internal module structure of the devcontainer handler. **Proposed spec text**: Add a note in the Devcontainer section documenting the 4-module split pattern and the re-export approach. This is a good pattern for other large handlers to follow. --- ### Change 5: Spec monolithic→split restructuring (MAJOR) **Current state**: `docs/specification.md` is a single file of **47,039 lines (~3.1 MB)**. This significantly exceeds the 3,000-line threshold for restructuring. **Proposed restructuring**: Split into `docs/specification/` directory with logical sub-documents: | File | Content | Approx Lines | |------|---------|-------------| | `index.md` | Overview, Glossary, Standards Alignment | ~250 | | `cli.md` | CLI Commands (Synopsis + Reference) | ~18,100 | | `core-concepts.md` | Core Concepts (Plan, Action, Strategy, Execute, Apply, Project, Actor, etc.) | ~10,200 | | `behavior.md` | Behavior (Automation Profiles, Guardrails, Corrections, Human-in-the-Loop) | ~540 | | `tui.md` | TUI (all TUI subsections) | ~1,590 | | `configuration.md` | Configuration (all config subsections) | ~5,790 | | `workflow-examples.md` | Workflow Examples (all 18 examples) | ~6,780 | | `architecture.md` | Architecture (all architecture subsections) | ~3,575 | | `milestone-plan.md` | Milestone Plan | ~300 | Each sub-document would have its own H1 heading and cross-link to others via relative paths. The `index.md` would serve as the entry point with a table of contents linking all sub-documents. **Rationale**: The current monolithic file is difficult to navigate, slow to load in editors, and makes targeted updates error-prone. Splitting follows the existing ADR directory pattern and makes the spec more maintainable. --- ## Spec Sections Affected 1. `## CLI Commands > Command Reference > agents resource stop/rebuild` — scope clarification 2. `## Architecture > A2A Integration Architecture > A2aLocalFacade` — dispatch caching note 3. `## TUI > TUI Architecture Overview` — optional dependency pattern 4. `## Core Concepts > Resources > Devcontainer` — module split documentation 5. **Entire spec** — monolithic→split restructuring (major change) --- ## Rationale All proposed changes reflect implementation discoveries that represent **better approaches**: - Changes 1–4 are minor clarifications where the implementation found a better or more complete design - Change 5 is a structural improvement that makes the spec more maintainable and navigable None of these changes remove planned features or alter the core domain model. --- ## Scope - **Changes 1–4**: Minor clarifications to existing spec sections - **Change 5**: Major structural change (monolithic→split) requiring careful execution --- ## Subtasks - [ ] Get human approval on this proposal - [ ] For Changes 1–4: Create branch `spec/update-v3.7.0-minor-clarifications`, commit targeted edits, create PR - [ ] For Change 5: Create branch `spec/restructure-monolithic-to-split`, execute the split, update all cross-references, create PR - [ ] Add `needs feedback` label to both PRs - [ ] Post announcement issue when PRs are created --- ## Definition of Done This proposal is complete when: - All subtasks above are completed - PRs are created with `needs feedback` label - A human has reviewed and merged the PRs - This issue is closed --- **Automated by CleverAgents Bot** Supervisor: Spec Evolution | Agent: spec-updater
HAL9000 added this to the v3.7.0 milestone 2026-04-10 04:37:39 +00:00
Author
Owner

Updated labels on issue #6873: Added Needs Feedback, Type/Task, State/Unverified, Priority/Backlog. Milestone set to v3.7.0 (130).


Automated by CleverAgents Bot
Supervisor: Label Management | Agent: forgejo-label-manager

Updated labels on issue #6873: Added Needs Feedback, Type/Task, State/Unverified, Priority/Backlog. Milestone set to v3.7.0 (130). --- **Automated by CleverAgents Bot** Supervisor: Label Management | Agent: forgejo-label-manager
Author
Owner

Verified — Spec proposal: multiple spec updates for resource, A2A, TUI, devcontainer. MoSCoW: Could-have. Priority: Low.


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

✅ **Verified** — Spec proposal: multiple spec updates for resource, A2A, TUI, devcontainer. MoSCoW: Could-have. Priority: Low. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: project-owner-pool-supervisor
Sign in to join this conversation.
No milestone
No project
No assignees
1 participant
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#6873
No description provided.