From 6d62f86ddf280ea15e25543320971b3b10494d4c Mon Sep 17 00:00:00 2001 From: JRS1986 <1651269+JRS1986@users.noreply.github.com> Date: Wed, 20 May 2026 20:20:50 +0200 Subject: [PATCH] Clarify CodingScaffold value proposition --- CHANGELOG.md | 4 ++++ README.md | 27 +++++++++++++++++++++++++++ docs/docs/index.md | 4 ++++ docs/docs/wiki/FAQ.md | 14 ++++++++++++++ docs/docs/wiki/Knowledge-Base.md | 6 ++++++ tests/test_docs_positioning.py | 29 +++++++++++++++++++++++++++++ 6 files changed, 84 insertions(+) create mode 100644 tests/test_docs_positioning.py diff --git a/CHANGELOG.md b/CHANGELOG.md index e17ada7..037c0b9 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -13,6 +13,10 @@ aims to follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html). 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 environment. The clone + editable install path remains documented for contributors. +- **README now answers why CodingScaffold exists alongside one-command agent installers.** The intro + now highlights adaptive language/tool setup, shared reviewed knowledge, and repeatable team + workflows before the quick-start commands. Knowledge docs clarify that durable wiki pages should + be distilled and reviewed, not raw chat transcript dumps. ## [0.5.1] — 2026-05-19 diff --git a/README.md b/README.md index e26d394..d765aca 100644 --- a/README.md +++ b/README.md @@ -6,6 +6,27 @@ Local-first onboarding, configuration, and governance scaffolding for AI-assisted software development teams. +## Why Use This If Agents Already Install In One Command? + +A coding-agent installer gives you a binary. CodingScaffold prepares the repo around that binary so +the agent starts with the right project rules, context, model guidance, review flow, and team memory. + +The practical difference shows up after the first setup: + +- **Adaptive project setup:** `setup run` uses the programming language, project shape, privacy + preference, hardware/provider signals, and selected coding tool to generate different local files. + OpenCode gets native commands and agents; Claude Code and Codex get their own native project + guidance; other tools get focused adapter docs. +- **A shared knowledge base:** session traces, decisions, useful prompts, project vocabulary, and + repeated agent patterns can be captured as Markdown, reviewed in Git, and promoted into a team + wiki instead of staying buried in one person's chat history. +- **A repeatable team workflow:** the scaffold gives `doctor`, `pilot`, `session`, `eval`, + permissions, policy, skills, and onboarding manifests the same shape across projects, without + making the scaffold a runtime agent or sending prompts to a model. + +Use your preferred coding agent. Use CodingScaffold when you want that agent to behave consistently +inside a real repo and when the useful lessons from each session should become reusable team context. + ## 30-Second Start You need three commands today. The rest can wait. @@ -493,6 +514,12 @@ the single source of truth; this table is a scannable summary. The knowledge base is Markdown-first so it works in GitHub, GitLab, local editors, OpenCode, Obsidian, and optional memory tools. +It is deliberately not "dump every chat into the wiki." Session traces and raw notes are source +material. The durable team wiki should contain compressed, abstracted, reviewed knowledge: decisions, +project vocabulary, useful prompts, validated workflows, and links back to source notes when needed. +If automatic chat ingestion is added later, it should create reviewable distilled proposals rather +than saving raw transcripts as team truth. + Plain Markdown: ```bash diff --git a/docs/docs/index.md b/docs/docs/index.md index 2e2c72d..e2fd296 100644 --- a/docs/docs/index.md +++ b/docs/docs/index.md @@ -20,6 +20,10 @@ CodingScaffold helps a project use existing coding agents without turning day on migration. It writes reviewable project-local files for agent instructions, provider hints, knowledge, policies, and workflows. +Agent installers give you a command to run. CodingScaffold gives that command repo-specific +context: language-aware setup, tool-specific adapter files, model/provider guidance, verification +habits, and a Markdown knowledge base where session findings can become reviewed team wiki pages. + For a new repo or a small team pilot, use only this: ```bash diff --git a/docs/docs/wiki/FAQ.md b/docs/docs/wiki/FAQ.md index 85c9de1..d3bd77b 100644 --- a/docs/docs/wiki/FAQ.md +++ b/docs/docs/wiki/FAQ.md @@ -60,6 +60,20 @@ print, or collect secret values. Copilot is useful for completion and chat. CodingScaffold focuses on agentic workflows: inspect, plan, edit, verify, review, and preserve reusable team habits. +## Why not just install a coding agent directly? + +You should install and use the coding agent your team likes. CodingScaffold is the repo layer around +that agent: it generates language-aware and tool-specific guidance, points the agent at the right +local context, names verification habits, and gives the team a shared knowledge structure. The agent +does the coding work; CodingScaffold helps the project remember how that work should happen. + +## Does it automatically turn chats into wiki pages? + +No. Today it provides session traces, raw note folders, curated wiki pages, and +`knowledge distill --review` proposals. Durable team knowledge should be compressed, abstracted, +reviewed Markdown, not raw chat logs. If automatic ingestion is added later, it should summarize, +redact, deduplicate, and propose updates for review before they become team wiki pages. + ## Why Markdown for knowledge? Markdown works in Git, GitHub, GitLab, editors, Obsidian, and memory tools. It is easy to review diff --git a/docs/docs/wiki/Knowledge-Base.md b/docs/docs/wiki/Knowledge-Base.md index 8815cc4..80485bc 100644 --- a/docs/docs/wiki/Knowledge-Base.md +++ b/docs/docs/wiki/Knowledge-Base.md @@ -136,6 +136,12 @@ coding-scaffold knowledge distill --target ~/dev/my-project --source raw --revie The first version is deterministic and review-first. It writes `.new` proposal files under `knowledge/wiki/` and never silently rewrites curated pages. +Do not treat raw agent chats as durable team knowledge. If your workflow captures conversation +output, distill it first: remove secrets and irrelevant history, compress repeated context, abstract +the reusable decision or pattern, and review the proposal before promoting it into `wiki/`. +Automatic chat ingestion, if added later, should follow that same proposal-first shape instead of +writing raw transcripts into the shared wiki. + ## Obsidian Obsidian mode keeps Markdown as the source of truth while adding vault structure, backlinks, diff --git a/tests/test_docs_positioning.py b/tests/test_docs_positioning.py new file mode 100644 index 0000000..2ee9a54 --- /dev/null +++ b/tests/test_docs_positioning.py @@ -0,0 +1,29 @@ +from pathlib import Path + + +ROOT = Path(__file__).resolve().parents[1] + + +def test_readme_answers_why_use_scaffold_before_quick_start() -> None: + text = (ROOT / "README.md").read_text(encoding="utf-8") + + why_index = text.index("## Why Use This If Agents Already Install In One Command?") + start_index = text.index("## 30-Second Start") + assert why_index < start_index + assert "Adaptive project setup" in text + assert "A shared knowledge base" in text + assert "A repeatable team workflow" in text + + +def test_docs_do_not_claim_raw_chat_ingestion_as_team_wiki() -> None: + readme = (ROOT / "README.md").read_text(encoding="utf-8") + faq = (ROOT / "docs" / "docs" / "wiki" / "FAQ.md").read_text(encoding="utf-8") + knowledge = (ROOT / "docs" / "docs" / "wiki" / "Knowledge-Base.md").read_text( + encoding="utf-8" + ) + + combined = "\n".join([readme, faq, knowledge]) + assert "not raw chat" in combined + assert "reviewable distilled proposals" in combined + for verb in ("summarize", "redact", "deduplicate"): + assert verb in combined