dsh-project-handbook

Company-grade project handover / onboarding handbook generator for DeepSeek Harness — 项目交接与新人熟悉文档.

One command pair turns a real repository into a Markdown handover pack a new engineer can act on in their first week:

.handover/
├── PROJECT-HANDBOOK.md        # 15-section handover manual (公司项目级)
├── ONBOARDING-CHECKLIST.md    # day-one / week-one checklist with sign-off
├── GLOSSARY.md                # domain + internal jargon (comprehensive profile)
├── RUNBOOK.md                 # failure cards, rollout, data repair (comprehensive)
├── inventory.json / .md       # the fact base every claim is checked against
└── check-report.md            # what the quality gate found

Why it is different from "ask the model to write a README"

• Evidence or 待确认. Every claim carries a path, path:line or the exact command that proves it. Anything the repository cannot answer (deploy target, on-call rotation, business rules, why a decision was made) is written as an explicit open question instead of plausible-sounding prose.
• A deterministic scan first. project-inventory.mjs walks the repository and reports languages, manifests, framework signals, CI jobs and their commands, deployment artifacts, env-var names, migrations, entry points, test layout, git history and top authors, technical-debt markers, committed credential-shaped files — plus a pre-computed verifyFirst list of the gaps.
• A real quality gate. check-handbook.mjs blocks missing sections, stubs, unfilled placeholders, speculation wording, ✅ badges with no citation, cited paths that do not exist, links and anchors that do not resolve, package scripts that no package.json defines, secrets pasted into the document, and claims that contradict the inventory.
• Stack-aware reconnaissance. Recon playbooks for Java/Spring, Go, Python, Node/TypeScript, frontend, data/AI and legacy-ops projects tell the agent exactly which files to open and which facts to extract.
• Safe by construction. Read-only reconnaissance; credentials are never opened or quoted; no builds, migrations, deploys or commits happen while producing the document.

Install

From GitHub (works today, no npm publish needed):

dsh plugin --profile web add github:Gan-lang/dsh-project-handbook

From npm — once the package is published there:

dsh plugin --profile web add dsh-project-handbook

From a local checkout:

dsh plugin --profile web add /absolute/path/to/dsh-project-handbook

Whichever source you use, finish by adding the bundle to the profile's ordered bundle list in $DSH_HOME/profiles/web/package.json:

{
  "dsh": {
    "profile": {
      "bundles": ["@deepseek-ai/dsh-base", "@deepseek-ai/dsh-web-app", "dsh-project-handbook"]
    }
  }
}

Restart dsh web. The plugin mounts only the bundled skill (no host services, no client code): cordis.patch.yml registers a @deepseek-ai/dsh-skill-filesystem provider whose bundledSkillDir is resolved from the installed package identity, so the skill appears in the session catalog as project-handbook.

Use

Ask in any session:

生成这个项目的交接文档，要公司项目级、新人能直接上手的那种

The skill:

1. runs scripts/project-inventory.mjs (--root . --out .handover/inventory.json);
2. reads the matching stack playbook(s) and the code that carries the project story;
3. fills the templates in assets/ (profile compact / standard / comprehensive);
4. runs scripts/check-handbook.mjs until it passes, then completes the manual acceptance list in references/quality-gate.md;
5. reports the files, the inspected commit, and the short list of questions the project owner must answer.

The scripts are plain ESM and also run standalone:

node skills/project-handbook/scripts/project-inventory.mjs --root . --help
node skills/project-handbook/scripts/check-handbook.mjs .handover/PROJECT-HANDBOOK.md \
  --root . --facts .handover/inventory.json --profile standard --report .handover/check-report.md

Layout

dsh-project-handbook/
├── cordis.patch.yml                     # mounts the bundled skill provider
├── lib/index.js                         # package identity + skill-root resolver
└── skills/project-handbook/
    ├── SKILL.md                         # the workflow the agent follows
    ├── scripts/project-inventory.mjs    # repository reconnaissance → JSON + Markdown
    ├── scripts/check-handbook.mjs       # documentation quality gate
    ├── references/                      # evidence rules, content standard, stack playbooks,
    │                                    # credential rules, quality gate
    └── assets/                          # fill-in document templates

Requirements

Node.js ^22.19.0 || >=24.0.0 (no runtime dependencies) and a DSH host that ships @deepseek-ai/dsh-skill-filesystem.

License

MIT