Foreword¶

When using DeepSeek Harness (DSH) for long-running task development, the common pain points often lie not in “the model not being smart enough,” but in loss of process control: the agent modifies code without first grasping the project boundaries, declares “done” without verification evidence, or even a simple bug fix spirals into an extensive workflow. The community plugin hub, SkillHub, features a workflow plugin called Aegis (ganyuanran/aegis), with over 1100 GitHub stars, maintained by GanyuanRan. It packages “baseline-first, evidence verification, and drift checks” into an installable method pack, with a clear goal: reduce rework, ensure more stable changes, and stop blindly trusting “it’s done.”

The core philosophy of DeepSeek Harness is “everything is a plugin”; directories like SkillHub facilitate discovery and installation but have no official affiliation with DeepSeek or High-Flyer. The following installation instructions are based on the plugin repository and the original GitHub documentation.

What This Is¶

Aegis is an Aegis Method Pack, not a background daemon or a standalone runtime core. In one line: it ensures AI coding agents align with the real project baseline (owners, contracts, boundaries) before making changes, prove results with fresh evidence before completion, use a fast path for simple tasks, and only invoke the full ceremony for complex ones.

The plugin is categorized under “Workflow” in the SkillHub directory, currently at version v2.8.8; the GitHub repository uses the MIT license. The project’s README draws inspiration from Jesse Vincent’s Superpowers concept, extended with architecture and evidence layers tailored for real software projects.

Core Features & Highlights¶

Before modifying code, the agent aligns with the project’s current state: module ownership, interface contracts, change boundaries. The goal is to stop “guessing architecture, guessing conventions” and reduce rework at the source.

2. Evidence Verification, Say Goodbye to “Feeling Done”¶

Completion declarations must include verifiable evidence, coverage details, and residual risk notes. Users review an evidence chain, not a verbal confirmation.

3. Complexity Governance: No Fuss for Simple Tasks¶

Trivial requests follow a fast path; the full ceremony is only deployed when task risk genuinely warrants it. The README calls this Workflow Quality: keep light work light, and add process only for heavy work.

4. Retirement & Drift Management¶

Tracking or cleaning up obsolete fallback paths and deprecated implementations prevents “ghost code” silently accumulating in repositories; continuous drift checks are performed during long-running tasks.

5. One Set of Discipline Across Multiple Hosts¶

The same discipline works across hosts supporting Skills, including Codex, Claude Code, OpenCode, Kimi, and DeepSeek Harness. For DSH users, the official documentation at docs/README.deepseek-harness.md provides a dedicated profile-plugin installation and verification process.

6. Quantifiable Benchmark Reference (with Boundary Notes)¶

The project conducted a frozen A/B benchmark on Aegis 2.7.6: across 20 use cases and 120 effective runs, the contract pass rate rose from 61.67% to 93.33%, and unsafe outcomes dropped from 13.33% to 0%. The README explicitly marks this as bounded reference evidence, not a universal quality promise or final completion authority; the review is technical and not an independent human audit. When writing, retain this data along with its qualifications.

Installation & Activation¶

Before installation, ensure dsh and pnpm are installed on your machine (Harness’s dsh plugin forwards to pnpm; merely using npx to start the Web UI is insufficient):

dsh --version
pnpm --version

Default Method: Profile Plugin Bundle Installation¶

Take the Web profile as an example; install separately in each profile where you want to enable Aegis (installing in one profile does not automatically apply to another):

dsh plugin --profile web add "git+https://github.com/GanyuanRan/Aegis.git"

If using a Headless profile, run the following separately:

dsh plugin --profile headless add "git+https://github.com/GanyuanRan/Aegis.git"

To pin a version, specify the release tag:

dsh plugin --profile web add "git+https://github.com/GanyuanRan/Aegis.git#v2.8.8"

Note: The official documentation requires the full git+https:// form; do not abbreviate it as github:GanyuanRan/Aegis, as some DSH/pnpm combinations parse the shorthand as an SSH path, causing installation failure if GitHub SSH keys are not configured.

After installation, do not re-register in paths like $DSH_HOME/skills or the project’s .dsh/skills to avoid duplicate skill ownership with the Bundle and routing interference.

Installation Verification¶

