dsh-project-handbook

Readme

# dsh-project-handbook

Company-grade **project handover / onboarding handbook** generator for
[DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) — 项目交接与新人熟悉文档.

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

```text
.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):

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

From npm — once the package is published there:

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

From a local checkout:

```sh
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`:

```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:

```sh
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

```text
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