feat: brownfield awareness across product, roadmap, and architecture

CLAUDE.md

@@ -89,7 +89,11 @@ Each file in `claude/commands/{name}.md` is a tiny wrapper that points at `.awos
 
 ## Architecture: Document-Centric Workflow
 
-AWOS is **spec-driven** — all project state lives in markdown files under `context/` in the user's project, not in chat history. An AI agent can rehydrate full context by reading the files alone. The canonical flow (each command is a markdown prompt under `commands/`):
+AWOS is **spec-driven** — all project state lives in markdown files under `context/` in the user's project, not in chat history. An AI agent can rehydrate full context by reading the files alone.
+
+**Brownfield projects** get automatic codebase awareness. `/awos:product` detects existing source code (during Creation Mode only) and creates `context/product/brownfield.md` with triaged findings about purpose, audience, and features. `/awos:roadmap` and `/awos:architecture` read that file and run their own focused explorations (capabilities and tech stack respectively), passing prior findings to avoid duplicate questions. All findings are triaged with the user (accept / correct / reject). `/awos:hire` removes the file after all knowledge is absorbed into the product, roadmap, and architecture documents.
+
+The canonical flow (each command is a markdown prompt under `commands/`):
 
 ```
 /awos:product → /awos:roadmap → /awos:architecture → /awos:hire

README.md

@@ -21,7 +21,7 @@ npx @provectusinc/awos
 
 This sets up the `.awos/` directory (commands, templates, scripts), the `.claude/commands/awos/` wrappers, and the `context/` directory where your project documents will live. It also registers the AWOS plugin marketplace in your project settings.
 
-> **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)
+> **Running on an existing codebase?** AWOS auto-detects brownfield projects. `/awos:product` explores what your project does, `/awos:roadmap` maps what's already built, and `/awos:architecture` discovers your tech stack — each presenting findings for you to accept, correct, or reject before continuing the normal interview. You can also run an AI readiness audit: install the plugin with `/plugin install awos@awos-marketplace`, then run `/awos:ai-readiness-audit`. [Learn more](plugins/awos/README.md)
 
 ### Step 2: Foundation Setup
 

commands/architecture.md

@@ -49,12 +49,42 @@ Follow this logic precisely.
 ## Scenario 1: Creation Mode
 
 1.  Read and synthesize the product definition and roadmap, paying close attention to features planned for Phase 1.
-2.  Work through the template section by section — not all at once.
+2.  **Brownfield context.** Check if `context/product/brownfield.md` exists (produced by `/awos:product` when it detects an existing codebase). If it does:
+
+    a. Read `context/product/brownfield.md`.
+
+    b. Construct the Explore prompt by reading `context/product/brownfield.md` and embedding its full content between `<existing_findings>` and `</existing_findings>` tags. Then launch an `Explore` agent focused on the technology stack:
+
+    ```text
+    Agent(subagent_type="Explore", description="Discover existing tech stack", prompt="
+    Explore this codebase and document the existing technology stack. Focus on:
+    - Languages and frameworks (with versions from config files)
+    - Databases, ORMs, and data stores
+    - Infrastructure (Docker, cloud configs, deployment scripts)
+    - External services and APIs (auth providers, payment, analytics)
+    - Testing frameworks and tools
+    - Build tools, bundlers, CI/CD
+
+    The following findings were already confirmed by the user — do not repeat them:
+
+    <existing_findings>
+    ... brownfield.md contents ...
+    </existing_findings>
+
+    Report only NEW findings not covered above. For each technology found, cite the file paths that evidence it. Be concise — report findings as bullet points.
+    ")
+    ```
+
+    c. Walk through any new findings with `AskUserQuestion` (Accept / Accept with corrections / Reject), same as earlier commands. Append accepted findings to `context/product/brownfield.md` under a `## Technology` heading. For corrected findings, record the corrected version.
+
+    d. Use the confirmed technology findings to pre-fill the architecture template. Frame the section-by-section walkthrough as "here's what you're using — confirm, and tell me what you want to change or add for the roadmap ahead."
+
+3.  Work through the template section by section — not all at once.
     - For each architectural area, propose a concrete title from the template placeholder.
-    - For each component, propose a specific technology with one or more alternatives, justified by the project context.
+    - For each component, propose a specific technology with one or more alternatives, justified by the project context. When brownfield findings provided a known technology, present it as the default.
     - If the user is unsure, ask clarifying questions about team skills, budget, or priorities. Do not proceed until the current section is confirmed.
     - Repeat for every architectural area (Data, Infrastructure, etc.).
-3.  Once all sections are confirmed, proceed to **Step 3: Finalization**.
+4.  Once all sections are confirmed, proceed to **Step 3: Finalization**.
 
 ---
 

commands/hire.md

@@ -208,4 +208,8 @@ Report:
 - **Coverage Report:** path to `context/product/hired-agents.md`
 - **Gaps Remaining:** any technologies without specific skill coverage
 
+## Step 10: Brownfield Cleanup
+
+If `context/product/brownfield.md` exists, delete it. By this point all brownfield knowledge has been absorbed into `product-definition.md`, `roadmap.md`, and `architecture.md` — the brownfield file is no longer needed.
+
 End with the next command: `/awos:tasks`.

