docs: document the brownfield integration path - #166
Conversation
Brownfield behavior was shipped quietly across prior PRs but lived only in the command prompts and CLAUDE.md — absent from every user-facing doc. Give it equal footing with the greenfield path. - docs/brownfield-adoption.md: new end-to-end guide (audit → product → roadmap → architecture), artifact lifecycle, opt-in/out, and a greenfield-vs-brownfield comparison. - README + product/roadmap/architecture command docs: brownfield sections and cross-links. - plugin README: position /awos:ai-readiness-audit as the recommended first step of brownfield adoption, noting its scoring is self-contained and does not depend on /awos:hire's agents. Co-Authored-By: Claude Opus 4.8 <[email protected]>
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Plus Run ID: 📒 Files selected for processing (7)
🚧 Files skipped from review as they are similar to previous changes (5)
📝 WalkthroughWalkthroughAWOS documentation now defines an audit-first brownfield adoption path, existing-code exploration and triage, capability and technology-stack discovery, temporary artifact cleanup, opt-out controls, and transition to the standard feature workflow. ChangesBrownfield adoption flow
Estimated code review effort: 2 (Simple) | ~10 minutes Possibly related PRs
Suggested reviewers: 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
|
@coderabbitai review |
✅ Action performedReview finished.
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 5
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/brownfield-adoption.md`:
- Line 88: Remove “credentials” from the retained configuration examples in
docs/brownfield-adoption.md at lines 88-88 and docs/commands/architecture.md at
lines 27-27; both documents should specify retaining only non-secret metadata,
with credentials supplied through environment variables or a secret manager
instead of stored under context/.
- Around line 24-27: Update the fenced command block containing /plugin install
and /awos:ai-readiness-audit to use the sh language tag, changing the unlabeled
fence to ```sh while preserving the commands.
- Around line 77-79: Update the brownfield capability guidance to classify only
fully implemented capabilities as done, while preserving partially
built/scaffolded and planned TODO/FIXME findings as incomplete follow-up work.
Apply the same completion-status distinction when building roadmap phases in
docs/brownfield-adoption.md lines 77-79 and docs/commands/roadmap.md line 29.
- Line 35: Revise the audit explanation in the adoption guidance to remove the
claim that scores remain the same regardless of repository state. Clarify that
the scoring engine is self-contained and does not depend on specialist agents
installed by /awos:hire, while acknowledging that repository changes from
adoption can alter the resulting score and dimensions.
In `@README.md`:
- Line 24: The README statement around the brownfield-project introduction
overstates automatic detection across all foundation commands. Clarify that
/awos:product performs source detection and creates
context/product/brownfield.md, while /awos:roadmap and /awos:architecture
consume that staging artifact rather than independently detecting the codebase.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro Plus
Run ID: 61a2c909-fe86-4955-86fb-445e832b6b11
📒 Files selected for processing (6)
README.mddocs/brownfield-adoption.mddocs/commands/architecture.mddocs/commands/product.mddocs/commands/roadmap.mdplugins/awos/README.md
PR #166 review: - Audit baseline: clarify the audit *methodology* is self-contained (engine, not /awos:hire's agents) — the score still reflects repo state and rises with adoption. Removes the self-contradictory "scores the same" phrasing. - Capabilities: only fully-implemented capabilities are treated as done; partial/scaffolded and planned (TODO/FIXME) work stays visible as upcoming roadmap items (brownfield-adoption.md + docs/commands/roadmap.md). - Secrets: retain only non-secret source metadata under context/; credentials belong in env vars / a secret manager, never under context/ (brownfield-adoption.md + docs/commands/architecture.md). - README: only /awos:product auto-detects; later commands build on its staged brownfield.md — narrow the auto-detection claim accordingly. - Tag the audit command fence as text (MD040) — the new file's only fences. Co-Authored-By: Claude Opus 4.8 <[email protected]>
|
Addressed all 5 findings in
Lint 146 / 0, Prettier clean. |
AlexanderMakarov
left a comment
AlexanderMakarov
left a comment
There was a problem hiding this comment.
Fills a real gap — the brownfield path has been shippable for a while with nothing user-facing describing it, and the artifact-lifecycle table at :94-98 is the part I'd keep exactly as written; every cell in it checks out.
Accuracy is what I'd want resolved before merge, since describing the prompts is this doc's whole job. Six load-bearing claims don't match the prompts — all inline, all a sentence each, none needing code. Two of them (:79 and :88) came out of fixing CodeRabbit's points and landed past what the framework actually does, so those want a deliberate decision rather than another reword.
Three things that aren't tied to a line:
The docs/commands/*.md sections duplicate the guide, and one has already drifted inside this PR. docs/commands/roadmap.md:29 repeats the guide's incorrect roadmap claim, so one prompt fact now has two files to fix; docs/commands/architecture.md:27 restates all of guide :83-88 in a single 120-word line, carrying two of the defects with it. I'd make those three sections pointer-shaped — a couple of sentences of orientation plus the guide link — and let the guide be the one place the behavior is described.
You're right about not shipping tests here, and it's worth saying so since it's the kind of thing that gets asked reflexively. tests/lint-prompts.test.js reads nothing under docs/, so there's no docs→prompt contract today — but it does already pin the prompt side of nearly everything this guide quotes, and CLAUDE.md's same-PR-test rule enumerates framework structural contracts, not prose pages. Decisive bit: a lint asserting each quoted string appears in the prompt would have caught none of the findings above, because they're all semantic — a doc asserting a rule the prompt doesn't contain, or crediting work to the wrong actor. Cutting the duplication above beats testing it.
Discoverability. README.md:60 and :72 give docs/rationale.md and docs/testing-strategies.md a dedicated top-level ## section each, and there's no docs/ index, so those sections are the index. This guide is now the second-longest thing in docs/ and is reachable only from inside the Step 1 blockquote. A three-line ## Brownfield Adoption section next to ## Testing Strategies would match how the others are surfaced — keeping the Step 1 link as the in-flow pointer.
|
|
||
| When `context/product/brownfield.md` is present, `/awos:roadmap` runs a focused `Explore` pass to inventory **existing capabilities** — features that are fully implemented (routes, UI, tests), partially built or scaffolded, and planned (TODOs, FIXMEs). It appends these under a `## Capabilities` heading in `brownfield.md`. | ||
|
|
||
| The roadmap is then anchored in reality: only **fully-implemented** capabilities are treated as done, while **partially-built or scaffolded** work and **planned** items (TODOs, FIXMEs) stay visible as upcoming roadmap items rather than being marked complete. New phases describe what comes next instead of re-planning work the codebase has already finished. As with product, the capability findings are triaged with you before the roadmap is finalized. |
There was a problem hiding this comment.
This distinction isn't in the prompt. commands/roadmap.md:84 is the only line that says what the roadmap does with the findings, and it folds all of them into done:
Use the full set of capabilities (from brownfield.md) to anchor the roadmap: existing capabilities are noted as already done, and new phases focus on what comes next.
The three-way split does exist, but only in the Explore agent's reporting instructions at commands/roadmap.md:68-70 — nothing downstream acts on the difference. Your own side-by-side table at :113 ("Existing capabilities marked done") describes the actual behavior, so the doc disagrees with itself here too. Same sentence is in docs/commands/roadmap.md:29.
This came from CodeRabbit's capability-status finding, which asked the docs to assert the distinction — so the fix ended up documenting something the framework doesn't do. Given that, I'd rather see it go the other way: add the rule to commands/roadmap.md:84 (one line — "only capabilities reported as fully implemented are noted as done; partial/scaffolded and TODO/FIXME items become upcoming roadmap items") and keep the prose you've already written. It's the better product behavior and it's a smaller edit than unpicking the claim from three places. If you'd rather keep this PR docs-only, the alternative is reverting :79/:113/roadmap.md:29 to match the prompt and filing the prompt change separately.
While you're in this sentence: "triaged with you before the roadmap is finalized" is backwards — commands/roadmap.md:82 puts triage in Step 3: Finalization "after the roadmap is saved — so exploration never blocks the write", and :129-130 writes, then triages, then re-saves. You describe that ordering correctly for product at :56; worth matching it.
There was a problem hiding this comment.
Good call — went the prompt route: roadmap.md now only marks fully-implemented capabilities as done. Also fixed the triage-timing sentence (saved first, triaged after).
| - **Force brownfield:** include intent in your prompt — `/awos:product explore the existing codebase`. | ||
| - **Force greenfield on a repo with code:** `/awos:product start from scratch, ignore existing code`. | ||
| - **Skip external sources:** answer **No** when asked, or decline; a `## Status: none` marker records the choice so you are not asked again. | ||
| - **Unattended runs** (`claude -p …`): every brownfield prompt has a safe default (explore, no external sources) and never blocks the deliverable, so foundation setup completes without a human present. |
There was a problem hiding this comment.
"never blocks the deliverable, so foundation setup completes without a human present" is the sentence someone will rely on to put /awos:product in CI, and the prompt documents two ways it doesn't hold.
commands/product.md:98 and :99 both end with If the skill triggers an editor restart, stop here. — that stop is inside Step 2B, and the write is Step 3 (commands/product.md:139), so on the restart path no product-definition.md gets written at all. And the prompt authors flagged the general case themselves, at commands/product.md:42:
In claude -p a dismissed AskUserQuestion ends the turn, so a deliverable Write placed after such a question never runs unattended. The fix is structural — keep the Write ahead of any dismissable question, then refine afterward.
Both Step 2B questions (:73, :99) sit ahead of the Step 3 write, so that note applies here. Worth knowing the platform side reinforces it: the headless docs note that under --permission-mode dontAsk — the locked-down mode for CI — "AskUserQuestion … [is] denied even when an allow rule matches", so in exactly the setup this bullet is written for, the question doesn't get a default, it gets refused.
The first half of your sentence is right — :73 does default to Yes-explore and :99 to No when unanswered. I'd keep that and replace the guarantee with what's actually true: an unanswered question falls back to its default and the run continues; a dismissed or denied one ends the turn; and external-source setup that adds an MCP server stops for a restart before the definition is written, so you re-run to finish.
There was a problem hiding this comment.
Reworded — an unanswered question falls back to its default and continues; a dismissed/denied one ends the turn; an MCP-add stops for a restart before the write. Added the CI caveat.
| - identifies each source and its category (documentation, tickets, communication), | ||
| - guides you through connecting the right tool — an MCP server, a CLI like `gh`, or manual paste, | ||
| - records the configuration in `context/sources/sources.md`, and | ||
| - once connected, retrieves product-relevant content (requirements, goals, audience, pain points) and folds it into the same triage flow as the code findings. |
There was a problem hiding this comment.
This bullet is under "the command invokes the skill … which:", but retrieval is the one thing the skill says it doesn't do — configure-external-sources/SKILL.md:13:
Your only output is the structured source manifest at context/sources/sources.md. You do not retrieve content from the sources — the calling command handles retrieval after you finish.
/awos:product does it itself, in its own substep — commands/product.md:101, one Explore agent per Access: mcp / Access: cli source, AskUserQuestion paste for Access: manual. Worth splitting: end the skill's bullets at "records the configuration in context/sources/sources.md", then a separate sentence for the retrieval that /awos:product runs afterwards. docs/commands/product.md:30 has the same misattribution.
There was a problem hiding this comment.
Split it — the skill only writes the config, product does the retrieval. Fixed the same misattribution in the command doc.
|
|
||
| ## Step 3 — `/awos:architecture`: adopt the existing stack, then clean up | ||
|
|
||
| With `brownfield.md` present, `/awos:architecture` runs an `Explore` pass to discover the **existing technology stack** — languages, frameworks and versions, databases and ORMs, infrastructure (Docker, cloud configs, deployment scripts), external services, and testing/build/CI tooling. It appends these under a `## Technology` heading, and uses them as the **defaults** for each architecture decision instead of proposing technologies from scratch. You still confirm or change every decision. |
There was a problem hiding this comment.
Two overstatements in this one sentence. "You still confirm or change every decision" — the file is written first, without waiting for you (commands/architecture.md:132: "Write the file without waiting for approval — an architecture is reversible…"), and the triage afterwards is scoped to the brownfield subset (:133: "If brownfield technology findings seeded any defaults, triage them with the user now"). And "uses them as the defaults for each architecture decision instead of proposing technologies from scratch" is only true where findings exist — commands/architecture.md:114: "When brownfield or documentation findings provided a known technology, use it as the default; otherwise pick a sensible best-practice default and label it as an assumption."
You already explain this write-then-refine shape well for /awos:product at :56 — reusing that framing here would fix both. Same claim in docs/commands/architecture.md:27.
There was a problem hiding this comment.
Fixed both — defaults only where a finding exists (else a best-practice default labeled an assumption), and reused the write-then-refine framing. Same in the architecture doc.
|
|
||
| Most AWOS documentation assumes a **greenfield** project — you start from a blank slate and describe what you want to build. But AWOS works just as well on a **brownfield** project: an existing codebase with real source, history, and often external documentation (wikis, tickets, chat). This guide is the brownfield counterpart to the [Quick Start](../README.md#quick-start) — same commands, same document-centric workflow, with the extra awareness AWOS brings to code that already exists. | ||
|
|
||
| You do not run a different set of commands for brownfield. The same foundation commands (`/awos:product`, `/awos:roadmap`, `/awos:architecture`) **auto-detect** your existing code and fold it into the context they build. This guide explains what that detection does, what it produces, and how to steer it. |
There was a problem hiding this comment.
Only /awos:product detects. The other two just check for the file: commands/roadmap.md:59 — "Check if context/product/brownfield.md exists (produced by /awos:product when it detects an existing codebase)" — and commands/architecture.md:57 is identical in shape. Neither scans for source indicators.
This is CodeRabbit's auto-detection finding, and you fixed it in README.md:24 — the phrasing there ("/awos:product auto-detects your code and stages what it finds, and the later foundation commands build on that") is exactly right and worth reusing here. Your table at :12-14 and the Step 2/3 headings already get it right, so :5 is the odd one out.
Related, and not stated anywhere yet: because detection is per-/awos:product, choosing No, start from scratch at Step 1 means no brownfield.md, so Steps 2 and 3 do zero brownfield work either. That's worth a line in "Opting in and opting out" — the opt-out is global, not per-step.
There was a problem hiding this comment.
Reused the README wording — only product detects. Added the global-opt-out note to the opt-in/out section too.
| The command chooses whether to explore existing code in this order: | ||
|
|
||
| 1. **Your prompt wins.** If you say something like "explore the existing codebase" or "brownfield", it explores. If you say "start from scratch", "greenfield", or "ignore existing code", it skips detection and treats the project as new. | ||
| 2. **Otherwise it looks.** If your prompt says nothing either way, the command scans for common source indicators — `src/`, `app/`, `lib/`, `package.json`, `requirements.txt`, `go.mod`, `Cargo.toml`, `pom.xml`, `Gemfile`, `build.gradle`, `*.csproj`, `pyproject.toml`, and similar. If none are found, it proceeds as greenfield. If any are found, it asks you to confirm: **Yes, explore the codebase** or **No, start from scratch** (defaulting to explore if the question goes unanswered). |
There was a problem hiding this comment.
The indicator list is missing Makefile, CMakeLists.txt and setup.py from the fifteen in commands/product.md:73. "and similar" keeps it from being wrong, but those three are exactly the cases where a C/C++ or older-Python reader would conclude their repo won't trip detection. Three words.
There was a problem hiding this comment.
Added Makefile, CMakeLists.txt and setup.py.
| - **A punch list.** `recommendations.md` surfaces the highest-leverage gaps (missing `CLAUDE.md`, thin tests, no agent configs) that make the rest of the AWOS flow more effective. | ||
| - **A shared vocabulary.** The scores give the team a concrete, agreed-upon picture of the starting point. | ||
|
|
||
| **The audit is a fixed measuring stick, so run it first without hesitation.** Its _methodology_ is self-contained — the score is computed by an engine, not by the specialist agents `/awos:hire` later installs — so it measures the repository the same way before and after adoption. The _score itself_ reflects the state of the repo and is expected to change as you improve it: a first run on an untouched brownfield repo will score the AI-tooling and spec-driven-development dimensions low, and that low score _is_ the honest baseline. Adopt AWOS (foundation, `/awos:hire`, specs), re-run the same audit, and those dimensions climb — the measuring stick didn't move, the codebase did. The audit is read-only and each run is an independent snapshot, so re-running costs nothing. |
There was a problem hiding this comment.
"re-running costs nothing" undersells the cost — an audit is a multi-turn LLM flow with connector fetches and, in org mode, subagent fan-out; ai-readiness-audit/SKILL.md:118 is explicitly about minimizing engine calls because "in single-repo mode wall time is dominated by the number of serial turns". The property you want is safety, not free: "re-running is safe — it never modifies your source and never reads a previous audit" says the true thing, and the rest of this paragraph is accurate.
There was a problem hiding this comment.
Switched to safety framing — re-running is safe: never modifies source, never reads a prior audit.
| /plugin marketplace add provectus/awos | ||
| ``` | ||
|
|
||
| > **Adopting AWOS on an existing codebase?** The audit is the recommended first step of the brownfield path — run it before the foundation commands to get a baseline score and a punch list, then re-run it after adoption to see the delta. Its scoring is self-contained (it does not depend on the specialist agents `/awos:hire` installs), so it works the same on an untouched repo. See the [Brownfield Adoption Guide](../../docs/brownfield-adoption.md). |
There was a problem hiding this comment.
"re-run it after adoption to see the delta" reads like a feature, and there isn't one — same file at :86 says every audit "stands alone; earlier directories are history, never input". The guide gets this right at :35. Suggest "compare the two reports" so the two new pieces of prose in this PR agree.
There was a problem hiding this comment.
Changed to 'compare the two reports' — no delta feature, agreed.
| > **Running on an existing codebase?** Start with an AI readiness audit to understand how AI-friendly your project is. Install the plugin with `/plugin install awos@awos-marketplace`, then run `/awos:ai-readiness-audit` to get a scored assessment with actionable recommendations for improvement. [Learn more](plugins/awos/README.md) | ||
| > | ||
| > AWOS integrates seamlessly with existing projects — the setup commands auto-detect your codebase and use it as context, so you won't start from a blank slate. | ||
| > **Running on an existing codebase?** AWOS integrates seamlessly with brownfield projects — `/awos:product` auto-detects your code and stages what it finds, and the later foundation commands build on that so you won't start from a blank slate. The recommended first step is an AI-readiness audit: install the plugin with `/plugin install awos@awos-marketplace`, then run `/awos:ai-readiness-audit` for a scored assessment with actionable recommendations. See the **[Brownfield Adoption Guide](docs/brownfield-adoption.md)** for the full path — how detection works, what it produces, and how to steer it. |
There was a problem hiding this comment.
Preference rather than a defect, so take or leave it — but this rewrite puts the brownfield mechanism ahead of the audit recommendation and ends on "how detection works", and that's the ordering I asked to reverse on #137: keep the audit explanation leading, put brownfield exploration after it, and pitch seamless integration rather than explaining how it works inside.
To be fair to the rewrite: it's much shorter than the version that prompted that, it does keep "The recommended first step is an AI-readiness audit", and both install commands survive. But if you swap the two clauses — audit first, then "AWOS integrates seamlessly with brownfield projects, /awos:product auto-detects your code and the later commands build on that" — and end the guide link on the outcome rather than the mechanism, it lands the same content in the shape I was after.
There was a problem hiding this comment.
Swapped the clauses — audit leads now, brownfield integration after, and it ends on the outcome rather than the mechanism.
Fix ~14 prompt-accuracy defects Alexander flagged, plus structural cleanup: - roadmap.md prompt: only fully-implemented capabilities marked done (partial/scaffolded/TODO become upcoming items) — makes the doc claim true - guide: scope detection to /awos:product; add data-egress gate; correct retrieval attribution, restart trigger, triage timing, architecture defaults, retention wording, opt-out marker semantics, CI caveat - docs/commands/*.md brownfield sections made pointer-shaped (single source of truth in the guide), dropping duplicated/drifted claims - README: lead brownfield callout with the audit; add top-level Brownfield Adoption section for discoverability - plugin README: "see the delta" -> "compare the two reports" Co-Authored-By: Claude Opus 4.8 <[email protected]>
|
Thanks, really useful review — pushed in 8f67659. Addressed all the inline accuracy points. On the roadmap completion-status one I took the prompt route you suggested (added the rule to Two structural bits:
Lint 146/0, Prettier clean. |
2 participants
What
Documents the brownfield (existing-codebase) adoption path to parity with the greenfield Quick Start. The brownfield behaviour was shipped across prior PRs (detection in
/awos:product, capability/tech-stack passes in/awos:roadmapand/awos:architecture, external-source gathering) but lived only in the command prompts andCLAUDE.md— absent from every user-facing doc. This closes that gap.Roadmap item: Documented brownfield integration path (Brownfield, High).
Contents
docs/brownfield-adoption.md(new) — end-to-end guide: the AI-readiness audit as Step 0, the brownfield-awareproduct → roadmap → architectureflow, thebrownfield.md/context/sources/artifact lifecycle, opt-in/opt-out, and a greenfield-vs-brownfield comparison table.README.md— the "running on an existing codebase?" callout now links to the guide.docs/commands/product.md·roadmap.md·architecture.md— a "Brownfield mode" section in each, cross-linking the guide.plugins/awos/README.md— positions/awos:ai-readiness-auditas the recommended first step of brownfield adoption, noting its scoring is self-contained (independent of/awos:hire).Scope
Documentation only — no behaviour or engine changes, so no new test contracts (the lint layer already guards the command prompts these docs describe). Lint: 146 pass / 0 fail; Prettier clean; internal links resolve.
🤖 Generated with Claude Code
Summary by CodeRabbit
Documentation
Enhancements