CLI UX: doctor rationale, Glossary, stability markers (#87, #88, #95)#117
Merged
Conversation
Closes #87, #88, #95. - New `artifacts.py` registry: one place that names every scaffold artifact doctor/pilot recommend, with a <100-char rationale answering "what does this unlock?". Doctor's survey now reads from the registry and renders the rationale inline next to each artifact line. - New `docs/docs/wiki/Glossary.md` covering the terms users see in --help and doctor output (artifact, persona, MCP, skill, manifest, scope, maturity, ...). Linked from the wiki index, the top-level --help footer, and the doctor output footer so new users don't need to leave the CLI to interpret it. - New `cli_stability.py` registry tagging every top-level command as stable/preview/experimental. Markers render in --help next to each command name. Wiki `Stability.md` defines the contract per level. - Tests assert: every doctor artifact has a rationale, the Glossary covers the required terms, every visible --help command carries a registry entry, every marker is one of the three known levels.
4 tasks
JRS1986
added a commit
that referenced
this pull request
May 25, 2026
Closes #90, closes #91. - New `personas.py` registry: four personas (beginner, control, security, team-lead) with focus area, prioritized artifact keys, and tailored next commands. Both `doctor --persona <name>` and `pilot --persona <name>` read from the same registry so the CLI cannot drift from the Team-Rollout wiki. - `doctor --persona security` reorders the artifact survey so policy / MCP / permissions appear first, switches the recommendation list to a focused policy/MCP recipe, and tightens the ignore-for-now to advanced surfaces that genuinely don't matter for a security review. - New `coding-scaffold tour` command: five-screen, stateless walkthrough (what the tool does -> artifact families -> doctor/pilot/setup loop -> daily session/eval/team workflow -> where to go next). No files written, no commands executed. Mentioned in the README "30-Second Start" as step 0. - Persona import-time validation: a typo in `Persona.artifact_keys` fails the module load instead of producing a silent KeyError at runtime. Stacked on top of #117 (the artifact registry is the persona registry's input).
This was referenced May 25, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
doctor(and any future onboarding command) can show why each scaffold artifact matters in <100 chars per entry. (doctor: explain WHY each recommendation matters, not just WHAT #87)docs/docs/wiki/Glossary.mdcovering every term that appears in--helpanddoctor/pilotoutput, linked from the wiki index, the top-level--helpfooter, and thedoctorfooter. (Add a Glossary and link it from CLI --help #88)stable | preview | experimental) rendered next to every top-level command in--help, plus aStability.mdwiki page defining the contract per marker. (Mark CLI commands with stability metadata (stable/preview/experimental) in --help #95)Closes #87, closes #88, closes #95.
Test plan
uv run pytest -q— 394 tests pass (was 351); newtests/test_artifacts_and_stability.pycovers registries, doctor output rendering, glossary contents, and stability marker invariants.python -m coding_scaffold --help— markers render, footer links to Glossary + Stability.python -m coding_scaffold doctor— every artifact line carries-> <why>.