Proposal: update specification — remove all legacy plan workflow references (agents tell, agents build) #2441

Open
opened 2026-04-03 18:22:26 +00:00 by freemo · 4 comments
Owner

Spec Update Proposal

Triggered By

  • PR #1577 (merged 2026-04-03): fix(cli): disallow mixing legacy and v3 plan workflows (closes #1560)
  • Human feedback on this issue (comment by @freemo): Legacy commands should be completely removed from the spec, not just documented as incompatible. v3.7.0 is the first release, so there is no need to preserve backwards compatibility.

Change: Remove All Legacy Plan Workflow References from Specification

What changed in the implementation

PR #1577 added explicit ULID validation to all v3 plan CLI commands. The human reviewer has clarified that since v3.7.0 is the first release, there is no backwards compatibility requirement — the legacy agents tell and agents build commands should be completely removed from the specification, not merely documented as incompatible.

What spec sections need updating

docs/specification.md — All sections referencing legacy commands:

  1. Remove all references to agents tell — the legacy command for submitting work to an agent. This command is not part of the v3 plan lifecycle and should not appear in the spec.

  2. Remove all references to agents build — the legacy build command. Same rationale.

  3. Remove any "legacy workflow" sections or notes — any documentation describing the legacy storage system, legacy plan format, or migration paths from legacy to v3.

  4. Update Plan Lifecycle section — ensure it only describes the v3 plan lifecycle (agents plan useagents plan executeagents plan apply) with no mention of legacy alternatives.

  5. Add ULID format documentation — since plan IDs are Crockford Base32 ULIDs, document this in the Plan Lifecycle section and/or Glossary:

    Plan IDs are Crockford Base32 ULIDs (26 characters, using characters 0-9A-HJKMNP-TV-Z, case-insensitive). All v3 plan commands validate that the provided plan ID is a valid ULID at input time.

  6. Update CLI Commands section — remove agents tell and agents build from the CLI command reference entirely.

  7. Update CONTRIBUTING.md — remove the "Workflow Choice: Legacy vs. v3 Plan Lifecycle" section that was added by PR #1577, since legacy commands no longer exist in the spec.

Rationale

v3.7.0 is the first public release of CleverAgents. There are no existing users with legacy plans to migrate. The legacy agents tell / agents build workflow was an internal development artifact that predates the v3 plan lifecycle. Keeping it in the spec creates confusion and maintenance burden. Removing it entirely makes the spec cleaner and more authoritative.

The ULID validation enforcement is a genuine UX improvement that should be documented — plan IDs have a specific format and the CLI validates this at input time.


Scope

Section Change Type
docs/specification.md — CLI Commands Remove agents tell and agents build commands entirely
docs/specification.md — Plan Lifecycle Remove all legacy workflow references; add ULID format note
docs/specification.md — Glossary Remove legacy plan entries; update Plan entry with ULID format
docs/specification.md — Any other legacy references Remove
CONTRIBUTING.md — Workflow Choice section Remove legacy vs. v3 section

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 - **PR #1577** (merged 2026-04-03): `fix(cli): disallow mixing legacy and v3 plan workflows` (closes #1560) - **Human feedback** on this issue (comment by @freemo): Legacy commands should be completely removed from the spec, not just documented as incompatible. v3.7.0 is the first release, so there is no need to preserve backwards compatibility. --- ## Change: Remove All Legacy Plan Workflow References from Specification ### What changed in the implementation PR #1577 added explicit ULID validation to all v3 plan CLI commands. The human reviewer has clarified that since **v3.7.0 is the first release**, there is no backwards compatibility requirement — the legacy `agents tell` and `agents build` commands should be **completely removed** from the specification, not merely documented as incompatible. ### What spec sections need updating **`docs/specification.md` — All sections referencing legacy commands:** 1. **Remove all references to `agents tell`** — the legacy command for submitting work to an agent. This command is not part of the v3 plan lifecycle and should not appear in the spec. 2. **Remove all references to `agents build`** — the legacy build command. Same rationale. 3. **Remove any "legacy workflow" sections or notes** — any documentation describing the legacy storage system, legacy plan format, or migration paths from legacy to v3. 4. **Update Plan Lifecycle section** — ensure it only describes the v3 plan lifecycle (`agents plan use` → `agents plan execute` → `agents plan apply`) with no mention of legacy alternatives. 5. **Add ULID format documentation** — since plan IDs are Crockford Base32 ULIDs, document this in the Plan Lifecycle section and/or Glossary: > Plan IDs are **Crockford Base32 ULIDs** (26 characters, using characters `0-9A-HJKMNP-TV-Z`, case-insensitive). All v3 plan commands validate that the provided plan ID is a valid ULID at input time. 6. **Update CLI Commands section** — remove `agents tell` and `agents build` from the CLI command reference entirely. 7. **Update CONTRIBUTING.md** — remove the "Workflow Choice: Legacy vs. v3 Plan Lifecycle" section that was added by PR #1577, since legacy commands no longer exist in the spec. ### Rationale v3.7.0 is the first public release of CleverAgents. There are no existing users with legacy plans to migrate. The legacy `agents tell` / `agents build` workflow was an internal development artifact that predates the v3 plan lifecycle. Keeping it in the spec creates confusion and maintenance burden. Removing it entirely makes the spec cleaner and more authoritative. The ULID validation enforcement is a genuine UX improvement that should be documented — plan IDs have a specific format and the CLI validates this at input time. --- ## Scope | Section | Change Type | |---------|-------------| | `docs/specification.md` — CLI Commands | Remove `agents tell` and `agents build` commands entirely | | `docs/specification.md` — Plan Lifecycle | Remove all legacy workflow references; add ULID format note | | `docs/specification.md` — Glossary | Remove legacy plan entries; update Plan entry with ULID format | | `docs/specification.md` — Any other legacy references | Remove | | `CONTRIBUTING.md` — Workflow Choice section | Remove legacy vs. v3 section | --- **Awaiting human approval before any branch or PR is created.** --- **Automated by CleverAgents Bot** Supervisor: Spec Evolution | Agent: ca-spec-updater
Author
Owner

The legacy commands dont need to be supported at all, completely remove them along with any reference to them (including in documentation). v3.7.0 will actually be our first release so there is no need to preserve backwards compatibility.

Please update the description of this ticket to reflect this, and then I will approve the ticket. Once you updated the body of the ticket leave a comment to me letting me know so I can review the ticket again for approval.

The legacy commands dont need to be supported at all, completely remove them along with any reference to them (including in documentation). v3.7.0 will actually be our first release so there is no need to preserve backwards compatibility. Please update the description of this ticket to reflect this, and then I will approve the ticket. Once you updated the body of the ticket leave a comment to me letting me know so I can review the ticket again for approval.
freemo changed title from Proposal: update specification — document ULID validation enforcement and legacy/v3 plan workflow incompatibility to Proposal: update specification — remove all legacy plan workflow references (agents tell, agents build) 2026-04-03 18:54:35 +00:00
Author
Owner

I've updated the proposal body as requested. The scope has been changed from "document legacy/v3 incompatibility" to "remove all legacy plan workflow references entirely" from the specification.

Summary of updated scope:

  • Remove agents tell and agents build commands from the CLI Commands section entirely
  • Remove all legacy workflow references from the Plan Lifecycle section
  • Remove legacy plan entries from the Glossary
  • Add ULID format documentation (plan IDs are Crockford Base32 ULIDs, validated at input time)
  • Remove the "Workflow Choice: Legacy vs. v3 Plan Lifecycle" section from CONTRIBUTING.md

Rationale incorporated: v3.7.0 is the first public release — no backwards compatibility is needed.

Please review the updated proposal body above and approve when ready (remove the needs feedback label, add State/Verified, or comment with approval).


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

I've updated the proposal body as requested. The scope has been changed from "document legacy/v3 incompatibility" to **"remove all legacy plan workflow references entirely"** from the specification. **Summary of updated scope:** - Remove `agents tell` and `agents build` commands from the CLI Commands section entirely - Remove all legacy workflow references from the Plan Lifecycle section - Remove legacy plan entries from the Glossary - Add ULID format documentation (plan IDs are Crockford Base32 ULIDs, validated at input time) - Remove the "Workflow Choice: Legacy vs. v3 Plan Lifecycle" section from CONTRIBUTING.md **Rationale incorporated:** v3.7.0 is the first public release — no backwards compatibility is needed. Please review the updated proposal body above and approve when ready (remove the `needs feedback` label, add `State/Verified`, or comment with approval). --- **Automated by CleverAgents Bot** Supervisor: Spec Evolution | Agent: ca-spec-updater
Author
Owner

Label compliance fix applied:

  • Removed conflicting labels: State/Unverified, State/Verified
  • Kept: State/In progress (most advanced state)
  • Reason: Issue had 3 conflicting State/* labels simultaneously. Per CONTRIBUTING.md, only one State/* label is permitted. State/In progress is the most advanced state and was retained.

Automated by CleverAgents Bot
Supervisor: Backlog Grooming | Agent: ca-backlog-groomer

Label compliance fix applied: - Removed conflicting labels: `State/Unverified`, `State/Verified` - Kept: `State/In progress` (most advanced state) - Reason: Issue had 3 conflicting `State/*` labels simultaneously. Per CONTRIBUTING.md, only one `State/*` label is permitted. `State/In progress` is the most advanced state and was retained. --- **Automated by CleverAgents Bot** Supervisor: Backlog Grooming | Agent: ca-backlog-groomer
Author
Owner

Label compliance fix applied:

  • Added missing label: State/Unverified
  • Added missing label: Type/Task
  • Added missing label: Priority/Backlog
  • Reason: Issue was missing all required labels (State/, Type/, Priority/*) per CONTRIBUTING.md. Applied defaults: State/Unverified (new issues default), Type/Task (spec update proposal), Priority/Backlog (default per CONTRIBUTING.md).

Automated by CleverAgents Bot
Supervisor: Backlog Grooming | Agent: ca-backlog-groomer

Label compliance fix applied: - Added missing label: `State/Unverified` - Added missing label: `Type/Task` - Added missing label: `Priority/Backlog` - Reason: Issue was missing all required labels (State/*, Type/*, Priority/*) per CONTRIBUTING.md. Applied defaults: `State/Unverified` (new issues default), `Type/Task` (spec update proposal), `Priority/Backlog` (default per CONTRIBUTING.md). --- **Automated by CleverAgents Bot** Supervisor: Backlog Grooming | Agent: ca-backlog-groomer
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#2441
No description provided.