mirror of
https://github.com/sipeed/picoclaw.git
synced 2026-06-12 18:08:54 +00:00
yinwm
146 lines
3.9 KiB
Markdown
146 lines
3.9 KiB
Markdown
# Agent Refactor
|
|
|
|
## What this directory is for
|
|
|
|
This directory is the working area for the current Agent refactor.
|
|
|
|
The purpose of this refactor is simple:
|
|
|
|
the project needs a smaller, clearer, and more stable Agent model before more Agent-related behavior is added.
|
|
|
|
The codebase already contains meaningful Agent behavior. What it still lacks is a sufficiently explicit and stable semantic boundary around that behavior.
|
|
|
|
This refactor exists to fix that first.
|
|
|
|
---
|
|
|
|
## Refactor stance
|
|
|
|
This is a maintenance-led consolidation effort.
|
|
|
|
It is not a general invitation to expand Agent behavior in parallel.
|
|
|
|
During this refactor window, Agent-related work should converge on the current refactor track instead of branching into new semantics.
|
|
|
|
That means:
|
|
|
|
- concept clarification before feature expansion
|
|
- boundary tightening before abstraction growth
|
|
- semantic consolidation before new behavior
|
|
|
|
---
|
|
|
|
## Core rule: minimum concepts only
|
|
|
|
This refactor follows one hard rule:
|
|
|
|
**do not introduce a new concept unless it is strictly necessary**
|
|
|
|
More explicitly:
|
|
|
|
- if an existing concept can be clarified, reuse it
|
|
- if an existing boundary can be made explicit, do that first
|
|
- if a behavior can be expressed without a new abstraction, do not add one
|
|
- "future flexibility" is not enough justification on its own
|
|
|
|
The goal of this refactor is not to grow the model.
|
|
|
|
The goal is to reduce ambiguity.
|
|
|
|
---
|
|
|
|
## What is being clarified
|
|
|
|
This refactor is currently concerned with the following questions:
|
|
|
|
1. what an `Agent` is
|
|
2. what an `AgentLoop` is
|
|
3. what the lifecycle of `AgentLoop` is
|
|
4. what the event surface around `AgentLoop` is
|
|
5. how persona / identity is assembled
|
|
6. how capabilities are represented
|
|
7. how context boundaries and compression work
|
|
8. how subagent coordination works
|
|
|
|
These are the current working boundaries.
|
|
|
|
If they need to be adjusted, they should be adjusted explicitly rather than drift implicitly in code.
|
|
|
|
---
|
|
|
|
## Status of this directory
|
|
|
|
The documents here are working materials.
|
|
|
|
They are not final or immutable.
|
|
|
|
If current notes are incomplete, incorrectly split, or too broad, they should be revised. This directory should evolve with the refactor rather than pretending the first draft is complete.
|
|
|
|
---
|
|
|
|
## Suggested document split
|
|
|
|
This directory may eventually contain notes such as:
|
|
|
|
- `agent-overview.md`
|
|
- what an Agent is
|
|
- `agent-loop.md`
|
|
- AgentLoop contract, lifecycle, event surface
|
|
- `persona.md`
|
|
- persona and identity assembly
|
|
- `capability.md`
|
|
- tools / skills / MCP capability semantics
|
|
- `context.md`
|
|
- context scope, history, summary, compression
|
|
- `subagent.md`
|
|
- subagent coordination rules
|
|
|
|
These files should be added only when they help clarify the current refactor work.
|
|
|
|
This directory should not turn into a generic architecture dump.
|
|
|
|
---
|
|
|
|
## What this directory is not for
|
|
|
|
This directory is not intended for:
|
|
|
|
- broad speculative architecture
|
|
- future multi-node protocol design not required by the current refactor
|
|
- parallel feature planning unrelated to Agent consolidation
|
|
- adding new concepts before current ones are made clear
|
|
|
|
If a topic does not directly help reduce ambiguity in the current Agent model, it probably does not belong here yet.
|
|
|
|
---
|
|
|
|
## Relationship to implementation
|
|
|
|
Implementation changes should not keep redefining Agent semantics implicitly.
|
|
|
|
If a PR changes or depends on Agent semantics, those semantics should either already exist here or be clarified in a linked issue first.
|
|
|
|
This directory is here to make implementation narrower and more disciplined.
|
|
|
|
---
|
|
|
|
## Relationship to GitHub tracking
|
|
|
|
The umbrella issue for this refactor should point here.
|
|
|
|
The issue is the coordination surface.
|
|
|
|
This directory is the repository-local working surface.
|
|
|
|
---
|
|
|
|
## Summary
|
|
|
|
The main question of this refactor is not:
|
|
|
|
- what more can Agent do
|
|
|
|
The main question is:
|
|
|
|
- what is the smallest stable model that current Agent behavior can be organized around
|