diff --git a/CHANGELOG.md b/CHANGELOG.md index 037c0b9..4b59c66 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,8 +7,71 @@ aims to follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html). ## [Unreleased] +### Added + +- **`coding-scaffold tour`** — read-only five-screen walkthrough explaining what the + tool does, the scaffold artifact families, the doctor/pilot/setup loop, the daily + session/eval/team workflow, and where to go next. Never writes files; safe right + after install. Closes [#91](https://github.com/JRS1986/CodingScaffold/issues/91). +- **`--persona` flag on `doctor` and `pilot`** — choose from `beginner` (default), + `control`, `security`, `team-lead`. Each persona reorders the artifact survey and + swaps the recommended-commands list for a focused recipe matching the persona's job. + Persona registry lives at `src/coding_scaffold/personas.py` and is kept in sync + with the [Team-Rollout](docs/docs/wiki/Team-Rollout.md#persona-paths) wiki page. + Closes [#90](https://github.com/JRS1986/CodingScaffold/issues/90). +- **Stability markers in `--help`.** Every top-level command now renders a + `[stable]` / `[preview]` / `[experimental]` marker so teams know what they can + build on. Contract per marker documented in + [Stability](docs/docs/wiki/Stability.md). Registry at + `src/coding_scaffold/cli_stability.py`. Closes + [#95](https://github.com/JRS1986/CodingScaffold/issues/95). +- **Per-subcommand `--help` descriptions and examples.** Every subcommand + (`setup run`, `knowledge lint`, `team push`, ...) now prints a one-paragraph + description, when-to-run guidance, and 1-3 worked examples instead of bare + argparse output. Registry at `src/coding_scaffold/cli_help.py`. Closes + [#89](https://github.com/JRS1986/CodingScaffold/issues/89). +- **Doctor rationale lines.** Every artifact `doctor` surveys is rendered with a + one-line `→ why this matters` rationale, sourced from the shared + `src/coding_scaffold/artifacts.py` registry so `doctor`, `pilot`, and any future + onboarding command stay in sync. Closes + [#87](https://github.com/JRS1986/CodingScaffold/issues/87). +- **`setup update --force` + `min_supported_scaffold_version` field.** + `.coding-scaffold/scaffold-version.json` now records the minimum scaffold + version required to safely update the project. `setup update` refuses to run + when the installed scaffold is older (use `--force` to override after reading + the migration note). Closes + [#96](https://github.com/JRS1986/CodingScaffold/issues/96). +- **`setup update` prints a copy-pasteable `.new` reconciliation recipe.** When + staged `.new` sidecars are produced, the command now prints the `diff -u` / + merge / delete / `eval` steps inline, plus a link to the upgrade guide. + +### Fixed + +- **Template renderer no longer leaks `${undefined}` into user files.** Missing + keys raise `UnresolvedTemplateError` naming the template + key; any + `${...}` token surviving substitution raises before the file is written. + `$$` is preserved as the documented escape for a literal `$`. A parametrized + test renders every template under `templates/{writers,adapters}/` with a + default context. Fixes [#94](https://github.com/JRS1986/CodingScaffold/issues/94). + +### Changed + +- **Unified error message style.** New `src/coding_scaffold/errors.py` exposes + `fail_with(cause, next_step, link=None)` so CLI failure paths share a + three-line shape (`error: ... / next: ... / see: ...`). Documented in + [Errors and Recovery](docs/docs/wiki/Errors-and-Recovery.md). Closes + [#92](https://github.com/JRS1986/CodingScaffold/issues/92). + ### Documentation +- **New wiki pages**: [Glossary](docs/docs/wiki/Glossary.md) (cold-readable + vocabulary; linked from `doctor` and `--help` footers — closes + [#88](https://github.com/JRS1986/CodingScaffold/issues/88)); + [Stability](docs/docs/wiki/Stability.md); + [Upgrading](docs/docs/wiki/Upgrading.md) (the full upgrade contract: + `.new` recipe, rollback, version pinning, reading CHANGELOG Breaking notes); + [Errors and Recovery](docs/docs/wiki/Errors-and-Recovery.md). Wiki index + + README updated to route to the new pages. - **Install docs now default to an isolated global CLI.** README, Getting Started, and generated project onboarding recommend `uv tool install` or `pipx install` from the GitHub repo so users can run `coding-scaffold` from any project without activating the source checkout's virtual @@ -18,6 +81,17 @@ aims to follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html). workflows before the quick-start commands. Knowledge docs clarify that durable wiki pages should be distilled and reviewed, not raw chat transcript dumps. +### Tests + +- **Test coverage gap filled** for `file_ops`, `scaffold_version`, `doctor`, + `pilot`, `session` (full init → start → checkpoint → diff → rollback + round-trip), and `pr_template`. Test count grew from 351 to 590. Closes + [#93](https://github.com/JRS1986/CodingScaffold/issues/93). +- **Acceptance-criteria audit** for the team / knowledge / HTML-backend issues + (#97 – #105) — one test per acceptance bullet, with failure messages naming + the issue so regressions surface the affected ticket. The deeper mechanics + coverage stays in `tests/test_team.py` and `tests/test_knowledge.py`. + ## [0.5.1] — 2026-05-19 ### Fixed diff --git a/README.md b/README.md index 2704b44..499ec22 100644 --- a/README.md +++ b/README.md @@ -66,8 +66,13 @@ Everything else (`policy`, `mcp`, `skills`, `memory`, `team`, routing, and workf is useful later, but it should not be day-one cognitive load. > Looking for a specific entry point? See the [persona paths](docs/docs/wiki/Team-Rollout.md#persona-paths) -> (beginner / control-and-reproducibility / security review / team lead). For the threat model +> (beginner / control-and-reproducibility / security review / team lead), surfaced directly via +> `coding-scaffold doctor --persona ` / `pilot --persona `. For the threat model > and what the scaffold deliberately does not enforce, read [Security](docs/docs/wiki/Security.md#threat-model). +> Cold-start? Run `coding-scaffold tour` for a five-screen walkthrough, or skim the +> [Glossary](docs/docs/wiki/Glossary.md). Hit a CLI error? See +> [Errors and Recovery](docs/docs/wiki/Errors-and-Recovery.md). Wondering what's safe to depend on? +> See [Stability](docs/docs/wiki/Stability.md). Upgrading? See [Upgrading](docs/docs/wiki/Upgrading.md). > Release notes are in [CHANGELOG.md](CHANGELOG.md). CodingScaffold prepares an existing project for AI-assisted development without tying the team to diff --git a/docs/docs/wiki/FAQ.md b/docs/docs/wiki/FAQ.md index 7e2327c..51fee60 100644 --- a/docs/docs/wiki/FAQ.md +++ b/docs/docs/wiki/FAQ.md @@ -18,6 +18,39 @@ Run `coding-scaffold doctor --target .`. It surveys the repo and recommends the If you want the smallest useful demo, run `coding-scaffold pilot --target . --tool opencode` next and follow the printed recipe. +If the CLI vocabulary is unfamiliar, run `coding-scaffold tour` first — a read-only five-screen +walkthrough of what the tool does, the artifact families, and where to go next. Definitions for +every term live in the [Glossary](./Glossary.md). + +## Can I get a focused recipe for my job (security, team lead, …)? + +Yes. Pass `--persona {beginner,control,security,team-lead}` to `doctor` or `pilot`. A security +reviewer running `doctor --persona security` sees policy / MCP / permissions surfaced first +instead of the full firehose; a team lead gets a manifest / knowledge / skills recipe. The four +persona paths are documented in [Team Rollout](./Team-Rollout.md#persona-paths). + +## A command failed and I don't know what to do — where do I look? + +Every CLI failure path prints a three-line block: `error: ` / `next: ` / `see: `. Read the `next:` line first. If you want to +understand the recurring failure modes (missing tool, untouched .env, eval on empty repo, +manifest version mismatch), the [Errors and Recovery](./Errors-and-Recovery.md) page +enumerates them. + +## How do I know what I can build automation on? + +Every top-level command in `coding-scaffold --help` carries a `[stable]` / `[preview]` / +`[experimental]` marker. The [Stability](./Stability.md) page defines the deprecation and +breaking-change contract for each marker — depend on `[stable]` freely; pin a version +when depending on `[preview]`; treat `[experimental]` as exploratory only. + +## How do I upgrade a project after a new release? + +`coding-scaffold setup update --target .` refreshes generated files without losing your edits. +Unchanged files are rewritten in place; edited files get a `.new` sidecar so you can merge. +The full upgrade contract — `.new` reconciliation recipe, rollback, version pinning, how to +read the CHANGELOG's Breaking section — is in [Upgrading](./Upgrading.md). + ## Does setup install tools? Yes, when it is running interactively and the selected coding environment is missing. It asks before diff --git a/docs/docs/wiki/Getting-Started.md b/docs/docs/wiki/Getting-Started.md index 4815bdd..b9edc01 100644 --- a/docs/docs/wiki/Getting-Started.md +++ b/docs/docs/wiki/Getting-Started.md @@ -8,17 +8,31 @@ backend immediately; the goal is to make one small, inspected, verified change. After installing CodingScaffold in your environment, your first three commands are: ```bash +coding-scaffold tour # optional five-screen orientation coding-scaffold doctor --target . coding-scaffold pilot --target . --tool opencode # follow the printed steps ``` +`tour` is a read-only five-screen walkthrough (artifacts → doctor loop → daily workflow → +where to go next). It's stateless — never writes files — so it's safe to run on a fresh +checkout. Skip it if you already know the model. + That's it for day one. Everything else on this page is reference material you can come back to when you actually need it. The other commands (`policy`, `mcp`, `skills`, `memory`, `team`, `permissions`, `tools route`) are deliberately out of the first-run mental model — `doctor` lists them under "Ignore for now (advanced)" so you don't have to track them yourself. +### Persona-targeted output + +`doctor` and `pilot` accept `--persona {beginner,control,security,team-lead}` to scope the +recommendations and ignore-for-now list to a specific job. A security reviewer running +`coding-scaffold doctor --persona security --target .` sees policy / MCP / permissions +surfaced first instead of the full firehose. The four personas are documented in +[Team Rollout](./Team-Rollout.md#persona-paths); the registry lives at +`src/coding_scaffold/personas.py` so the CLI and wiki stay in sync. + ### What `doctor` does Surveys the scaffold artifacts already present in your project (AGENTS.md, PR template, diff --git a/docs/docs/wiki/Glossary.md b/docs/docs/wiki/Glossary.md index ed7aeab..8c9eeff 100644 --- a/docs/docs/wiki/Glossary.md +++ b/docs/docs/wiki/Glossary.md @@ -114,6 +114,7 @@ See [artifact](#artifact). A SHA256 snapshot of every generated file written by setup, stored in `.coding-scaffold/scaffold-version.json`. `setup update` uses it to tell unchanged files (safe to rewrite) from user-edited files (write a `.new` sidecar instead). +See [Upgrading](./Upgrading.md). ## session trace diff --git a/docs/docs/wiki/Upgrading.md b/docs/docs/wiki/Upgrading.md index e9a94f2..7521d5d 100644 --- a/docs/docs/wiki/Upgrading.md +++ b/docs/docs/wiki/Upgrading.md @@ -137,8 +137,7 @@ The CHANGELOG groups changes by release. Look for these sections: - **Deprecated** — features that still work but are scheduled for removal. Plan to migrate before the next major bump. - **Stability** — commands moved between `stable`/`preview`/`experimental` - markers. The Stability wiki page (shipped alongside this one) defines what - each marker promises. + markers. See [Stability](./Stability.md) for what each marker promises. A worked example: if 0.6.0's CHANGELOG says "Renamed `policy.network.allow` to `policy.network.allowlist`", and your update produced diff --git a/docs/docs/wiki/index.md b/docs/docs/wiki/index.md index 59c812f..cf4e7f1 100644 --- a/docs/docs/wiki/index.md +++ b/docs/docs/wiki/index.md @@ -42,11 +42,15 @@ Start with the smallest path that matches your job today: | Need | Page | What you get | | --- | --- | --- | +| Define a term you saw in `--help` | [Glossary](./Glossary.md) | One paragraph per term (artifact, persona, MCP, manifest, scope, ...). | | First useful session | [Getting Started](./Getting-Started.md) | The `doctor` + `pilot` path and the first bounded agentic change. | -| Small-team pilot | [Team Rollout](./Team-Rollout.md) | A two-person rollout plan for teams under 20 people. | +| Small-team pilot | [Team Rollout](./Team-Rollout.md) | A two-person rollout plan + the four persona paths surfaced by `--persona`. | | Security/compliance review | [Security](./Security.md) | Credential, provider, MCP, policy, and trust-boundary notes. | | Tool comparison | [Tool Adapters](./Tool-Adapters.md) | Capability matrix for OpenCode, Claude Code, Codex, OpenClaude, Hermes, and Pi. | | Shared memory | [Knowledge Base](./Knowledge-Base.md) | Markdown, HTML, Obsidian, Foam, MemPalace, and shared Git workflows. | +| Upgrade a project | [Upgrading](./Upgrading.md) | What `setup update` does, the `.new` recipe, rollback, version pinning. | +| Decide what to depend on | [Stability](./Stability.md) | What `[stable]` / `[preview]` / `[experimental]` markers in `--help` promise. | +| Recover from a CLI failure | [Errors and Recovery](./Errors-and-Recovery.md) | The three-line error format and the recurring failure modes. | Then use the reference pages when the need appears: