@staavanothanh/dsh-ecc

Readme

# dsh-ecc

`dsh-ecc` is a DeepSeek Harness (DSH) plugin that adapts the most useful
runtime surfaces of [Everything Claude Code (ECC)](https://github.com/affaan-m/ECC)
to DSH. It is an adapter package, not a fork of DSH and not a replacement for
Claude Code or Codex.

The plugin currently provides:

- ECC agent Markdown as persona and instruction resources for child agents.
- ECC skills through the DSH skill provider.
- Model/provider/reasoning-effort catalog injection through DSH lifecycle hooks.
- `spawn`, with explicit provider, model, reasoning effort, ECC
  persona, and continuable follow-up support.
- `spawn_fork`, with the same route/persona/follow-up contract while seeding
  the child from the parent session's completed turns.

## Release status

| Item | Current value |
| --- | --- |
| Package | `@staavanothanh/dsh-ecc@0.6.0` |
| Bundled ECC | `v2.2.0` |
| ECC commit | `d8409a4b0813771235555e32e3d8046a73988bfa` |
| DSH peer floor | `>=0.1.0-rc.5` |
| Validated DSH runtime | `0.1.1-rc.1` |
| Distribution | GitHub release tarball (canonical install channel) |

`0.6.0` is the rc1 compatibility release that includes the public `spawn`
tool, durable cold-resume binding recovery, and the new `spawn_fork` tool.
There is intentionally no `spawn_subagent` compatibility alias.

## v0.6.0 highlights

`spawn_fork` seeds a continuable child from the parent's completed turns,
supports explicit provider/model/effort/persona selection, durable follow-up,
and cold-resume. DSH core remains unchanged. The release validation includes
61 passing tests and 81.84% branch coverage.

The bundled ECC revision is recorded in `assets/ecc/revision.json`. A release
must use a pinned ECC tag or commit. The plugin does not fetch `main` or
`latest` during startup. The current ECC version comes from the upstream
version metadata; the upstream repository does not provide a `v2.2.0` tag, so
future remote synchronization must use the verified commit SHA rather than
assuming that tag exists.

## Capability mapping

| ECC surface | DSH implementation | Runtime behavior |
| --- | --- | --- |
| `agents/*.md` | `EccPersonaCatalog` + `spawn.persona` | Injects persona/instructions into the child session. The adapter strips upstream `tools` and `model` metadata; the child inherits the parent effective DSH tool scope. |
| `skills/*/SKILL.md` | `EccSkillProvider` | Discovers, validates, and loads ECC skill bodies from the bundled revision. |
| ECC agent routing metadata | `PersonaNormalizer` | Ignores upstream `tools` and `model` fields. `spawn` owns the provider/model/effort selection. |
| ECC MCP entries | Compatibility report only | MCP servers are not bundled or silently mapped. Configure DSH MCP servers separately. |

The plugin installs the complete agents and skills surface. Agents, skills and
the model-catalog lifecycle adapter are active in the current runtime. The MVP
has no per-surface enable/disable switch.

## `spawn`

`spawn` is a native DSH tool implemented by dsh-ecc. It does not call
the existing DSH `subagent` or `workflow` tool from inside another tool.

Start a child:

```json
{
  "operation": "start",
  "prompt": "Review the authentication boundary and report concrete risks.",
  "provider": "deepseek-official",
  "model": "deepseek-v4-flash",
  "effort": "high",
  "persona": "ecc:security-reviewer",
  "label": "security-review"
}
```

Continue the same child:

```json
{
  "operation": "followup",
  "childId": "<durable-child-id>",
  "prompt": "Now verify the highest-risk finding against the current tests."
}
```

`effort` is resolved against the selected DSH model's published reasoning
efforts and is persisted with the child request selection. `persona` resolves
to one file under the bundled ECC `agents/` root; raw Markdown is not accepted
from the model.

## `spawn_fork`

`spawn_fork` has the same explicit provider/model/effort, optional ECC persona,
durable binding, and `operation: "followup"` contract as `spawn`. Its only
transport difference is that it uses DSH's native `fork` continuable provider.
The provider seeds the child with the parent session's completed turns, so the
child can inspect earlier conversation context. The current in-flight parent
turn is deliberately excluded from the seed.

The child still inherits the effective parent DSH tool scope. dsh-ecc does not
call the model-facing `subagent_fork` tool; it calls the public
`ctx.subagents.startContinuable` runtime seam with `provider: "fork"`. Follow-up
uses the same durable fork binding and route/persona snapshot.

Because DSH's fork provider documents a caveat around composing fork seeds with
continuable setup/report prefixes, the adapter tests this combination explicitly.
A host that does not expose the `fork` provider returns `TRANSPORT_UNAVAILABLE`.

## Skill invocation and name collisions

DSH's native skill registry accepts kebab-case names only. Its public registry
does not accept a colon in a candidate name, so the internal ECC identifier may
be `ecc:accessibility` while the DSH candidate remains `accessibility`.

The intended adapter contract is:

```text
/ecc:<name>  -> the ECC skill with that name
/<name>      -> the native/project DSH skill
```

The `0.6.0` runtime currently registers ECC candidates in the native flat DSH
catalog. Therefore the Web picker displays plain names and `/name` is the
working entrypoint. The `/ecc:<name>` client and host alias bridge is a planned
compatibility fix; it must be implemented before claiming strict namespace
support in a release.

Until that bridge exists, a project skill with the same name can shadow the ECC
candidate according to DSH scope and rank rules. Do not assume that both bodies
are available under the same name.

## Model catalog lifecycle

The current runtime registers the model-catalog lifecycle adapter:

1. `llm/adapters-updated` invalidates the in-memory provider/model/effort catalog.
2. `agent/pre-step` rebuilds the catalog, writes `.dsh/model-catalog.yaml` when
   a workspace `cwd` is available, and injects one compact catalog message.
   It checks the durable session surface and re-injects the catalog when DSH
   compaction shadows the previous catalog message.

## Installation

Install the scoped GitHub release tarball into a DSH profile:

```powershell
dsh plugin --profile web add https://github.com/staavanothanh/dsh-ecc/releases/download/v0.6.0/staavanothanh-dsh-ecc-0.6.0.tgz
```

Do not use `dsh plugin --profile web add dsh-ecc`: that unscoped npm name is
owned by another project. The tarball URL pins this repository and release.

The package is installed under the selected DSH profile. The logical package
layout is:

```text
<DSH_HOME>/profiles/<profile>/
  package.json
  node_modules/@staavanothanh/dsh-ecc/
    dist/
    assets/ecc/
      agents/
      skills/
    cordis.patch.yml
    LICENSE
    NOTICE
```

The runtime resolves the package root from the DSH module loader. It does not
read an author's checkout, the current project, or a hard-coded Windows path.

Local `file:` installation is for development only. A local package containing
`node_modules` can trigger pnpm junction or symlink errors on Windows; build and
pack the artifact, then test the resulting tarball instead.

Update or roll back a profile with an exact release tarball:

```powershell
# Existing profiles should remove the previous scoped tarball first.
dsh plugin --profile web remove @staavanothanh/dsh-ecc
dsh plugin --profile web add https://github.com/staavanothanh/dsh-ecc/releases/download/v0.6.0/staavanothanh-dsh-ecc-0.6.0.tgz
```

For rollback, add the previous known-good tarball explicitly. Keep the release
tag and ECC commit available until the new release passes the clean-profile
smoke test.

## Configuration boundary

The package patch mounts the adapter with a bundled, pinned ECC source:

```yaml
eccSource:
  mode: bundled
  repository: https://github.com/affaan-m/ECC.git
  ref: d8409a4b0813771235555e32e3d8046a73988bfa
  updatePolicy: explicit
transportProvider: spawn
```

The bundled package also records the human-readable ECC version `v2.2.0` in
`assets/ecc/revision.json`. A remote mode must resolve and verify the commit
before activation; it must not infer a ref from the version string.

Remote revision caching and atomic activation are post-MVP features. They must
accept only an explicit tag or commit, verify the downloaded snapshot, and keep
the last known-good revision for rollback.

## Development and verification

Requirements: Node.js `>=22.19.0` and pnpm.

```powershell
pnpm install
pnpm typecheck
pnpm test
pnpm build
pnpm pack:check
```

Before a release, also install the generated tarball into a temporary
`DSH_HOME` profile and verify:

- the plugin row loads without changing DSH core;
- all expected ECC agents and skills are discoverable;
- `spawn` starts and follows up with provider/model/effort selection;
- `spawn_fork` starts from completed parent turns and accepts follow-up;
- `spawn` and `spawn_fork` do not reuse each other's durable bindings;
- follow-up can recover a child binding from a DSH rc1 live/persisted session;
- persona child inherits the parent effective tool scope and can use the native
  continuable-child reporting surface;
- package contents contain `dist`, `assets/ecc`, `cordis.patch.yml`, `LICENSE`,
  and `NOTICE`.

## ECC runtime synchronization

ECC changes independently from dsh-ecc. The release process therefore treats
the ECC revision as an explicit input and publishes an immutable snapshot with
each dsh-ecc release. The detailed update, compatibility, release, and rollback
plan is in [`docs/plans/ecc-runtime-sync.md`](docs/plans/ecc-runtime-sync.md).

The short rule is:

```text
ECC tag/commit -> synchronized asset snapshot -> compatibility checks
-> dsh-ecc version bump -> package/release smoke test -> publish
```

## Documentation

- [Plugin specification](docs/specs/dsh-ecc-plugin-spec.md)
- [Architecture](docs/architecture/dsh-ecc-architecture.md)
- [Compatibility research](docs/research/compatibility-matrix.md)
- [Spawn fork TDD evidence](docs/testing/spawn-fork-tdd.md)
- [ECC runtime synchronization plan](docs/plans/ecc-runtime-sync.md)

## License and attribution

dsh-ecc is distributed under the license in [`LICENSE`](LICENSE). ECC source
attribution and the bundled-revision notice are recorded in [`NOTICE`](NOTICE).