@ttxl314/dsh-skill-lord-serf

Readme

# @ttxl314/dsh-skill-lord-serf

English | [中文](README.zh-CN.md)

A **DeepSeek Harness (DSH) plugin** port of [ttxl314/lord-serf-agent-protocol-SKILL](https://github.com/ttxl314/lord-serf-agent-protocol-SKILL) (protocol 0.5): it ships the `lord` and `serf` skills so DSH can act as the Lord (orchestrator) and as the Serf (executor).

## The protocol

A file-based multi-agent orchestration protocol with the lifecycle:

```text
plan → package → dispatch → execute → submit → review → decide
```

- **Lord** owns planning, task packages, Serf dispatch, the authoritative task state source, review decisions, and final acceptance.
- **Serf** owns bounded execution of one Lord-issued task package, self-validation of actual outputs, and one submission report (`REVIEW` / `BLOCKED` / `CHANGE_REQUEST`).
- Chat is notification only; project state, requirements, evidence, and decisions live in files (`TASKS.md`, `TASKS/`, `REVIEWS/`, `BLOCKERS/`, `CHANGE_REQUESTS/`).

## Repository structure

```text
dsh-skill-lord-serf/
├── package.json          # dsh.bundle manifest; no runtime deps, peers only
├── cordis.patch.yml      # bundle patch layer: registers the plugin row
├── lib/index.js          # cordis plugin: file-backed provider on ctx.skills
├── test/self-test.mjs    # self-test suite
└── skills/
    ├── lord/
    │   ├── SKILL.md          # DSH-adapted (DSH Bindings mapping table)
    │   ├── assets/schemas/   # task-package / micro-task / dispatch-instruction schemas
    │   ├── assets/templates/ # task-package / dispatch-instruction / project templates
    │   └── references/       # scaling, review, change control, recovery, adapters, ...
    └── serf/
        ├── SKILL.md
        ├── assets/schemas/   # submission-envelope / review-report schemas
        ├── assets/templates/ # REVIEW / BLOCKED / CHANGE_REQUEST templates
        └── references/       # intake, subagent fan-out, self-validation, reporting, ...
```

Each `skills/<name>/SKILL.md` carries DSH skill frontmatter (`name` + `description`), so one file serves two installation paths:

1. **Plugin**: at startup `lib/index.js` registers a file-backed provider on `ctx.skills` (rank 250) exposing both skills with `resourceBase: { kind: 'directory', path: <skill dir> }` in the global layer, available to every session. `get()` re-reads the body on every load, so content edits take effect immediately.
2. **Filesystem**: copy (or link) `skills/lord` and `skills/serf` into `<project>/.dsh/skills/` or `~/.dsh/skills/`; `dsh-skill-filesystem` discovers them without a restart.

## DSH bindings

| Protocol concept | DSH mechanism |
|---|---|
| Serf executor | `subagent` tool (one subagent per task package) or a separate DSH session |
| Serf sub-work fan-out | `subagent` tool for bounded, disjoint sub-steps inside the task boundary; see `skills/serf/references/dsh-subagents.md` |
| `$serf` invocation | `/serf` user gesture, or a `skill(name='serf')` call inside the dispatched subagent |
| `$lord review <path>` / `$lord resolve <path>` | `/lord` gesture plus the report path; a subagent Serf's final message already reaches Lord |
| State source / packages / reports | Plain workspace files read and written with the filesystem tools |
| Long-running orchestration | DSH goal tools |

## Install

### A. As a bundle (global)

Install from GitHub — this package ships prebuilt ESM, so there is **no build step and no `prepare`-script permission** to grant; pinning a commit is recommended:

```sh
dsh plugin --profile <name> add github:ttxl314/dsh-skill-lord-serf#<commit-sha>
```

Or link a local checkout:

```sh
dsh plugin --profile <name> add ./dsh-skill-lord-serf
```

`dsh plugin` adds the package to the profile's dependencies and `dsh.profile.bundles`; the bundle's own `cordis.patch.yml` registers the plugin row. Restart the web service afterwards; the entry then appears in the GUI's Settings → Plugins inventory.

### B. As filesystem skills (no restart, project-scoped)

```powershell
New-Item -ItemType Junction -Path .dsh\skills\lord -Target <checkout>\skills\lord
New-Item -ItemType Junction -Path .dsh\skills\serf -Target <checkout>\skills\serf
```

The skill watcher picks the catalog up immediately.

## Usage

- **Lord session**: say "orchestrate this project with the Lord protocol" or type `/lord`; follow the workflow to produce task packages and dispatch instructions and maintain `TASKS.md`.
- **Dispatch a Serf**: Lord dispatches through the `subagent` tool; the subagent prompt is the generated `assets/templates/dispatch-instruction.md`, and it must load the `serf` skill before executing the task package.
- **Serf session**: type `/serf` or hand it a task-package path; it may fan out sub-work through `subagent` inside the boundary (`references/dsh-subagents.md`), then writes the report from a template and ends with the report path.

## Self-test

```powershell
node test\self-test.mjs
```

The suite runs 26 checks: provider contract (apply/list/get/invalidate), SKILL.md frontmatter parsing, residual Codex-marker scan, existence of every referenced resource path, compilation of all 6 JSON Schemas (draft 2020-12), positive and negative representative payload validation (including v0.3 field rejection), and template/schema const agreement. It resolves `ajv`, `ajv-formats`, and `yaml` from the local DSH profile (`$DSH_HOME`).

An end-to-end drill is also supported: Lord creates a schema-validated task package → a `subagent` loads the `serf` skill and executes → the report passes the `micro-review-report`/`submission-envelope` schemas → Lord verifies actual outputs and updates the authoritative state.

## Dependencies

- `@deepseek-ai/cordis` ^4.0.1 (peer)
- `@deepseek-ai/dsh-skill` ^0.1.0-rc.6 (peer, provided by the `@deepseek-ai/dsh-base` bundle)

## Differences from upstream

- All `$lord`/`$serf` (Codex commands) → `/lord`/`/serf` (DSH skill gestures).
- `dispatch-instruction`'s `worker_invocation` const is `/serf`; the Invocation section describes DSH `subagent` dispatch; Execution Requirements gained a subagent fan-out clause.
- Added `serf/references/dsh-subagents.md` (DSH-specific Serf fan-out rules) and an "Execution Capabilities (DSH)" section in the coding adapter.
- Removed the Codex-only `agents/openai.yaml`.
- The protocol itself (field names, micro/standard/full task profiles, status vocabulary, report paths, non-negotiables) matches upstream 0.5 exactly, so task packages and reports remain interoperable across platforms.

## License

Derived from [ttxl314/lord-serf-agent-protocol-SKILL](https://github.com/ttxl314/lord-serf-agent-protocol-SKILL) (MIT); this port is released under the same [MIT](LICENSE) license.