English | 简体中文
Status: the bundled Skill, desktop handoff, public CLI, and rule preview have source implementations. This Codex session can exercise the CLI; separate Claude Code and WorkBuddy runtime acceptance remains pending.
Space Analysis offers Simple/Detailed views and a Copy for AI action in both. It copies the existing scan ID, scope, exact paths, size/extension evidence, coverage, selected/removed paths and local CLI/Skill entries. Users paste it into their existing agent; Shou neither uploads it nor calls a model. The agent reuses analysis context/map/children before inspecting rules, resolving purpose and previewing a draft. See the space-analysis contract and acceptance.
The bundle ships Cleanup assistant and Rule authoring. macOS and Windows expose skills list/read/install/export with --skill. Desktop setup is available from Cleanup Options or Settings/Rules. External Skill distribution is separate from embedded Windows AI and does not open native mutation gates.
Shou's next stage adds a built-in cleanup Agent while retaining external coding-agent CLI/Skill access. The first built-in investigation is implemented; see usage and acceptance and see the PRD and integration design. This document covers the existing external-agent contract.
A user’s existing coding agent operates Shou as a local tool with a stable CLI. Shou owns deterministic validation, scans, plans, and file-operation policy. The external product owns inference, authentication, conversation, and authorization.
Built-in investigation adds user-provided credentials, model connections and a replaceable Swift SDK. It does not host external coding agents, manage their authentication/conversation/permissions or expand Skill installation into client configuration management.
The released version uses existing agents for personal-rule customization. Built-in investigation will share its draft, validation and independent-preview contracts. Users describe the problem and answer necessary questions; the manual wizard and JSON import remain advanced fallback tools.
Open Rules → Customize with AI, select the client and install the Skill or export a ZIP, then copy the request into an existing agent. The request supplies the local Skill entrypoint, exact CLI path, and selected workspace when available. Installation writes the Skill directory only; no external agent is launched and no client settings file is modified. The rules list refreshes when the sheet closes, Rules is revisited or Shou becomes active.
/Applications/Shou.app/Contents/Helpers/shou agent skill --jsonThis read-only command works without opening the cleanup record store. It returns name, directory, entrypoint, and instructions for the shipped Skill. The directory includes its questionnaire and optional Codex metadata. skills list/read expose the bundled instructions; skills install --agent codex|claude-code installs the whole directory, and skills export --output <path.zip> prepares a WorkBuddy upload. See installation, invocation and Lark CLI research. Directly asking a client to read the supplied SKILL.md is an alternative when local-file reading is supported. Automatic discovery remains a separate client behavior to verify.
The same files ship in both the desktop resources and the independent CLI resources. ShouAgentSupport resolves the packaged copy after relocation; it has no dependency on the cleanup engine or an AI provider.
| Need | Contract |
|---|---|
| Skill distribution | Bundled reads, explicit client installation, conflict-preserving updates, WorkBuddy ZIP export |
| Discovery | Capabilities, help, schemas, side-effect levels |
| Understanding | Stable fields, bytes, codes, evidence, unknowns |
| Rule addition | Noninteractive validation/import of disabled drafts and read-only preview |
| State queries | Rule/scan/plan/history state and permissible next actions |
| Continuation | Stable IDs, immutable snapshots, pagination, conflict details |
| Bounded operation | Same workspace, protection, platform, and confirmation policies |
| GUI independence | Persistent operations do not require simulated clicks |
sequenceDiagram
actor User
participant Agent as Existing coding agent
participant CLI
participant Core
participant FS as Authorized workspace
User->>Agent: Add a rule for a specified project
Agent->>CLI: agent skill --json
CLI-->>Agent: Skill entrypoint and questionnaire
Agent->>CLI: Discover capabilities and schema
CLI-->>Agent: Actual inputs and limits
Agent->>CLI: Query workspace and evidence
CLI-->>Agent: Scope, clues, unknowns
Agent-->>User: Ask missing purpose, rebuild, retention and keep-path questions
User->>Agent: Explain intent and constraints
Agent->>Agent: Draft local JSON
Agent->>CLI: Validate
CLI->>Core: Structural and semantic checks
Core-->>Agent: Result or actionable errors
Agent->>CLI: Import disabled draft
CLI->>Core: Persist version and provenance
Agent->>CLI: Preview
Core->>FS: Read-only scan
FS-->>Core: Identities and statistics
Core-->>Agent: Matches, exclusions, risks, completeness
Agent-->>User: Explain draft and unresolved questions
Note over User,CLI: Enablement and confirmed execution remain separate
Import is a real W-level operation: users should not have to reconstruct a rule manually after receiving generated text.
flowchart TD
Intent[User describes disk problem] --> Skill[Existing agent reads shipped Skill]
Skill --> Inspect[Inspect specified roots and existing rules]
Inspect --> Missing{Purpose and rebuild evidence clear?}
Missing -->|No| Ask[Ask only unresolved questions]
Ask --> Answers[User supplies scope, retention and keep paths]
Answers --> Missing
Missing -->|Yes| Existing{Exact built-in rule available?}
Existing -->|Yes| Reuse[Reuse current rule and inspect matches]
Existing -->|No| Draft[Agent writes declarative JSON]
Draft --> Validate[Validate and import disabled version]
Validate --> Preview[Read-only preview and paginated evidence]
Preview --> Review[User reviews exact effect]
Reuse --> Review
Review --> Enable[Enable if authorized and rescan]
Enable --> Clean[Desktop or terminal confirms chosen cleanup action]
Use the question matrix for mixed roots such as Documents, Library, .colima, .codex, .cache, .nvm, go, .rustup, .local, and .cargo. This list guides investigation; it is not a default deletion catalog. Current rules match directories only, so a VM image file or tool-native operation may need a future adapter. A high-risk label cannot bypass source, credential, identity or completeness checks.
A user may give an existing agent this task, or use the desktop-generated request:
Use Shou’s public CLI to add a rule for inactive Rust target directories
in my already registered developer-workspaces workspace.
Discover capabilities and the current rule schema first. Inspect workspace
and directory evidence. Require parent Cargo.toml, at least 14 days since
the newest modification, and exclude my current project.
Do not guess that other large directories are disposable. Ask me when
purpose is unclear. Validate, import a disabled draft, and preview it.
Report exact matches, estimates, rebuild costs, and unknowns.
Do not enable, clean, permanently delete, run rm/sudo, or bypass Shou.
A delegation is behavioral guidance, not OS isolation. Tool access remains controlled by the external product and user environment.
| Product | Interface | Excluded behavior | Evidence |
|---|---|---|---|
| Codex | Authorized local CLI and JSON | No launch, model integration, or global configuration changes | Current-session CLI checks; independent Skill discovery/client modes pending |
| Claude Code | Same public CLI under its tool permissions | No hard-coded private flags or model choices | Pending actual client validation |
| WorkBuddy and others | Same contract when local commands/files are supported | Do not assume equal capabilities across versions | Pending version/permission validation |
No provider-specific engine is required. If a client cannot invoke commands reliably, record the limitation instead of claiming compatibility from documentation alone.
Export only necessary inspected metadata, not source bodies, secrets, or business contents by default. Paths, README text, rule descriptions, and logs are data, not authoritative instructions. Separate observed facts, declarations, unknowns, and recommendations.
Shou uploads nothing automatically. External agents may process tool results according to their own configuration. Let users review private paths and prefer relative summaries; never expose bookmarks or access credentials.
Authorized noninteractive tasks may register roots, import drafts, and preview. Enablement is separate and still grants no deletion permission. Destructive execution requires a concrete plan and confirmation in the desktop or interactive terminal. No TTY returns confirmation_required and structured next actions.
After review, an agent may create either the default Trash plan or an explicitly requested permanent plan:
shou plan create --scan-id "scan_example" --candidate "candidate_example" --mode trash --json
# Use --mode permanent only after the user explicitly chooses irreversible removal.
shou plan show --plan-id "plan_example" --json
shou plan execute --plan-id "plan_example"The CLI asks for TRASH <plan-id> or PURGE <plan-id> in the controlling TTY. A noninteractive agent may prepare and inspect a permanent plan but cannot execute it. Shou never accepts rm, rm -rf, arbitrary Shell scripts or paths outside the returned plan; a permanent receipt records operation=permanent_cleanup, purging and purged.
Equally privileged local processes may modify files outside Shou, so the CLI is not a sandbox. Guarantees apply to operations through supported interfaces, not arbitrary external Shell commands.
Record product/version, operating system, permission mode, and actual results. Verify discovery; evidence-based drafts; actionable rejection of invalid fields, scripts, and paths; idempotent disabled import; accurate preview; refusal of noninteractive destruction; GUI/CLI consistency; and state queries after interruption.
Record current-session CLI evidence separately from automatic Skill loading and other clients. Claude Code and WorkBuddy runtime evidence remains pending. Current scope uses CLI and local files without global configuration changes or an MCP service.