First, confirm the profile lists aegis:

dsh plugin --profile web list --depth 0
dsh --profile web --dump-config

The dump result should show id: aegis-method-pack. Then, in the method pack root directory (typically $DSH_HOME/profiles/web/node_modules/aegis), run the doctor script. Do not run it in your target business project directory:

cd <aegis-method-pack-root>
python scripts/aegis-doctor.py --write-config --json

The JSON output must include "ok": true, "workspaceSupport": "available", and "configStatus": "configured" to be considered structurally installed. After restarting the profile, in a new session, verify that the skill directory contains entries like using-aegis, systematic-debugging, and verification-before-completion, and use a representative natural language task to confirm routing enters the Aegis decision path.

Compatibility Mode (Only When Necessary)¶

When the preview Bundle API is unavailable, policies prohibit third-party profile plugins, or pnpm cannot be provided to the plugin manager, use the direct-child compatibility installation described in the documentation; this mode requires explicit user approval and cannot be enabled alongside the Bundle. General users should prioritize the default Bundle path above.

Typical Usage Examples¶

After installation and restarting the host, most scenarios work with natural language—Aegis matches the method to the task. For more explicit control, use the following trigger patterns.

Routine Diagnosis and Repair:

Why does this login failure happen? Diagnose it before changing code.
Aegis goal: Fix the auth refresh bug without rewriting the auth system.

Decision Interview (Ask Only, No Changes):

Grill me on whether we should ship a hosted version first.

Review & First-Principles Stress Test:

Review this diff independently before I merge it.
aegis:first-principles-review

Explicit TDD (Default TDD Mode is Off):

TDD Route: strict

Or enable auto TDD routing in the method pack root directory:

cd <aegis-method-pack-root>
python scripts/aegis-doctor.py tdd-mode auto

Update an Installed Method Pack:

dsh plugin --profile web update aegis

You can also use natural language update Aegis or an explicit request aegis:update; the local update script routes based on the current host.

For non-trivial project work, Aegis can passively reuse domain terminology from CONTEXT.md or CONTEXT-MAP.md; domain modeling is only activated when terms need resolution, disambiguation, renaming, or conflict resolution. Pending domain decisions remain with the user.

Applicable Scenarios & Considerations¶

Who It’s For, What Scenarios:

Using DSH or other AI coding hosts for multi-turn, multi-file changes, concerned about the agent “drifting further off track.”
Wanting to align architecture and contracts before changes, with reviewable evidence before completion.
Teams already using the Skill / method pack ecosystem, seeking a cross-host reusable workflow discipline.

Important Notes:

Permissions & Trust Boundaries: The plugin runs with the current dsh process permissions. Before installation, read the source code and MIT license to ensure it aligns with your team’s security policies.
Not the Final Authority: Aegis is a runtime-ready method pack, not an authoritative GateDecision or final completion arbiter; user instructions and target project rules take precedence over Aegis guidance.
DSH is Still Developer Preview: Official warnings indicate potential breaking compatibility changes; the documentation records the implemented Bundle structure support but does not guarantee that the current version’s real-time routing quality has been fully validated.
Do Not Mix Installation Methods: Do not activate the Bundle and direct-child compatibility view simultaneously; avoid running project-level .dsh/skills experiments in parallel with the Bundle in the same profile to ensure routing evidence remains reliable.
Activation Mode: The default auto mode delays injecting a concise using-aegis guide at session boundaries. For purely explicit invocation, execute python scripts/aegis-doctor.py activation-mode explicit in the method pack root directory and restart the host.

Closing¶

If you’re tired of “watching the agent not to make random changes or fake completion” during long tasks, Aegis offers an installable, verifiable path: align with the baseline first, let evidence speak, and keep simple things simple. It cannot replace your engineering judgment, but it can compress common points of失控 into reusable method disciplines.

SkillHub Directory: https://www.skillhub.cn/plugins/GanyuanRan/Aegis
GitHub Repository: https://github.com/GanyuanRan/Aegis
DeepSeek Harness Installation Guide: https://github.com/GanyuanRan/Aegis/blob/main/docs/README.deepseek-harness.md

Aegis: Enabling DeepSeek Harness Agents to "Align with Baseline First, Act Second, and Conclude with Evidence"