# Single CLI + Progressive Skill Disclosure Redesign PRD
## 1. Goal
This task redesigns the current agent tool protocol around one confirmed product constraint:
1. The runtime should continue to expose exactly one business tool to the worker agent: `project_cli`.
2. The worker should learn how to use the tool through progressive skill disclosure instead of receiving a large global tool surface up front.
3. The current `command + subcommand + args` transport should be replaced with a business-action protocol that matches real product objects and user intents.
4. The redesign must remain grounded in the current repository's actual schedule domain:
-`schedule_items`
-`schedule_subscriptions`
5. The redesign must reduce wasted retries and token consumption without reintroducing the old multi-tool schema explosion.
This PRD does not propose a broad agent-platform rewrite. It is a focused redesign of how the single CLI tool, skills, router output, and worker execution contract should work together.
## 2. Confirmed Repository Facts
### 2.1 Router is not ReAct
The router is a direct structured generation stage, not a ReAct loop.
- The product itself already separates these business operations.
- The ambiguity exists in the agent CLI input contract, not in the underlying app/domain design.
## 3. Problem Statement
The current one-tool design has the right high-level direction but the wrong action protocol.
### 3.1 What was correct in the previous refactor
The following direction remains valid and should be preserved:
1. One AgentScope tool entry (`project_cli`) is preferable to many domain tools for token control.
2. AgentScope skills should be the mechanism for teaching the model when and how to use the tool.
3. Tool outputs should remain structured and machine-oriented.
4. AG-UI/UI-schema compilation should remain backend-owned.
5. The worker should not receive all tool knowledge eagerly.
### 3.2 What is no longer acceptable
The following parts of the previous CLI protocol should be replaced:
1.`command + subcommand + args` as the model-facing protocol.
2. Ambiguous action names such as `read` that cover more than one business intent.
3. Loose `args: dict[str, Any]` semantics that encourage field guessing.
4. Legacy alias drift such as `start_time/end_time`, `event_timezone`, and other migration leftovers.
5. Runtime dependence on long prose skill files instead of short execution-oriented action cards.
### 3.3 Why the old CLI shape fails even though the single-tool strategy is good
The current single-tool protocol is too generic for a small model.
The worker must infer, from weak labels like `read`, all of the following at once:
1. Which business object is involved.
2. Whether the user wants a list or one detail record.
3. Which fields are mandatory for that specific subcommand.
4. Which field names are canonical.
This moves too much burden from the runtime protocol into model guesswork.
The result is not just correctness risk. It also increases token cost because the worker burns iterations learning through failure.
## 4. Design Principles
### 4.1 Keep exactly one tool
The worker should continue to see one executable tool:
-`project_cli`
Reason:
- avoids multi-tool selection overhead
- avoids injecting many tool schemas into every model call
- preserves a stable tool surface for worker prompting
### 4.2 Move model-facing semantics from CLI history to business actions
The model-facing protocol should describe business intent directly, not technical command-tree history.
Replace:
```json
{
"command":"calendar",
"subcommand":"read",
"args":{}
}
```
With:
```json
{
"module":"calendar",
"method":"read",
"input":{
"mode":"event",
"event_id":"<uuid>"
}
}
```
This preserves one tool while making the business contract explicit.
### 4.3 Use progressive disclosure for skill knowledge, not for raw global schema exposure
The worker should not receive all method definitions by default.
Instead:
1. Read a short skill index first.
2. Read the relevant method card only when necessary.
3. Call `project_cli` with the chosen `module/method/input` payload.
This keeps the token budget focused on the current business scenario.
### 4.4 Server-side validation stays strict even if the tool schema stays thin
To avoid a large tool schema, `project_cli` may expose only a thin outer schema:
-`module`
-`method`
-`input`
Strict validation then happens server-side by dispatching `module + method` to the corresponding Pydantic model.
For calendar reads, the input must use strong typed domain values at the schema boundary:
- day reads: `date`
- range reads: timezone-aware `datetime`
- single-event reads: `UUID`
The transport remains JSON, but the backend contract must validate these as typed values immediately instead of accepting arbitrary strings and reparsing them later.
This preserves strictness without forcing the entire action matrix into the model context.
### 4.5 No broad backward-compatibility layer
This redesign should not preserve old field aliases or broad coercion behavior.
Specifically, phase implementation should remove or reject:
-`args` as JSON string
-`start_time/end_time`
-`event_timezone`
- action overloading under `read`
The system should fail clearly and structurally instead of guessing.
## 5. Target Architecture
## 5.1 Runtime responsibilities
### Router
The router remains a direct structured output stage.
It should continue to decide:
- the objective
- whether tool evidence is required
It should be extended to optionally provide stronger execution hints:
-`selected_skill`
-`intended_action`
-`known_entities`
-`known_time_range`
-`missing_fields`
These fields are not there to make router execute tools. They are there to reduce worker exploration cost.
