dsh-plugin-module-driven-dev

Readme

<div align="center">

# 🧩 dsh-plugin-module-driven-dev

**Module-Driven Development (MDD) plugin for DeepSeek Harness**

Decompose any requirement into a module tree, let each module be designed and generated by an **independent agent**, have the **main agent orchestrate, integrate and debug**, and **fully regenerate from design** whenever a design or requirement changes.

[![DSH plugin](https://img.shields.io/badge/DeepSeek%20Harness-plugin-4D6BFE)](https://github.com/phantomSuying/dsh-module-driven-develop)
[![Version](https://img.shields.io/badge/version-1.1.0-blue)](package.json)
[![Skill](https://img.shields.io/badge/skill-module--driven--dev-22c55e)](skills/module-driven-dev/SKILL.md)
[![Stars](https://img.shields.io/github/stars/phantomSuying/dsh-module-driven-develop?style=social)](https://github.com/phantomSuying/dsh-module-driven-develop)
[![License](https://img.shields.io/github/license/phantomSuying/dsh-module-driven-develop)](LICENSE)

</div>

---

## Table of Contents

- [Features](#-features)
- [Example project](#-example-project--auth-service)
- [Installation](#-installation)
- [Usage](#-usage)
- [How it works](#-how-it-works)
- [Project structure](#-project-structure)
- [Development](#-development)
- [License](#-license)

## ✨ Features

| # | Feature | How it works |
|---|---------|--------------|
| 1 | **A programming plugin** | A skill-driven software development protocol covering decomposition, design, implementation, integration, debugging and change management. |
| 2 | **Recursive requirement decomposition** | Requirements → modules → submodules, decomposed level by level until every leaf module is small enough for a single agent to design *and* implement independently (termination rules in [`references/decomposition.md`](skills/module-driven-dev/references/decomposition.md)). |
| 3 | **Independent agents generate code** | Each leaf module is fully generated by its own sub-agent; a module with submodules acts as the next-level main agent and dispatches recursively. The main agent orchestrates, integrates and debugs ([`references/agent-protocol.md`](skills/module-driven-dev/references/agent-protocol.md)). |
| 4 | **Design change ⇒ full code regeneration** | The design document is the single source of truth. Bumping its revision archives the old code, wipes the module directory, and regenerates *everything* from the new design — patching old code is forbidden. |
| 5 | **Requirement changes propagate recursively** | The main agent dispatches a change-analyst sub-agent to locate affected modules (including indirect dependencies); each module agent decides whether to push the task further down to its submodule agents, then redesigns and regenerates. |

## 🎯 Example project: [auth-service](https://github.com/phantomSuying/auth-service)

A real project **developed end-to-end with this plugin** — a small JWT authentication service (Python 3.12 / FastAPI + SQLite), fully built by the MDD workflow.

| Module id | Python package | Responsibility |
|-----------|----------------|----------------|
| `common/contracts` | `authsvc_contracts` | Shared DTOs (pydantic), business exceptions, rule constants |
| `common/config` | `authsvc_config` | Environment-based configuration (`AUTH_*` prefix) |
| `core/security` | `authsvc_security` | PBKDF2-SHA256 password hashing, JWT issue/verify, token hashing |
| `data/db` | `authsvc_db` | SQLite connection (WAL, foreign keys) and `users`/`sessions` schema |
| `data/user-store` | `authsvc_user_store` | User table storage |
| `data/session-store` | `authsvc_session_store` | Session lifecycle (create / query / revoke) |
| `auth/service` | `authsvc_auth` | Auth orchestration: register / login / refresh / logout / me |
| `api/routes` | `authsvc_api` | FastAPI HTTP layer: routes, DI, unified error handling |

The `.mdd/` workspace in that repo records the whole process:

- **`manifest.md`** — the module tree: 8 leaf modules + root, acyclic dependency graph, `integrated` status, revision 1;
- **`designs/`** — 9 design documents (one per module + root) with contract tables, dependency references, acceptance criteria and revision history;
- **`logs/schedule.md`** — the delegation log: 5 topological batches (B1–B5) of independent sub-agents, then P4 integration and P5 smoke test;
- **`logs/<module>/report.md`** — per-module delivery reports.

**Verification results (run locally):**

- ✅ **169 test cases pass** (module unit tests + API end-to-end, exit 0);
- ✅ **15/15 HTTP smoke checks pass** — register, duplicate 409, login, wrong-password 401, `/me`, refresh-token **rotation (replay protection)**, logout revocation, validation errors.

Clone it and explore — every design decision, delegation and test is documented in `.mdd/`.

## 📦 Installation

### Option A — One-click install (profile bundle, recommended)

The package is a self-contained Cordis bundle: [`index.js`](index.js) locates the bundled `skills/` directory via `import.meta.url` and registers a skill provider — **no hardcoded paths**, works from any machine and any install source:

```powershell
# One command installs into a profile (web, or any profile name). Restart dsh afterwards.
dsh plugin --profile web add git+https://github.com/phantomSuying/dsh-module-driven-develop.git
```

After installation every agent session under that profile has the `module-driven-dev` skill in its catalog.

### Option B — Copy the skill directory (no pnpm / profile)

DSH discovers skills from fixed roots (`<project>/.dsh/skills`, `~/.dsh/skills`, `~/.agents/skills`):

```powershell
# Install for the current project (immediately available in this directory's sessions)
.\scripts\install.ps1 -Scope Project

# Install user-wide (available in every project)
.\scripts\install.ps1 -Scope User
```

### Option C — From a packed tarball

```powershell
npm pack
dsh plugin --profile web add C:\path\to\dsh-plugin-module-driven-dev-1.1.0.tgz
```

### Verify

In a new session, ask the agent to list available skills (or simply say "use module-driven development mode"). `module-driven-dev` should appear.

## 🚀 Usage

Just talk to the agent:

- **"用模块驱动开发实现 \<requirement\>"** → main agent runs P0–P5: decompose the module tree (`.mdd/manifest.md`) → design each module (`.mdd/designs/`) → dispatch independent sub-agents to generate code (`.mdd/code/`) → integrate, build, debug.
- **"把 \<module\> 的设计改成 …"** → design change: revision +1, archive old code, regenerate everything from the new design.
- **"需求调整：\<new requirement\>"** → a change-analyst sub-agent locates the affected modules (including propagation along the dependency graph), module agents recursively decide whether to push the task further down, then redesign + regenerate + re-integrate.

All artifacts live under `.mdd/` (layout: [`references/workspace-layout.md`](skills/module-driven-dev/references/workspace-layout.md)).

## 🧠 How it works

```
dsh-plugin-module-driven-dev        ← Cordis bundle (patch layer, not executed itself)
  └─ cordis.patch.yml inserts one row:
       skill-mdd-provider            ← loader entry (id)
         name: dsh-plugin-module-driven-dev
           └─ index.js               ← self-locating plugin (import.meta.url → ./skills/)
                └─ ctx.skills provider: module-driven-dev
                     └─ discovers → module-driven-dev (the skill, SKILL.md)
                          └─ the main-agent protocol: P0 启动 → P1 拆解 → P2 设计
                             → P3 独立 agent 生成 → P4 集成 → P5 调试 → P6 变更
```

The skill is the product; the provider row is the infrastructure that makes it discoverable.

## 📁 Project structure

```
dsh-plugin-module-driven-develop/
├── index.js                 # Self-contained skill provider (portable, no absolute paths)
├── cordis.patch.yml         # Bundle patch: mounts index.js into the host composition
├── package.json             # Bundle metadata (dsh.bundle.patch)
├── scripts/
│   └── install.ps1          # Skill-directory installer (Project / User scope)
├── test-provider.mjs        # Functional test for the skill provider
└── skills/
    └── module-driven-dev/   # The plugin core: skill bundle
        ├── SKILL.md                    # Main-agent work protocol (six phases)
        └── references/
            ├── decomposition.md        # Decomposition algorithm & leaf termination rules
            ├── agent-protocol.md       # Sub-agent dispatch protocol + prompt templates
            ├── workspace-layout.md     # .mdd/ workspace conventions
            └── templates/
                ├── module-design.md    # Module design-document template
                ├── module-manifest.md  # Module-tree manifest template
                └── change-request.md   # Requirement-change template
```

## 🛠 Development

```powershell
npm pack                                        # Build the distributable tarball
node test-provider.mjs                          # Verify the skill provider (discovery + load)
.\scripts\install.ps1 -Scope Project            # Install the skill for local testing
```

The provider is deliberately dependency-free: no runtime imports beyond Node built-ins, so the bundle installs anywhere.

## 📄 License

[MIT](LICENSE) © 2026 phantomSuying