project-docs

name

project-docs

description

Author the orientation document set that gets a newcomer (human or agent) productive — README.md, GLOSSARY.md, DEVELOPMENT_SCENARIO_GUIDE.md, and ONBOARDING_GUIDE.md — by reading the codebase and existing project docs, then writing what is actually true. Produces any subset the user asks for; cross-links the other docs (CODING_STANDARD, TASK_BREAKDOWN, DEPLOYMENT_PLAN, etc.) instead of duplicating them. Use when the user wants a README, glossary, onboarding guide, development/getting-started guide, or "the orientation docs" for a repo.

Project Docs

Author the orientation set that takes someone from "just cloned this" to "shipping a change":

Doc	Answers	Audience
README.md	What is this, why, how do I run it?	Anyone landing on the repo
GLOSSARY.md	What does this word mean here?	Anyone reading code or specs
DEVELOPMENT_SCENARIO_GUIDE.md	How do I actually do a task end-to-end?	A developer picking up work
ONBOARDING_GUIDE.md	How do I get set up and find my way around?	A brand-new contributor

Produce whichever the user asks for; default to all four. They share one source (the codebase + existing docs) and one rule: describe reality, then cross-link — never duplicate. Where a fact already lives in another doc (standards, task breakdown, deployment plan, ADRs), link to it rather than restating it; restated facts drift and rot.

1. Read first

Before writing, build an accurate picture:

• Run/build truth: README, CONTRIBUTING.md, CLAUDE.md/AGENTS.md, manifests, lockfiles, scripts, .env.example, compose/Dockerfile, CI workflows. Get the real setup and verification commands — don't guess them.
• Structure truth: the directory layout, module/layer boundaries, entry points, where each responsibility lives.
• Domain truth: specs, user stories, ADRs, and the code itself — for the glossary, harvest the actual terms used in identifiers, UI copy, and docs (including non-English UI labels, preserved verbatim).
• Workflow truth: branch/PR flow, review process, sprint/task model — read TASK_BREAKDOWN.md, CODING_STANDARD.md, DEPLOYMENT_PLAN.md if present.

Ask the user only for what the repo can't tell you: project purpose/business context, target audience, where to get help (channels, owners), and anything intentionally undocumented. Batch these questions.

2. Write each requested doc

Every command must be copy-paste-runnable for this repo (real script names, paths, ports). Open each doc with a one-line project identifier and a short Table of Contents if it's long. Follow the writing conventions below.

README.md

The front door, kept lean. What the project is and the problem it solves; key tech/stack; a quickstart (prerequisites → install → run → test) that actually works; a high-level repo-structure map; and links out to the deeper docs (onboarding, glossary, standards, deployment) rather than inlining them. Badges/license/contributing pointer if the project uses them.

GLOSSARY.md

A pure glossary — definitions only, no implementation detail. Group terms by domain area (e.g. domain entities, lifecycle/status, actions/buttons, roles). Each entry: the canonical term, its UI label if different (quote non-English labels verbatim), and a one-to-two-sentence definition. Disambiguate overloaded words ("account = Customer, not User"). Pull terms from real usage; don't invent vocabulary the project doesn't use.

DEVELOPMENT_SCENARIO_GUIDE.md

Concrete, role-based walkthroughs of the recurring jobs, start to finish. Typically: Day 1 setup; the work-split / sprint model; picking up and completing a task of each kind (e.g. backend card, frontend card) test-first through to commit; reviewing a PR; promoting/releasing. Each scenario is an ordered, runnable sequence of steps with the exact commands, referencing the relevant skills/docs at each step (e.g. "run the verification gate per CODING_STANDARD.md", "review per the checklist"). This is the "how we work here" doc.

ONBOARDING_GUIDE.md

The newcomer's path, in order: project context (what/why, domain in a paragraph); prerequisites (tools + versions); local setup (automated path and manual fallback, both verified); a codebase walkthrough (the map plus what to read first); the development workflow in brief (linking the scenario guide for depth); key concepts to internalize (linking the glossary); and where to get help. Should get a new contributor to a green local build and first change.

3. Confirm and write

• For a fresh set, show the proposed outline (sections per doc) before writing, unless told to just generate.
• Write to where the project keeps docs (docs/ or repo root for README). If a doc exists, read and update it in place — preserve still-true content, refresh what drifted, report what changed. Never clobber.
• Keep the set internally consistent: the README's links, the onboarding's pointers, and the scenario guide's references should all resolve to the docs that actually exist.

Notes

• These complement the rest of the doc pipeline (/coding-standard, /task-breakdown, /deployment-plan, /troubleshooting); generate or update those first where it makes the cross-links real.
• If the user wants a shareable onboarding link for teammates, the ShareOnboardingGuide tool uploads an ONBOARDING.md and returns a link.

Helper script

For the repo-structure map in the README and the codebase walkthrough in the onboarding guide, generate the tree rather than transcribing it by hand:

python scripts/repo_tree.py . --max-depth 3

It prints a fenced tree skipping VCS, dependencies, build output, and caches. Add the per-folder purpose annotations yourself; the script only guarantees the structure is accurate.

Writing conventions (enforced in all output)

• No AI slop: no filler or hedging; every sentence informs. Use the stop-slop skill on prose when unsure.
• No em-dashes, no double-dashes (--) in prose; dashes only as Markdown syntax (list bullets, table rules) or in literal code/CLI flags (e.g. --no-deps).
• No emoji. Professional, declarative tone.
• If a document carries a metadata header (**Version:**, **Date:**, **Author:**, **Status:**, **Phase:**), each such line ends with two trailing spaces so Markdown renders them on separate lines.