Content
# Sulde
**Task orchestration and engineering delivery for AI agents**
**English** | [简体中文](README.zh-CN.md)
[](LICENSE)
[](docs/DEVELOPMENT.md)
[](docs/DEVELOPMENT.md)
Sulde is a task orchestration and engineering delivery framework for AI agents. It covers task
definition and assignment, execution supervision, engineering checks, result verification, and
acceptance and rework, with knowledge retrieval and cross-session memory providing context.
Tools with compatible MCP/CLI interfaces can reuse the corresponding capabilities. Claude Code
and Codex adapters are included; full supervision requires host adaptation and validation.
Sulde is independently developed and maintained by an individual developer.
**Source available for noncommercial use.** See the [licensing guide](docs/LICENSING.md)
for permitted uses and historical license rights.
[Features](#features) · [Architecture](#architecture) · [Quick start](#quick-start) · [Examples](#examples) · [Documentation](#documentation) · [Contributing](#contributing) · [License](#license)
## Overview
Sulde organizes engineering work around explicit tasks: who owns each task, what it depends on,
which paths it may change, and what evidence is needed for acceptance. Dispatch instructions
target the selected host. For approved managed L3 tasks, the runtime executes in isolated Git
worktrees and verifies the resulting artifacts and execution state.
The coordinator checks evidence before advancing a managed task through implementation, task
verification, integration, system verification, and acceptance. Unresolved findings block
verification and acceptance; the coordinator can reopen work for repair and check it again.
Task decomposition, assignment, check selection, and judgment of the result remain explicit
work by the user and coordinating agent. These mechanisms do not imply that arbitrary requests
are automatically split, scheduled, or accepted.
Integration follows protocols and host capabilities. Compatible tools can use the exposed MCP and
CLI interfaces, while host adapters connect lifecycle events, permission decisions, and execution
results to the shared core. The included Claude Code and Codex adapters each operate independently
and can share local knowledge and memory when configured. The framework includes project templates
for Android, iOS, Flutter, and HarmonyOS; its core supervision and knowledge mechanisms can also
support other engineering projects.
This repository contains a **source candidate** of the full Harness. Host installation, permission
handling, and background scheduling must be verified in each target environment. See
[Development and packaging](docs/DEVELOPMENT.md) for compatibility and acceptance requirements.
## Features
- **Task definition and assignment** — Managed task contracts record an owner, dependencies, a base commit, owned paths, acceptance criteria, and evidence gates. Registration checks path ownership conflicts; state transitions require accepted dependencies.
- **Host-aware dispatch and isolated execution** — The dispatch Skill prepares instructions for the selected host. Approved managed L3 tasks use `agent-runtime.py` to run and verify work in isolated Git worktrees; ordinary interactive tasks use the current host.
- **Execution supervision** — Guardian tracks objectives, scope, user corrections, and observable Skill/MCP/tool actions through host hooks or managed execution streams.
- **Engineering checks and result verification** — Run checks chosen for the task, retain results tied to the tested inputs, and read back tool effects. The managed verifier checks task bindings, delivery reports, and terminal execution state; a passing command alone does not establish acceptance.
- **Acceptance and rework** — The managed program distinguishes implementation, task verification, integration, system verification, and acceptance. Coordinator-controlled transitions require evidence and resolved findings; reopened work must be verified again.
- **Engineering knowledge retrieval** — Keyword and vector search retrieve relevant knowledge while retaining source paths and applicability conditions for verification.
- **Cross-session memory** — Store, retrieve, and organize project and session information to recover the context needed for later tasks.
- **Constrained automation** — LIFE provides background tasks and layered governance within configured permissions and acceptance conditions.
- **Integration through compatible protocols** — Reuse MCP and CLI capabilities from compatible tools, and extend host adapters for supervision and execution. Claude Code and Codex adapters are included.
- **Extensible project toolkit** — Project diagnostics, skill and hook generators, knowledge containers, and templates for multiple platforms.
## Architecture
### Components and execution boundaries
```mermaid
flowchart TB
User["User and coordinating agent"]
subgraph Planning["1 · Task orchestration"]
Brief["Objective · Requirements · Acceptance criteria"]
Task["Managed task contract<br/>Owner · Dependencies · Base commit · Owned paths"]
Gates["Registration and readiness checks<br/>Path ownership conflicts · Accepted dependencies"]
Dispatch["Dispatch Skill<br/>Explicit target host · Task instructions"]
Brief --> Task --> Gates --> Dispatch
Brief -->|"Interactive task"| Dispatch
end
subgraph Execution["2 · Host execution"]
Host["Claude Code / Codex adapters"]
Interactive["Interactive task<br/>Current host and session"]
Managed["Approved managed L3 task<br/>agent-runtime.py · Isolated Git worktree"]
Backend["ExecutionBackend / RunHandle<br/>Provider process · Interrupt · Cleanup"]
Tools["Engineering work<br/>Files · Commands · MCP / external tools"]
Host --> Interactive --> Tools
Host --> Managed --> Backend --> Tools
end
subgraph Supervision["3 · Supervision"]
Guardian["Guardian<br/>Intent contract · Scope · Acceptance boundaries"]
Decisions["Corrections and permission decisions<br/>Current host decision route when required"]
Audit["Event and effect records<br/>Skill / tool events · Readback · Unresolved effects"]
Guardian --> Decisions
Guardian --> Audit
end
subgraph Verification["4 · Verification"]
Checks["Task-selected checks<br/>Tests · Build / lint · Integration checks"]
Evidence["Evidence artifacts<br/>Task / run / baseline · Commands · Results · Digests"]
Verify["Managed verifier<br/>Task binding · Report · Terminal state · Process cleanup"]
Review["Coordinator review<br/>Evidence gates · Findings · Acceptance criteria"]
Delivery["Accepted engineering deliverable"]
Checks --> Evidence
Evidence -->|"Managed task"| Verify --> Review --> Delivery
Evidence -->|"Interactive review"| Review
end
subgraph Context["5 · Context"]
Interfaces["Compatible tools via MCP / CLI"]
Knowledge["Engineering knowledge<br/>Retrieval · Source paths · Applicability"]
Memory["Cross-session memory<br/>Project facts · Session history"]
Sources["Checked references<br/>Read original sources before applying"]
Interfaces --> Knowledge --> Sources
Interfaces --> Memory --> Sources
end
User --> Brief
Dispatch --> Host
Task -.-> Guardian
Host -.->|"Native hooks"| Guardian
Managed -.->|"Provider event stream"| Guardian
Decisions -.->|"Scope and execution controls"| Interactive
Decisions -.->|"Pause / interrupt when required"| Backend
Tools --> Checks
Tools -->|"Effect readback"| Audit
Audit --> Verify
Backend -->|"Run result and cleanup evidence"| Verify
Brief -.->|"Context lookup"| Interfaces
Tools -.->|"Context lookup"| Interfaces
```
Solid arrows show work and evidence flow; dashed arrows show context, observed events, and
supervision. The task registration gates and managed verifier apply to the managed path;
ordinary interactive work uses the current host's tools and review process. Checks are selected
for the task rather than an unconditional test suite. Compatible MCP/CLI clients can reuse
exposed capabilities; full supervision requires a validated host adapter. Switching hosts does
not automatically transfer state or authority.
### Managed task acceptance and rework
```mermaid
flowchart TB
Planned["planned · Task registered"] -->|"Dependencies accepted"| Ready["ready · Ready for dispatch"]
Ready --> Running["running · Execute or repair"]
Running -->|"Implementation evidence"| Implemented["implemented · Change produced"]
Implemented -->|"Task verification evidence"| TaskVerified["task_verified · Task checked"]
TaskVerified -->|"Integration evidence"| Integrated["integrated · Integration checked"]
Integrated -->|"System verification evidence"| SystemVerified["system_verified · System checked"]
SystemVerified -->|"Cumulative evidence and no unresolved findings"| Accepted["accepted · Accepted by coordinator"]
Implemented -->|"Rework"| Running
TaskVerified -->|"Coordinator reopens"| Running
Integrated -->|"Coordinator reopens"| Running
SystemVerified -->|"Coordinator reopens"| Running
Running -->|"Blocker recorded"| Blocked["blocked · Work cannot advance"]
Blocked -->|"Coordinator unblocks; prerequisites rechecked"| Ready
Blocked -->|"Coordinator resumes; prerequisites rechecked"| Running
```
This diagram highlights the main delivery path and repair loops. The full state machine also
allows blocking before acceptance and explicitly superseding eligible tasks. Verification and
acceptance transitions belong to the coordinator. Evidence must match the task and tested
inputs, remain available without digest drift, and satisfy the configured gates; unresolved
findings prevent verification and acceptance. A failed check or missing evidence prevents a
transition rather than automatically repairing the task. `accepted` is terminal; further work
needs a new task.
| Boundary | Implementation and evidence |
| --- | --- |
| Task ownership, dependencies, allowed changes | [Task contract](spec/task-contract.md) · [Registration and state transitions](scripts/kb/guardian_program.py) |
| Host selection and dispatch | [Task authoring](spec/task-authoring.md) · [Dispatch Skill](skills/dispatch-task/SKILL.md) |
| Isolated managed execution | [Managed runtime](scripts/kb/agent-runtime.py) · [Process execution backend](scripts/kb/execution_backend.py) |
| Intent, corrections, and tool effects | [Intent supervision](docs/intent-guardian.md) · [Event observability](docs/event-observability.md) (Chinese) |
| Managed-run success | [Terminal invariants](scripts/kb/terminal_invariants.py): settled intent/effect/approval records, run result, and proven process cleanup |
| Host capability and context integration | [Host contract](docs/dual-runtime-contract.md) · [Retrieval contract](docs/kb-retrieval-contract.md) (Chinese) |
### Protocol compatibility
Compatibility is evaluated for the capabilities a tool uses:
| Integration surface | What a compatible tool needs |
| --- | --- |
| Knowledge and memory tools | An MCP client supporting this server's stdio transport, initialization, tool discovery, and tool calls |
| Project toolkit | Ability to invoke the documented CLI commands and consume their outputs |
| Skill instructions | Ability to load the relevant instructions and resolve their referenced commands, tools, and runtime paths |
| Full supervision and managed execution | A host adapter mapping session and tool events, native permission decisions, execution results, and process lifecycle to Sulde's contracts |
The shipped host adapters and provider selectors currently cover Claude Code and Codex. Another
tool can reuse matching interfaces; full host integration requires the corresponding adapter and
validation. An MCP connection alone does not establish compatibility with the complete supervision
workflow. See [Adding a compatible host](docs/DEVELOPMENT.md#adding-a-compatible-host).
## Quick start
For the standalone MCP release, see [Sulde MCP installation and tools](docs/MCP.md)
and [download MCP 0.2.0](https://github.com/EthanReedLabs/sulde/releases/tag/mcp-v0.2.0).
### Requirements
| Component | Requirement |
| --- | --- |
| Python | 3.10–3.14 |
| Basic tools | Git and PyYAML 6.0+ |
| Agent tool | Compatible MCP/CLI interfaces for selected capabilities; a validated host adapter for the full Harness. Claude Code and Codex adapters are included |
| Knowledge and memory engines | Additional indexing dependencies and models configured during bootstrap |
The standalone project toolkit runs without starting an agent host, model, or MCP service.
### Install the source toolkit
```sh
git clone https://github.com/EthanReedLabs/sulde.git
cd sulde
python3 -m venv .venv
```
Activate the environment and check the installation:
```sh
# macOS / Linux
. .venv/bin/activate
python3 -m pip install -r hooks/requirements.txt
python3 -B scripts/sulde.py doctor --strict
```
<details>
<summary>Windows / PowerShell</summary>
```powershell
.venv\Scripts\python.exe -m pip install -r hooks/requirements.txt
.venv\Scripts\python.exe -B scripts/sulde.py doctor --strict
```
On Windows, replace `python3` in the following examples with `.venv\Scripts\python.exe`.
</details>
`doctor` checks the source layout, basic dependencies, plugin manifests, and project toolkit.
Run the examples below from the repository root.
### Integrate an agent host
The full Harness requires a package for the selected host and initialization of the knowledge
and memory runtime:
| Host | Integration |
| --- | --- |
| Claude Code | Build the Claude plugin package and configure its runtime using the [host contract](docs/dual-runtime-contract.md) (Chinese) |
| Codex | Build a POSIX or Windows plugin package and use the repository installer to bind and verify the Codex executable |
| Other compatible tools | Connect through matching MCP/CLI interfaces; follow the [host integration requirements](docs/DEVELOPMENT.md#adding-a-compatible-host) for full supervision and execution |
Build commands, runtime dependencies, audited CLI versions, and verification requirements are
maintained in [Development and packaging](docs/DEVELOPMENT.md). Initialization can download
models and write local data; use a separate test environment for the first integration.
## Examples
### Define, dispatch, check, and accept a task
After integrating a host, start with a human-readable task brief. This illustrative brief is
not executable managed-task JSON and does not itself authorize execution:
```text
Task: cache-refresh-order
Objective: Fix stale data overwriting newer data after a cache refresh.
Owner: cache-agent; coordinator reviews the evidence and accepts or returns the work.
Dependencies: None; record prerequisite task IDs when work must wait for their acceptance.
Base: Record the verified commit before dispatch.
Scope: src/cache/** and tests/cache/**; preserve the public API.
Host: Codex for this example; select the actual target host explicitly.
Acceptance: Concurrent refresh cases and existing cache tests pass; no out-of-scope changes.
Evidence: Changed files, tested commit, check commands and results, and delivery report.
Rework: Record failing cases or missing evidence, return bounded work, then verify again.
Context: Retrieve relevant cases and read their original sources before applying them.
```
1. Define the owner, dependencies, allowed paths, and acceptance criteria using the
[task authoring specification](spec/task-authoring.md). For a managed program, translate the
brief into the [task contract](spec/task-contract.md), including its four evidence gates.
2. Use the [dispatch Skill](skills/dispatch-task/SKILL.md) to prepare instructions for the
selected host. A dispatched brief alone does not start a managed worker. Approved managed
L3 execution uses the runtime and isolated worktree described in the
[host contract](docs/dual-runtime-contract.md).
3. Run the task's engineering checks and retain evidence for the actual candidate. Report
passed, failed, skipped, and environment-blocked checks separately; verify tool effects by
readback. See [event observability (Chinese)](docs/event-observability.md).
4. The coordinator reviews the result against acceptance criteria. In a managed program,
evidence gates and unresolved findings constrain verification and acceptance. Reopen work
for repairs when needed, then verify the changed candidate before advancing it again.
### Create a project knowledge base
Initialize empty knowledge containers in a separate example directory, validate their format,
and generate an index:
```sh
mkdir -p .tmp/sulde-demo
python3 -B scripts/sulde.py kb init --root .tmp/sulde-demo
python3 -B scripts/sulde.py kb lint --root .tmp/sulde-demo
python3 -B scripts/sulde.py kb index --root .tmp/sulde-demo
```
The knowledge base lives in `.tmp/sulde-demo/knowledge/`. Its containers start empty. Follow the
[Knowledge Kit guide](docs/KNOWLEDGE-KIT.md) to add reviewed Markdown documents, then search by symptom:
```sh
python3 -B scripts/sulde.py kb search --root .tmp/sulde-demo "stale data overwrites newer data during cache refresh"
```
This CLI uses local lexical matching. The full Harness's hybrid retrieval engine is initialized
separately. An empty knowledge base returns an empty result.
## Documentation
| Topic | References |
| --- | --- |
| Core mechanisms (Chinese) | [Intent supervision](docs/intent-guardian.md) · [Host integration](docs/dual-runtime-contract.md) · [Event observability](docs/event-observability.md) |
| Task protocol | [Task authoring](spec/task-authoring.md) · [Task contract](spec/task-contract.md) |
| Knowledge and extensions | [Knowledge Kit](docs/KNOWLEDGE-KIT.md) · [Retrieval contract (Chinese)](docs/kb-retrieval-contract.md) · [Extension guide](docs/EXTENDING.md) |
| Development | [Development and packaging](docs/DEVELOPMENT.md) · [Changelog](CHANGELOG.md) · [Contributing](CONTRIBUTING.md) |
| Data and licensing | [Public data boundary](docs/PUBLIC-DATA-BOUNDARY.md) · [Licensing guide](docs/LICENSING.md) · [Notices](NOTICE) · [Third-party inventory](THIRD_PARTY_NOTICES.md) |
The project overview, development guide, licensing guide, and third-party inventory are available in English and
Simplified Chinese. Other documents retain their original language, as indicated above.
Documentation translations do not imply that CLI output or every skill is localized.
Historical Community guides describe the standalone toolkit; their older capability inventories
do not describe the current full Harness.
## Data and privacy
The repository distributes the framework and empty knowledge containers. Engineering knowledge,
project and session memory, indexes and vectors, production logs, installation receipts, internal
reports, credentials, and private Git history are not bundled. Runtime data lives in the user's
configured local Sulde directory. Model calls and external services follow the actual deployment's
data configuration.
Tests should use synthetic data. Before sharing logs, filing issues, or distributing a derived
package, review the [public data boundary](docs/PUBLIC-DATA-BOUNDARY.md) and remove sensitive content.
## Contributing
Documentation fixes, reproducible bug reports, platform compatibility improvements, and
improvements to the reusable framework and toolkit are welcome.
1. Describe the issue, reproduction steps, and expected behavior in [Issues](https://github.com/EthanReedLabs/sulde/issues).
2. Follow the [contribution guidelines](CONTRIBUTING.md) to establish scope; discuss core protocol or license changes first.
3. Submit a pull request focused on one issue and include verification results.
Do not post raw sensitive material in public issues. Contact the
[maintainer](mailto:eric.gao.tech@gmail.com) when needed. Contributors retain their copyright;
the repository's contribution licensing terms apply.
## License
New material released under the current terms uses the
[PolyForm Noncommercial License 1.0.0](LICENSE). It allows use, modification, and redistribution
for its permitted purposes and **does not grant commercial use**. Internal commercial development,
paid client delivery, resale, and commercial hosting are outside that grant; the standard license's
express permissions for educational, charitable, and other specified organizations remain intact.
Sulde is **source available**. Previously granted MIT and BSL rights remain effective for historical
material, and the new license has no automatic MIT conversion date. See the
[licensing guide](docs/LICENSING.md) for the full scope.
## Star History
[](https://www.star-history.com/#EthanReedLabs/sulde&Date)
Connection Info
You Might Also Like
No recommendations available