@harness-engineering/cli 4.0.0 → 4.0.1

package/dist/agents/skills/claude-code/product-advisor/SKILL.md

@@ -0,0 +1,202 @@
+# Product Advisor
+
+> Turn a client diagram + conversation into a Business Requirements Document and a resolved gap-list, then seed the harness pipeline. The pre-inception front door: gather requirements with AI, feed them in, and let the existing flow continue as it does today.
+
+## When to Use
+
+- At the **inception** of a client engagement, when a solution architect / pre-sales engineer has a rough idea, a diagram, and conversation notes but no structured requirements yet.
+- When you want to turn "a diagram and some notes" into a client-legible BRD plus an explicit list of what is still unknown.
+- When the output should **seed the roadmap** (many work items) and ground the engagement's strategy — not produce a single spec.
+- NOT for authoring a spec/proposal — that is `harness-brainstorming`'s job. Product Advisor stops at BRD + roadmap seeding.
+- NOT for writing or updating `STRATEGY.md` directly — that is `harness-strategy`'s job. This skill only reads strategy and _offers_ to seed it.
+- NOT for internal feature work where the requirements already live in the codebase or an existing spec — go straight to `harness-brainstorming` or `harness-planning`.
+
+## Process
+
+### Iron Law
+
+**Every gap is either resolved in the interview or shipped as an explicit client-facing question — never silently dropped.** A BRD that hides what it does not know is worse than no BRD: it launders assumptions into requirements. If you cannot answer a gap and did not surface it in `gaps.md`, STOP and add it.
+
+---
+
+### Phase 1: INGEST — Gather the Raw Material
+
+1. **Resolve the engagement slug.** From the `engagement` argument, or ask the SA for a short name. This sets `docs/inception/<engagement>/` and the roadmap milestone `Inception: <engagement>`.
+2. **Ingest the diagram.** If a `diagram` argument (or a discoverable diagram) is present, parse it by calling `ingest_source({ path, source: "diagrams" })` (harness MCP) — the shipped diagram path handles diagram-as-code (Mermaid/D2/PlantUML) and image attachments (vision analysis). Then read the extracted entities and flows back via `gather_context` / `query_graph`. **Do not build a new parser** — reuse `ingest_source`.
+3. **Soft-degrade when parsing is unavailable.** If diagram parsing is unavailable or the diagram is unreadable, continue with **notes-only intake** and record a gap: `"diagram not machine-read; confirm entities and flows manually."` Do not fail.
+4. **Ingest the notes.** Load the client conversation notes / transcript from the `notes` argument or as provided. Call `gather_context` to pull any existing project/business knowledge that grounds the domain.
+5. **Normalize into intake.** Produce a structured intake: `{ entities[], flows[], notes }`. State the entities and flows back to the SA in one short summary and confirm before drafting.
+
+---
+
+### Phase 2: DRAFT-BRD — Synthesize the First Draft
+
+1. **Write the BRD** to `docs/inception/<engagement>/brd.md` with these sections, each present even if thin: _Context, Business Objectives, Scope, Functional Requirements, Non-Functional Requirements, Assumptions, Constraints, Out-of-Scope, Open Questions._
+2. **Phrase behavioral requirements with EARS patterns:**
+   - Event-driven: "When [trigger], the system shall [response]."
+   - Unwanted: "If [condition], then the system shall not [behavior]."
+3. **Tag gaps against the fixed BRD completeness rubric** (see below). Every rubric miss becomes a gap with `{ id, brdSection, question, severity: blocker|important|nice, status: open }`. Do not invent facts to fill a section — an empty-because-unknown section is a gap, not a place to guess.
+4. **Cite the source** of each requirement (`diagram`, `notes`, or later `interview`) so the SA can trace it.
+
+#### BRD completeness rubric
+
+- Each BRD section is non-empty and internally consistent.
+- Every diagram entity and flow maps to ≥1 functional requirement (or to an explicit gap).
+- Every functional requirement has an **actor + trigger + response**.
+- Every non-functional requirement is measurable (a number or a testable condition), else it is a gap.
+- Scope and Out-of-Scope do not contradict each other.
+
+---
+
+### Phase 3: GAP-INTERVIEW — Resolve What You Can
+
+1. **Ask ONE question at a time, in plain text.** Order the gap queue by severity (`blocker` → `important` → `nice`). Ask the highest-severity open gap first, wait for the answer, then continue.
+
+   **Ask directly in your reply. Do NOT route questions through `emit_interaction`, `AskUserQuestion`, or any tool** — those do not reliably surface the question to the human. Plain text in your own message is the only channel that reaches the SA across every client (Claude Code, Cursor, Codex, Gemini CLI).
+
+   Present each gap as a scannable multiple-choice table where options exist, and state a recommendation:
+
+   ```markdown
+   ### Gap G3 (blocker): What authenticates end users?
+
+   |             | A) Client SSO (SAML/OIDC) | B) Local accounts | C) Unknown — ask client |
+   | ----------- | ------------------------- | ----------------- | ----------------------- |
+   | **Implies** | IdP integration work      | Password storage  | Blocks scoping          |
+   | **Risk**    | Depends on client IdP     | Security burden   | —                       |
+
+   **Recommendation:** likely A given the enterprise diagram — confirm the IdP.
+   ```
+
+2. **Fold each answer back into the BRD.** Update the relevant section, add the requirement (source: `interview`), and move the gap `open → resolved` with the captured answer.
+3. **Mark unresolvable gaps client-facing.** If the SA cannot answer (only the client can), keep the gap `open` and phrase it as a question to ask the client.
+4. **Stop when the queue is drained** — every gap is either `resolved` or `open` (client-facing). Do not loop past a drained queue inventing new questions.
+
+---
+
+### Phase 4: FINALIZE — Ship and Hand Off
+
+1. **Write `gaps.md`** to `docs/inception/<engagement>/gaps.md` with two sections: **Resolved** (gap + captured answer) and **Open / chase-with-client** (each phrased as a question to ask the client).
+2. **Offer a STRATEGY.md seed.** In plain text, offer to seed the engagement's strategy via `/harness:strategy`, using the BRD's Business Objectives + Scope as grounding. **Never write `STRATEGY.md` yourself** — dispatch `harness-strategy` if the SA accepts.
+3. **Fan out into roadmap candidates.** Decompose the BRD scope into N candidate work items — each `{ title, summary, brdRefs[], rationale }`. Present them to the SA for a quick confirm/prune, then write each accepted item via `manage_roadmap` action `add`, `status: backlog`, `milestone: "Inception: <engagement>"`, with the BRD section reference in the summary. One BRD produces many rows — do not collapse the engagement into a single item.
+4. **Emit the handoff.** Record the transition to the roadmap/brainstorming flow via `emit_interaction`. State plainly that each roadmap item now enters the existing `roadmap-pilot → brainstorming → spec → plan → execute` pipeline. **Do not author a spec** — hand off to `harness-brainstorming` per item when the SA is ready.
+
+---
+
+## Harness Integration
+
+- **`gather_context`** — Phase 1: pull existing project/business knowledge to ground the domain.
+- **`ingest_source` (`source: "diagrams"`)** — Phase 1: parse diagrams (diagram-as-code + image vision) into the knowledge graph; read the extracted entities/flows back via `gather_context` / `query_graph`. Never reimplement the parser.
+- **`read_strategy`** — Phase 4: read `STRATEGY.md` (if present) to align the BRD; never write it.
+- **`manage_roadmap` (action `add`)** — Phase 4: create backlog roadmap rows from the BRD fan-out.
+- **`emit_interaction`** — Phase 4: record the handoff transition to the roadmap/brainstorming flow.
+- **`harness validate`** — After finalize: verify artifact placement and project health.
+
+## Success Criteria
+
+- Running the skill with a diagram + notes produces `docs/inception/<engagement>/brd.md` with all required sections, none empty.
+- Every diagram entity/flow maps to ≥1 BRD requirement or to an explicit gap.
+- `gaps.md` exists and separates **Resolved** from **Open/client-facing**; every open gap is phrased as a question.
+- The gap interview asked one question at a time and folded each answer into the BRD (resolved gaps moved `open → resolved`).
+- `finalize` created ≥1 candidate roadmap row via `manage_roadmap`, each linking back to a BRD section.
+- `finalize` offered a `STRATEGY.md` seed via `/harness:strategy` and did not write `STRATEGY.md` directly.
+- Behavioral functional requirements use EARS phrasing.
+- When diagram parsing was unavailable, the skill degraded to notes-only and recorded a gap rather than failing.
+- No spec/proposal was authored by this skill.
+
+## Examples
+
+### Example: retail loyalty engagement from a diagram + call notes
+
+**INGEST:**
+
+```
+engagement: acme-loyalty
+diagram: architecture.mmd (Mermaid) → parsed: entities [POS, Loyalty API, CRM, Rewards Engine], flows [POS→Loyalty API→CRM]
+notes: kickoff-call.md → loaded. gather_context: existing "loyalty" business facts surfaced.
+Confirmed entities/flows with SA. Proceed.
+```
+
+**DRAFT-BRD:** Wrote `docs/inception/acme-loyalty/brd.md`. 9 sections. Tagged 6 gaps:
+G1 (blocker) no auth model; G2 (blocker) Rewards Engine has no defined trigger; G3 (important) no NFR for POS latency; G4 (important) CRM data residency unknown; G5 (nice) reporting cadence; G6 (blocker) "Rewards Engine" entity maps to no requirement.
+
+**GAP-INTERVIEW:**
+
+```
+G1: "What authenticates end users? A) Client SSO B) Local C) Unknown" → SA: "A, Okta OIDC." → folded in.
+G2: "When does the Rewards Engine fire? A) On transaction B) Batch nightly C) Unknown" → SA: "A." → EARS: "When a qualifying transaction is recorded, the system shall evaluate reward eligibility."
+G3: "POS latency budget?" → SA: "client must confirm." → kept open, client-facing.
+G4: "CRM data residency?" → SA: "client must confirm." → kept open, client-facing.
+G6: resolved by G2. G5: SA: "monthly." → folded in.
+```
+
+**FINALIZE:**
+
+```
+Wrote gaps.md → Resolved: G1,G2,G5,G6 | Open/client-facing: G3 (latency), G4 (residency).
+Offered STRATEGY.md seed → SA accepted → dispatched /harness:strategy.
+Roadmap fan-out (milestone "Inception: acme-loyalty", backlog):
+  - "POS ↔ Loyalty API integration" (brd: Scope, FR-1)
+  - "Rewards Engine eligibility rules" (brd: FR-4)
+  - "Okta OIDC authentication" (brd: FR-2)
+  - "CRM sync + residency compliance" (brd: FR-5, NFR-2)
+Emitted handoff → each item enters roadmap-pilot → brainstorming. No spec authored.
+```
+
+## Gates
+
+- **No dropped gaps.** Every gap is `resolved` or shipped as an `open` client-facing question in `gaps.md`. A gap that is neither = Iron Law violation; stop and fix.
+- **No guessed requirements.** A BRD section that is unknown is a gap, not a place to invent facts. Fabricating a requirement to fill a section is a hard stop.
+- **No writing `STRATEGY.md`.** This skill reads strategy and offers to seed it via `/harness:strategy`. Writing `STRATEGY.md` directly = gate violation.
+- **No authoring specs.** This skill stops at BRD + roadmap seeding. Writing a `proposal.md` = gate violation; hand off to `harness-brainstorming`.
+- **No single-item collapse.** If the BRD scope contains multiple independent capabilities, `finalize` must produce multiple roadmap rows. Collapsing an engagement into one row defeats the fan-out.
+- **No hard failure on missing diagram.** Absent/unreadable diagram → notes-only + recorded gap. Aborting the run because a diagram would not parse = gate violation.
+
+## Escalation
+
+- **Diagram parses but entities contradict the notes:** Do not silently pick one. Surface the contradiction as a `blocker` gap and ask the SA which source is authoritative.
+- **The SA cannot answer any blocker gap:** The engagement is too early for a BRD. Report: "N blocker gaps are all client-facing; this needs a client conversation before a BRD is meaningful. Ship the gap-list as a client questionnaire and pause."
+- **Scope keeps expanding during the interview:** Stop. Report: "Scope has grown beyond the ingested material. Should we (A) bound the BRD to the original diagram/notes and log the rest as follow-up, or (B) re-ingest expanded material first?"
+- **`manage_roadmap` is unavailable:** Write the candidate items into `gaps.md` under a "Proposed roadmap items" heading and report: "Roadmap seeding skipped (manage_roadmap unavailable). Re-run finalize when MCP is restored."
+- **More than ~15 gaps after drafting:** The intake is too raw. Report and propose narrowing the engagement scope before interviewing, rather than running a 15-question interview.
+
+## Rationalizations to Reject
+
+| Rationalization                                                                 | Reality                                                                                                                                                                              |
+| ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| "The diagram implies the auth model, so I'll just write it as a requirement"    | An implication is not a confirmation. Diagram-implied facts that the client has not stated are gaps — surface them, don't launder them into requirements.                            |
+| "This gap is minor, I'll leave it out of gaps.md to keep it clean"              | The Iron Law is explicit: every gap is resolved or shipped. A gap you drop is an assumption the client discovers in production. `nice`-severity still ships.                         |
+| "I have enough to draft a proposal, I'll just write the spec too"               | Product Advisor stops at BRD + roadmap seeding. Authoring a spec skips `harness-brainstorming`'s design exploration, which is exactly where the gaps get weighed against approaches. |
+| "The BRD's objectives are clear, I'll seed STRATEGY.md directly to save a step" | This skill never writes `STRATEGY.md`. The `harness-strategy` boundary exists so strategy stays a deliberate, pushback-gated human commitment — not a side effect of inception.      |
+| "The engagement is really one big project, I'll make one roadmap row"           | A BRD describes a solution scope that fans out into many work items. One row defeats the whole handoff — each capability needs its own brainstorming → spec cycle.                   |
+| "The diagram won't parse, so I can't run — I'll abort"                          | Notes-only intake is a first-class path. Degrade, record the diagram as a gap, and continue. Aborting throws away the requirements the notes already contain.                        |
+
+## Red Flags
+
+| Flag                                                                             | Corrective Action                                                                                                                                                                                           |
+| -------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| "I'll fill the empty NFR section with reasonable defaults"                       | STOP. Unknown NFRs are gaps. Defaults you invent become requirements no one agreed to. Tag it as a gap and ask.                                                                                             |
+| "The interview is dragging; I'll batch the remaining questions into one message" | STOP. One question at a time is prescribed — batched questions get partial answers and lose the fold-back loop. Ask the next single highest-severity gap.                                                   |
+| "The SA said 'just make sensible assumptions'"                                   | STOP. Assumptions belong in the BRD's **Assumptions** section, labeled as assumptions, and the underlying unknowns stay in `gaps.md` as client-facing. Do not convert assumptions into silent requirements. |
+| `// TODO: confirm with client` left inside brd.md functional requirements        | STOP. Confirmation-needed items are gaps, not requirements. Move them to `gaps.md` (Open/client-facing) and keep the BRD's requirements limited to what is actually known.                                  |
+
+---
+
+<!--
+## Skill Test Scenarios
+
+### Scenario 1: Gate — "No dropped gaps"
+Input: Drafting produces a `nice`-severity gap (reporting cadence) the SA never answers and cannot be bothered to log.
+Expected: Agent keeps the gap and writes it to gaps.md under Open/client-facing rather than dropping it; cites the Iron Law / "No dropped gaps" gate.
+
+### Scenario 2: Rationalization — "I have enough to draft a proposal, I'll just write the spec too"
+Input: After a clean interview the agent is tempted to write docs/changes/<x>/proposal.md.
+Expected: Agent refuses, finalizes BRD + roadmap fan-out, and hands off to harness-brainstorming per item — no spec authored (gate: "No authoring specs").
+
+### Scenario 3: Gate/Escalation — soft-degrade on unreadable diagram
+Input: The provided diagram is a binary image the environment cannot vision-parse.
+Expected: Agent does not abort; runs notes-only intake and records "diagram not machine-read; confirm entities manually" as a gap (gate: "No hard failure on missing diagram").
+
+### Scenario 4: Rationalization — "This is really one big project, I'll make one roadmap row"
+Input: A BRD with 4 independent capabilities; agent tempted to add a single "Acme engagement" roadmap row.
+Expected: Agent fans out into one row per capability with BRD backrefs (gate: "No single-item collapse").
+-->

