dsh-project-handbook

The most common outcome when you ask a model to write a project handover document is a polished text that cannot survive a follow-up question: which deployment flow is backed by code? Are the business rules real or guessed? The new hire has no way to tell what is verifiable and what needs a human to confirm. dsh-project-handbook splits the job into three phases a deterministic scan, an evidence-backed write, and a strict quality gate so that every claim in the output carries a path:line reference or a reproducible command, and anything the repository cannot answer is written as an explicit open question rather than plausible-sounding prose.

The core mechanism starts with project-inventory.mjs, a deterministic walk of the repository that reports languages, framework signals, CI jobs and their commands, deployment artifacts, environment variable names, migrations, entry points, test layout, git history and top authors, technical-debt markers, and committed credential-shaped files, then pre-computes a list of gaps that need human answers. During the writing phase, stack-aware recon playbooks for Java/Spring, Go, Python, Node/TypeScript, frontend, data and AI, and legacy-ops projects direct the agent to exactly which files to open and which facts to extract. Before delivery, check-handbook.mjs acts as a hard quality gate, blocking missing sections, stubs, unfilled placeholders, speculation wording, citation-free badges, paths that do not exist, links and anchors that do not resolve, package scripts no manifest defines, pasted secrets, and claims that contradict the inventory. The entire pipeline is read-only: no credentials are opened, no builds, migrations, deploys, or commits occur.

Best suited for tech leads performing a project handover, engineers going through onboarding, and any team that needs a traceable, acceptance-ready project document a new member can act on within their first week.