commands/product.md

@@ -62,14 +62,37 @@ First, check if the file `context/product/product-definition.md` exists.
 
 ### Step 2B: Creation Mode
 
-1.  If `<user_prompt>` is non-empty, briefly note that you'll use it as a starting point, then refine from there.
-2.  Walk the user through the sections of the template, explaining each one.
+1.  **Brownfield detection.** Check whether the project already has source code by looking for common indicators (`src/`, `app/`, `lib/`, `package.json`, `requirements.txt`, `go.mod`, `Cargo.toml`, `pom.xml`, `Gemfile`, `build.gradle`, `*.csproj`, `Makefile`, `CMakeLists.txt`, `setup.py`, `pyproject.toml`, or similar). If any are found, this is a brownfield project — run a comprehensive exploration before starting the interview:
+
+    a. Launch an `Explore` agent focused on the product domain:
+
+    ```text
+    Agent(subagent_type="Explore", description="Understand existing product", prompt="
+    Explore this codebase and determine what this project does. Focus on:
+    - Purpose and problem being solved (README, docs, package metadata, comments)
+    - Target audience signals (UI copy, API design, documentation tone, onboarding flow)
+    - Main features and capabilities (entry points, routes, commands, key modules)
+    - User journey (how someone uses this from start to finish)
+
+    For each finding, cite the file paths that evidence it. Be concise — report findings as bullet points.
+    ")
+    ```
+
+    b. Walk through the findings one by one — each discovered entity (purpose, audience signal, feature, journey step) gets its own confirmation. For each finding, use `AskUserQuestion` with three options:
+    - **Accept** — the finding is accurate as stated.
+    - **Accept with corrections** — the finding is directionally right but needs adjustment. If chosen, ask the user for their correction.
+    - **Reject** — the finding is wrong or irrelevant; discard it.
+
+    c. Write all accepted and corrected findings to `context/product/brownfield.md` under a `## Product` heading. For corrected findings, record the corrected version, not the original. Downstream commands (`/awos:roadmap`, `/awos:architecture`) will append their own findings to this file.
+
+2.  If `<user_prompt>` is non-empty, briefly note that you'll use it as a starting point, then refine from there.
+3.  Walk the user through the sections of the template. When step 1 produced brownfield findings, use the Product section to propose draft answers — frame questions as "does this match what you intend, or would you change it?" rather than asking from a blank slate. The interview still covers every section; the exploration gives better defaults, not fewer questions.
     - **Project Name & Vision:** Ask for the project's name and its core purpose.
     - **Target Audience & Personas:** Ask who the product is for and help create one simple persona.
     - **Success Metrics:** Ask how they will measure the product's impact on the user.
     - **Core Features & User Journey:** Ask for the 3-5 most important high-level features and a simple user workflow.
     - **Project Boundaries:** Ask what is essential for the first version (In-Scope) and what can wait (Out-of-Scope).
-3.  Once all sections are complete, proceed to **Step 3: File Generation**.
+4.  Once all sections are complete, proceed to **Step 3: File Generation**.
 
 ---
 

commands/roadmap.md

@@ -51,9 +51,36 @@ Follow this logic precisely.
 ## Scenario 1: Creation Mode
 
 1.  Read `context/product/product-definition.md` and the template at `.awos/templates/roadmap-template.md`.
-2.  Generate a proposed roadmap by populating the template structure with the product definition's Core Features, grouped into logical sequential phases.
-3.  Present the full draft to the user and ask for feedback.
-4.  Iterate until the user is satisfied, then proceed to **Step 3: Finalization**.
+2.  **Brownfield context.** Check if `context/product/brownfield.md` exists (produced by `/awos:product` when it detects an existing codebase). If it does:
+
+    a. Read `context/product/brownfield.md`.
+
+    b. Construct the Explore prompt by reading `context/product/brownfield.md` and embedding its full content between `<existing_findings>` and `</existing_findings>` tags. Then launch an `Explore` agent focused on existing capabilities:
+
+    ```text
+    Agent(subagent_type="Explore", description="Assess existing capabilities", prompt="
+    Explore this codebase and assess what's already built. Focus on:
+    - Features that are fully implemented and working (with evidence: routes, UI, tests)
+    - Features that appear partially implemented or scaffolded
+    - TODOs, FIXMEs, or planned features mentioned in code or docs
+
+    The following findings were already confirmed by the user — do not repeat them:
+
+    <existing_findings>
+    ... brownfield.md contents ...
+    </existing_findings>
+
+    Report only NEW findings not covered above. For each finding, cite the file paths that evidence it. Be concise — report findings as bullet points.
+    ")
+    ```
+
+    c. Walk through any new findings with `AskUserQuestion` (Accept / Accept with corrections / Reject), same as `/awos:product` does. Append accepted findings to `context/product/brownfield.md` under a `## Capabilities` heading. For corrected findings, record the corrected version.
+
+    d. Use the full set of confirmed capabilities (from brownfield.md) to anchor the roadmap: existing capabilities are noted as already done, and new phases focus on what comes next. Feed this into the roadmap generation in the next step.
+
+3.  Generate a proposed roadmap by populating the template structure with the product definition's Core Features, grouped into logical sequential phases.
+4.  Present the full draft to the user and ask for feedback.
+5.  Iterate until the user is satisfied, then proceed to **Step 3: Finalization**.
 
 ---
 