package/dist/agents/skills/claude-code/product-advisor/skill.yaml

@@ -0,0 +1,74 @@
+name: product-advisor
+version: "0.1.0"
+description: Upstream client-inception skill. Ingests a diagram + client conversation notes, drafts a Business Requirements Document (BRD), detects gaps against a fixed completeness rubric, resolves them through a one-question-at-a-time interview with the solution architect, then fans the BRD out into candidate roadmap items and offers a STRATEGY.md seed. Reads but never writes STRATEGY.md; never authors specs (harness-brainstorming owns that). The pre-inception front door to the harness pipeline.
+stability: static
+cognitive_mode: configuration-interviewer
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
+  - Glob
+  - Grep
+cli:
+  command: harness skill run product-advisor
+  args:
+    - name: engagement
+      description: Short name/slug for the client engagement. Used for the docs/inception/<engagement>/ artifact directory and the roadmap milestone.
+      required: false
+    - name: diagram
+      description: Path to a diagram (Mermaid/D2/PlantUML source or an image attachment) to ingest. Optional — the skill soft-degrades to notes-only when absent or unreadable.
+      required: false
+    - name: notes
+      description: Path to client conversation notes / call transcript to ingest.
+      required: false
+mcp:
+  tool: run_skill
+  input:
+    skill: product-advisor
+    path: string
+type: rigid
+tier: 1
+phases:
+  - name: ingest
+    description: Load diagram(s) + client conversation notes; reuse the business-knowledge diagram/vision path; normalize into a structured intake (entities, flows, notes). Soft-degrade to notes-only when diagram parsing is unavailable and record it as a gap.
+    required: true
+  - name: draft-brd
+    description: Synthesize a first BRD from intake into docs/inception/<engagement>/brd.md; tag every under-specified area as a gap against the fixed BRD completeness rubric. Behavioral requirements use EARS phrasing.
+    required: true
+  - name: gap-interview
+    description: Walk the solution architect through the gap queue one question at a time (plain-text tables); fold each answer back into the BRD; mark unresolved gaps as client-facing questions.
+    required: true
+  - name: finalize
+    description: Write brd.md + gaps.md (Resolved vs Open/client-facing); offer a STRATEGY.md seed via /harness:strategy; fan the BRD out into N candidate roadmap rows via manage_roadmap (status backlog) with backrefs to BRD sections; emit the handoff to the roadmap/brainstorming flow.
+    required: true
+state:
+  persistent: true
+  files:
+    - docs/inception/
+depends_on:
+  - harness-strategy
+  - harness-brainstorming
+related_skills:
+  - harness-strategy
+  - harness-brainstorming
+  - harness-ideate
+  - harness-roadmap-pilot
+keywords:
+  - product-advisor
+  - BRD
+  - business-requirements
+  - requirements-elicitation
+  - gap-analysis
+  - diagram-ingestion
+  - roadmap-decomposition
+  - pre-inception
+  - solution-architect
+  - upstream-grounding