tests/lint-prompts.test.js

@@ -657,6 +657,105 @@ test('SDD-07 recognizes the dual-model QA coverage', () => {
   );
 });
 
+// ---------------------------------------------------------------------------
+// Brownfield awareness contracts
+// ---------------------------------------------------------------------------
+
+test('product.md creates context/product/brownfield.md on brownfield detection', () => {
+  // /awos:product is the entry point for brownfield detection. When it finds
+  // source code indicators it must explore the codebase and write accepted
+  // findings to context/product/brownfield.md. Downstream commands (roadmap,
+  // architecture) depend on this file existing to avoid duplicate exploration.
+  const body = readUtf8(path.join(commandsDir, 'product.md'));
+  assert.ok(
+    body.includes('context/product/brownfield.md'),
+    'commands/product.md must reference context/product/brownfield.md as the brownfield findings destination'
+  );
+  assert.ok(
+    /## Product/.test(body),
+    'commands/product.md must write brownfield findings under a "## Product" heading'
+  );
+});
+
+test('roadmap.md reads brownfield.md and appends a Capabilities section', () => {
+  // /awos:roadmap reads the brownfield file produced by /awos:product and
+  // runs its own focused exploration for capabilities. It must append its
+  // findings under a "## Capabilities" heading so /awos:architecture can
+  // see the accumulated context.
+  const body = readUtf8(path.join(commandsDir, 'roadmap.md'));
+  assert.ok(
+    body.includes('context/product/brownfield.md'),
+    'commands/roadmap.md must reference context/product/brownfield.md to consume and extend brownfield findings'
+  );
+  assert.ok(
+    /## Capabilities/.test(body),
+    'commands/roadmap.md must append brownfield findings under a "## Capabilities" heading'
+  );
+});
+
+test('architecture.md reads brownfield.md and appends a Technology section', () => {
+  // /awos:architecture reads the accumulated brownfield file and runs a
+  // focused exploration for the tech stack. It must append its findings
+  // under a "## Technology" heading.
+  const body = readUtf8(path.join(commandsDir, 'architecture.md'));
+  assert.ok(
+    body.includes('context/product/brownfield.md'),
+    'commands/architecture.md must reference context/product/brownfield.md to consume and extend brownfield findings'
+  );
+  assert.ok(
+    /## Technology/.test(body),
+    'commands/architecture.md must append brownfield findings under a "## Technology" heading'
+  );
+});
+
+test('hire.md removes brownfield.md after onboarding completes', () => {
+  // /awos:hire is the last onboarding command. By this point all brownfield
+  // knowledge has been absorbed into product-definition.md, roadmap.md, and
+  // architecture.md. The brownfield file must be cleaned up.
+  const body = readUtf8(path.join(commandsDir, 'hire.md'));
+  assert.ok(
+    body.includes('context/product/brownfield.md'),
+    'commands/hire.md must reference context/product/brownfield.md for cleanup'
+  );
+  assert.ok(
+    /delete|remove/i.test(
+      body.substring(body.indexOf('context/product/brownfield.md'))
+    ),
+    'commands/hire.md must delete context/product/brownfield.md during its final steps'
+  );
+});
+
+test('brownfield exploration passes existing findings to avoid duplicates', () => {
+  // Each downstream exploration (roadmap, architecture) must pass the
+  // current brownfield.md content to the Explore agent so it skips
+  // already-confirmed findings. The literal <existing_findings> tag is
+  // the contract — if renamed, the Explore prompt silently ignores it.
+  for (const cmd of ['roadmap.md', 'architecture.md']) {
+    const body = readUtf8(path.join(commandsDir, cmd));
+    assert.ok(
+      body.includes('<existing_findings>'),
+      `commands/${cmd} must pass existing brownfield findings inside <existing_findings> tags to the Explore agent`
+    );
+  }
+});
+
+test('brownfield commands use accept/correct/reject triage for findings', () => {
+  // All three brownfield-aware commands must walk through findings
+  // with the user using the same three-option triage pattern. This
+  // ensures consistent UX across the onboarding flow.
+  for (const cmd of ['product.md', 'roadmap.md', 'architecture.md']) {
+    const body = readUtf8(path.join(commandsDir, cmd));
+    assert.ok(
+      /Accept with corrections/i.test(body),
+      `commands/${cmd} must offer "Accept with corrections" as a triage option for brownfield findings`
+    );
+    assert.ok(
+      /Reject/i.test(body),
+      `commands/${cmd} must offer "Reject" as a triage option for brownfield findings`
+    );
+  }
+});
+
 test('context/<path> references in prompts are internally consistent', () => {
   // Build a writer/reader map by scanning all prompts. A path is considered
   // consistent if every reference to it appears in at least one prompt — i.e.