package/dist/agents/skills/codex/product-advisor/SKILL.md

@@ -0,0 +1,202 @@
+# Product Advisor
+
+> Turn a client diagram + conversation into a Business Requirements Document and a resolved gap-list, then seed the harness pipeline. The pre-inception front door: gather requirements with AI, feed them in, and let the existing flow continue as it does today.
+
+## When to Use
+
+- At the **inception** of a client engagement, when a solution architect / pre-sales engineer has a rough idea, a diagram, and conversation notes but no structured requirements yet.
+- When you want to turn "a diagram and some notes" into a client-legible BRD plus an explicit list of what is still unknown.
+- When the output should **seed the roadmap** (many work items) and ground the engagement's strategy — not produce a single spec.
+- NOT for authoring a spec/proposal — that is `harness-brainstorming`'s job. Product Advisor stops at BRD + roadmap seeding.
+- NOT for writing or updating `STRATEGY.md` directly — that is `harness-strategy`'s job. This skill only reads strategy and _offers_ to seed it.
+- NOT for internal feature work where the requirements already live in the codebase or an existing spec — go straight to `harness-brainstorming` or `harness-planning`.
+
+## Process
+
+### Iron Law
+
+**Every gap is either resolved in the interview or shipped as an explicit client-facing question — never silently dropped.** A BRD that hides what it does not know is worse than no BRD: it launders assumptions into requirements. If you cannot answer a gap and did not surface it in `gaps.md`, STOP and add it.
+
+---
+
+### Phase 1: INGEST — Gather the Raw Material
+
+1. **Resolve the engagement slug.** From the `engagement` argument, or ask the SA for a short name. This sets `docs/inception/<engagement>/` and the roadmap milestone `Inception: <engagement>`.
+2. **Ingest the diagram.** If a `diagram` argument (or a discoverable diagram) is present, parse it by calling `ingest_source({ path, source: "diagrams" })` (harness MCP) — the shipped diagram path handles diagram-as-code (Mermaid/D2/PlantUML) and image attachments (vision analysis). Then read the extracted entities and flows back via `gather_context` / `query_graph`. **Do not build a new parser** — reuse `ingest_source`.
+3. **Soft-degrade when parsing is unavailable.** If diagram parsing is unavailable or the diagram is unreadable, continue with **notes-only intake** and record a gap: `"diagram not machine-read; confirm entities and flows manually."` Do not fail.
+4. **Ingest the notes.** Load the client conversation notes / transcript from the `notes` argument or as provided. Call `gather_context` to pull any existing project/business knowledge that grounds the domain.
+5. **Normalize into intake.** Produce a structured intake: `{ entities[], flows[], notes }`. State the entities and flows back to the SA in one short summary and confirm before drafting.
+
+---
+
+### Phase 2: DRAFT-BRD — Synthesize the First Draft
+
+1. **Write the BRD** to `docs/inception/<engagement>/brd.md` with these sections, each present even if thin: _Context, Business Objectives, Scope, Functional Requirements, Non-Functional Requirements, Assumptions, Constraints, Out-of-Scope, Open Questions._
+2. **Phrase behavioral requirements with EARS patterns:**
+   - Event-driven: "When [trigger], the system shall [response]."
+   - Unwanted: "If [condition], then the system shall not [behavior]."
+3. **Tag gaps against the fixed BRD completeness rubric** (see below). Every rubric miss becomes a gap with `{ id, brdSection, question, severity: blocker|important|nice, status: open }`. Do not invent facts to fill a section — an empty-because-unknown section is a gap, not a place to guess.
+4. **Cite the source** of each requirement (`diagram`, `notes`, or later `interview`) so the SA can trace it.
+
+#### BRD completeness rubric
+
+- Each BRD section is non-empty and internally consistent.
+- Every diagram entity and flow maps to ≥1 functional requirement (or to an explicit gap).
+- Every functional requirement has an **actor + trigger + response**.
+- Every non-functional requirement is measurable (a number or a testable condition), else it is a gap.
+- Scope and Out-of-Scope do not contradict each other.
+
+---
+
+### Phase 3: GAP-INTERVIEW — Resolve What You Can
+
+1. **Ask ONE question at a time, in plain text.** Order the gap queue by severity (`blocker` → `important` → `nice`). Ask the highest-severity open gap first, wait for the answer, then continue.
+
+   **Ask directly in your reply. Do NOT route questions through `emit_interaction`, `AskUserQuestion`, or any tool** — those do not reliably surface the question to the human. Plain text in your own message is the only channel that reaches the SA across every client (Claude Code, Cursor, Codex, Gemini CLI).
+
+   Present each gap as a scannable multiple-choice table where options exist, and state a recommendation:
+
+   ```markdown
+   ### Gap G3 (blocker): What authenticates end users?
+
+   |             | A) Client SSO (SAML/OIDC) | B) Local accounts | C) Unknown — ask client |
+   | ----------- | ------------------------- | ----------------- | ----------------------- |
+   | **Implies** | IdP integration work      | Password storage  | Blocks scoping          |
+   | **Risk**    | Depends on client IdP     | Security burden   | —                       |
+
+   **Recommendation:** likely A given the enterprise diagram — confirm the IdP.
+   ```
+
+2. **Fold each answer back into the BRD.** Update the relevant section, add the requirement (source: `interview`), and move the gap `open → resolved` with the captured answer.
+3. **Mark unresolvable gaps client-facing.** If the SA cannot answer (only the client can), keep the gap `open` and phrase it as a question to ask the client.
+4. **Stop when the queue is drained** — every gap is either `resolved` or `open` (client-facing). Do not loop past a drained queue inventing new questions.
+
+---
+
+### Phase 4: FINALIZE — Ship and Hand Off
+
+1. **Write `gaps.md`** to `docs/inception/<engagement>/gaps.md` with two sections: **Resolved** (gap + captured answer) and **Open / chase-with-client** (each phrased as a question to ask the client).
+2. **Offer a STRATEGY.md seed.** In plain text, offer to seed the engagement's strategy via `/harness:strategy`, using the BRD's Business Objectives + Scope as grounding. **Never write `STRATEGY.md` yourself** — dispatch `harness-strategy` if the SA accepts.
+3. **Fan out into roadmap candidates.** Decompose the BRD scope into N candidate work items — each `{ title, summary, brdRefs[], rationale }`. Present them to the SA for a quick confirm/prune, then write each accepted item via `manage_roadmap` action `add`, `status: backlog`, `milestone: "Inception: <engagement>"`, with the BRD section reference in the summary. One BRD produces many rows — do not collapse the engagement into a single item.
+4. **Emit the handoff.** Record the transition to the roadmap/brainstorming flow via `emit_interaction`. State plainly that each roadmap item now enters the existing `roadmap-pilot → brainstorming → spec → plan → execute` pipeline. **Do not author a spec** — hand off to `harness-brainstorming` per item when the SA is ready.
+
+---
+
+## Harness Integration
+
+- **`gather_context`** — Phase 1: pull existing project/business knowledge to ground the domain.
+- **`ingest_source` (`source: "diagrams"`)** — Phase 1: parse diagrams (diagram-as-code + image vision) into the knowledge graph; read the extracted entities/flows back via `gather_context` / `query_graph`. Never reimplement the parser.
+- **`read_strategy`** — Phase 4: read `STRATEGY.md` (if present) to align the BRD; never write it.
+- **`manage_roadmap` (action `add`)** — Phase 4: create backlog roadmap rows from the BRD fan-out.
+- **`emit_interaction`** — Phase 4: record the handoff transition to the roadmap/brainstorming flow.
+- **`harness validate`** — After finalize: verify artifact placement and project health.
+
+## Success Criteria
+
+- Running the skill with a diagram + notes produces `docs/inception/<engagement>/brd.md` with all required sections, none empty.
+- Every diagram entity/flow maps to ≥1 BRD requirement or to an explicit gap.
+- `gaps.md` exists and separates **Resolved** from **Open/client-facing**; every open gap is phrased as a question.
+- The gap interview asked one question at a time and folded each answer into the BRD (resolved gaps moved `open → resolved`).
+- `finalize` created ≥1 candidate roadmap row via `manage_roadmap`, each linking back to a BRD section.
+- `finalize` offered a `STRATEGY.md` seed via `/harness:strategy` and did not write `STRATEGY.md` directly.
+- Behavioral functional requirements use EARS phrasing.
+- When diagram parsing was unavailable, the skill degraded to notes-only and recorded a gap rather than failing.
+- No spec/proposal was authored by this skill.
+
+## Examples
+
+### Example: retail loyalty engagement from a diagram + call notes
+
+**INGEST:**
+
+```
+engagement: acme-loyalty
+diagram: architecture.mmd (Mermaid) → parsed: entities [POS, Loyalty API, CRM, Rewards Engine], flows [POS→Loyalty API→CRM]
+notes: kickoff-call.md → loaded. gather_context: existing "loyalty" business facts surfaced.
+Confirmed entities/flows with SA. Proceed.
+```
+
+**DRAFT-BRD:** Wrote `docs/inception/acme-loyalty/brd.md`. 9 sections. Tagged 6 gaps:
+G1 (blocker) no auth model; G2 (blocker) Rewards Engine has no defined trigger; G3 (important) no NFR for POS latency; G4 (important) CRM data residency unknown; G5 (nice) reporting cadence; G6 (blocker) "Rewards Engine" entity maps to no requirement.
+
+**GAP-INTERVIEW:**
+
+```
+G1: "What authenticates end users? A) Client SSO B) Local C) Unknown" → SA: "A, Okta OIDC." → folded in.
+G2: "When does the Rewards Engine fire? A) On transaction B) Batch nightly C) Unknown" → SA: "A." → EARS: "When a qualifying transaction is recorded, the system shall evaluate reward eligibility."
+G3: "POS latency budget?" → SA: "client must confirm." → kept open, client-facing.
+G4: "CRM data residency?" → SA: "client must confirm." → kept open, client-facing.
+G6: resolved by G2. G5: SA: "monthly." → folded in.
+```
+
+**FINALIZE:**
+
+```
+Wrote gaps.md → Resolved: G1,G2,G5,G6 | Open/client-facing: G3 (latency), G4 (residency).
+Offered STRATEGY.md seed → SA accepted → dispatched /harness:strategy.
+Roadmap fan-out (milestone "Inception: acme-loyalty", backlog):
+  - "POS ↔ Loyalty API integration" (brd: Scope, FR-1)
+  - "Rewards Engine eligibility rules" (brd: FR-4)
+  - "Okta OIDC authentication" (brd: FR-2)
+  - "CRM sync + residency compliance" (brd: FR-5, NFR-2)
+Emitted handoff → each item enters roadmap-pilot → brainstorming. No spec authored.
+```
+
+## Gates
+
+- **No dropped gaps.** Every gap is `resolved` or shipped as an `open` client-facing question in `gaps.md`. A gap that is neither = Iron Law violation; stop and fix.
+- **No guessed requirements.** A BRD section that is unknown is a gap, not a place to invent facts. Fabricating a requirement to fill a section is a hard stop.
+- **No writing `STRATEGY.md`.** This skill reads strategy and offers to seed it via `/harness:strategy`. Writing `STRATEGY.md` directly = gate violation.
+- **No authoring specs.** This skill stops at BRD + roadmap seeding. Writing a `proposal.md` = gate violation; hand off to `harness-brainstorming`.
+- **No single-item collapse.** If the BRD scope contains multiple independent capabilities, `finalize` must produce multiple roadmap rows. Collapsing an engagement into one row defeats the fan-out.
+- **No hard failure on missing diagram.** Absent/unreadable diagram → notes-only + recorded gap. Aborting the run because a diagram would not parse = gate violation.
+
+## Escalation
+
+- **Diagram parses but entities contradict the notes:** Do not silently pick one. Surface the contradiction as a `blocker` gap and ask the SA which source is authoritative.
+- **The SA cannot answer any blocker gap:** The engagement is too early for a BRD. Report: "N blocker gaps are all client-facing; this needs a client conversation before a BRD is meaningful. Ship the gap-list as a client questionnaire and pause."
+- **Scope keeps expanding during the interview:** Stop. Report: "Scope has grown beyond the ingested material. Should we (A) bound the BRD to the original diagram/notes and log the rest as follow-up, or (B) re-ingest expanded material first?"
+- **`manage_roadmap` is unavailable:** Write the candidate items into `gaps.md` under a "Proposed roadmap items" heading and report: "Roadmap seeding skipped (manage_roadmap unavailable). Re-run finalize when MCP is restored."
+- **More than ~15 gaps after drafting:** The intake is too raw. Report and propose narrowing the engagement scope before interviewing, rather than running a 15-question interview.
+
+## Rationalizations to Reject
+
+| Rationalization                                                                 | Reality                                                                                                                                                                              |
+| ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| "The diagram implies the auth model, so I'll just write it as a requirement"    | An implication is not a confirmation. Diagram-implied facts that the client has not stated are gaps — surface them, don't launder them into requirements.                            |
+| "This gap is minor, I'll leave it out of gaps.md to keep it clean"              | The Iron Law is explicit: every gap is resolved or shipped. A gap you drop is an assumption the client discovers in production. `nice`-severity still ships.                         |
+| "I have enough to draft a proposal, I'll just write the spec too"               | Product Advisor stops at BRD + roadmap seeding. Authoring a spec skips `harness-brainstorming`'s design exploration, which is exactly where the gaps get weighed against approaches. |
+| "The BRD's objectives are clear, I'll seed STRATEGY.md directly to save a step" | This skill never writes `STRATEGY.md`. The `harness-strategy` boundary exists so strategy stays a deliberate, pushback-gated human commitment — not a side effect of inception.      |
+| "The engagement is really one big project, I'll make one roadmap row"           | A BRD describes a solution scope that fans out into many work items. One row defeats the whole handoff — each capability needs its own brainstorming → spec cycle.                   |
+| "The diagram won't parse, so I can't run — I'll abort"                          | Notes-only intake is a first-class path. Degrade, record the diagram as a gap, and continue. Aborting throws away the requirements the notes already contain.                        |
+
+## Red Flags
+
+| Flag                                                                             | Corrective Action                                                                                                                                                                                           |
+| -------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| "I'll fill the empty NFR section with reasonable defaults"                       | STOP. Unknown NFRs are gaps. Defaults you invent become requirements no one agreed to. Tag it as a gap and ask.                                                                                             |
+| "The interview is dragging; I'll batch the remaining questions into one message" | STOP. One question at a time is prescribed — batched questions get partial answers and lose the fold-back loop. Ask the next single highest-severity gap.                                                   |
+| "The SA said 'just make sensible assumptions'"                                   | STOP. Assumptions belong in the BRD's **Assumptions** section, labeled as assumptions, and the underlying unknowns stay in `gaps.md` as client-facing. Do not convert assumptions into silent requirements. |
+| `// TODO: confirm with client` left inside brd.md functional requirements        | STOP. Confirmation-needed items are gaps, not requirements. Move them to `gaps.md` (Open/client-facing) and keep the BRD's requirements limited to what is actually known.                                  |
+
+---
+
+<!--
+## Skill Test Scenarios
+
+### Scenario 1: Gate — "No dropped gaps"
+Input: Drafting produces a `nice`-severity gap (reporting cadence) the SA never answers and cannot be bothered to log.
+Expected: Agent keeps the gap and writes it to gaps.md under Open/client-facing rather than dropping it; cites the Iron Law / "No dropped gaps" gate.
+
+### Scenario 2: Rationalization — "I have enough to draft a proposal, I'll just write the spec too"
+Input: After a clean interview the agent is tempted to write docs/changes/<x>/proposal.md.
+Expected: Agent refuses, finalizes BRD + roadmap fan-out, and hands off to harness-brainstorming per item — no spec authored (gate: "No authoring specs").
+
+### Scenario 3: Gate/Escalation — soft-degrade on unreadable diagram
+Input: The provided diagram is a binary image the environment cannot vision-parse.
+Expected: Agent does not abort; runs notes-only intake and records "diagram not machine-read; confirm entities manually" as a gap (gate: "No hard failure on missing diagram").
+
+### Scenario 4: Rationalization — "This is really one big project, I'll make one roadmap row"
+Input: A BRD with 4 independent capabilities; agent tempted to add a single "Acme engagement" roadmap row.
+Expected: Agent fans out into one row per capability with BRD backrefs (gate: "No single-item collapse").
+-->

package/dist/agents/skills/codex/product-advisor/skill.yaml

@@ -0,0 +1,74 @@
+name: product-advisor
+version: "0.1.0"
+description: Upstream client-inception skill. Ingests a diagram + client conversation notes, drafts a Business Requirements Document (BRD), detects gaps against a fixed completeness rubric, resolves them through a one-question-at-a-time interview with the solution architect, then fans the BRD out into candidate roadmap items and offers a STRATEGY.md seed. Reads but never writes STRATEGY.md; never authors specs (harness-brainstorming owns that). The pre-inception front door to the harness pipeline.
+stability: static
+cognitive_mode: configuration-interviewer
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
+  - Glob
+  - Grep
+cli:
+  command: harness skill run product-advisor
+  args:
+    - name: engagement
+      description: Short name/slug for the client engagement. Used for the docs/inception/<engagement>/ artifact directory and the roadmap milestone.
+      required: false
+    - name: diagram
+      description: Path to a diagram (Mermaid/D2/PlantUML source or an image attachment) to ingest. Optional — the skill soft-degrades to notes-only when absent or unreadable.
+      required: false
+    - name: notes
+      description: Path to client conversation notes / call transcript to ingest.
+      required: false
+mcp:
+  tool: run_skill
+  input:
+    skill: product-advisor
+    path: string
+type: rigid
+tier: 1
+phases:
+  - name: ingest
+    description: Load diagram(s) + client conversation notes; reuse the business-knowledge diagram/vision path; normalize into a structured intake (entities, flows, notes). Soft-degrade to notes-only when diagram parsing is unavailable and record it as a gap.
+    required: true
+  - name: draft-brd
+    description: Synthesize a first BRD from intake into docs/inception/<engagement>/brd.md; tag every under-specified area as a gap against the fixed BRD completeness rubric. Behavioral requirements use EARS phrasing.
+    required: true
+  - name: gap-interview
+    description: Walk the solution architect through the gap queue one question at a time (plain-text tables); fold each answer back into the BRD; mark unresolved gaps as client-facing questions.
+    required: true
+  - name: finalize
+    description: Write brd.md + gaps.md (Resolved vs Open/client-facing); offer a STRATEGY.md seed via /harness:strategy; fan the BRD out into N candidate roadmap rows via manage_roadmap (status backlog) with backrefs to BRD sections; emit the handoff to the roadmap/brainstorming flow.
+    required: true
+state:
+  persistent: true
+  files:
+    - docs/inception/
+depends_on:
+  - harness-strategy
+  - harness-brainstorming
+related_skills:
+  - harness-strategy
+  - harness-brainstorming
+  - harness-ideate
+  - harness-roadmap-pilot
+keywords:
+  - product-advisor
+  - BRD
+  - business-requirements
+  - requirements-elicitation
+  - gap-analysis
+  - diagram-ingestion
+  - roadmap-decomposition
+  - pre-inception
+  - solution-architect
+  - upstream-grounding