From acd01369e4b5dca4138cc22536dd58132f5f5396 Mon Sep 17 00:00:00 2001 From: Brian McManus Date: Sat, 9 May 2026 16:59:18 -0700 Subject: [PATCH 01/27] Add dual-runtime portability plan --- docs/runtime-portability.md | 89 +++++++++++++++++++++++++++++++++++++ 1 file changed, 89 insertions(+) create mode 100644 docs/runtime-portability.md diff --git a/docs/runtime-portability.md b/docs/runtime-portability.md new file mode 100644 index 0000000..cc484f6 --- /dev/null +++ b/docs/runtime-portability.md @@ -0,0 +1,89 @@ +# Runtime Portability Plan + +AI-Product-Team should support both Claude Code and Codex without splitting into two products. The product logic belongs in shared, runtime-neutral files; Claude and Codex should be thin adapters over the same Working Backwards pipeline. + +## Goals + +- Keep one canonical Working Backwards methodology, pipeline, rubric set, and output structure. +- Preserve the existing Claude Code extension experience. +- Add a Codex-native workflow that can run the same stages and write the same session artifacts. +- Avoid drift between Claude and Codex prompts, rubrics, and stage definitions. + +## Non-Goals + +- Replacing Claude support. +- Creating two separate implementations of the product process. +- Changing the Working Backwards methodology or stage gate rules during the portability work. + +## Target Structure + +```text +shared/ + pipeline.json + README.md + agents/ + methodology/ + rubrics/ + templates/ + +.claude/ + agents/ + skills/ + +.codex/ + skills/ + +AGENTS.md +``` + +## Shared Core + +The shared core is the source of truth for product behavior. It should contain: + +- Stage order and gate rules. +- Agent role definitions. +- Critic rubrics. +- Output templates. +- Session schema expectations. +- Methodology reference material. + +Runtime adapters may add tool-specific instructions, but they should not redefine stage semantics. + +## Claude Adapter + +The existing `.claude/` files remain the Claude Code adapter. Over time, the Claude agent and skill files should reference the shared core instead of duplicating the full stage definitions inline. + +## Codex Adapter + +The Codex adapter should provide: + +- A repo-level `AGENTS.md` that tells Codex how to operate the pipeline. +- `.codex/skills/working-backwards/SKILL.md` for starting or resuming a session. +- `.codex/skills/wb-status/SKILL.md` for read-only status inspection. +- The same `working-backwards/{session-id}/` output layout as Claude. + +Codex is especially well suited for stages that require editing, running, and verifying generated apps, such as Visual Demo and Site Builder. + +## Migration Sequence + +1. Add shared core files without changing existing Claude behavior. +2. Add Codex adapter instructions that consume the shared core. +3. Update README and PRD to describe dual-runtime support. +4. Gradually refactor `.claude/` files to reference shared files and reduce duplication. +5. Add validation checks that confirm both runtimes produce compatible session artifacts. + +## Compatibility Contract + +Both runtimes must produce sessions with: + +- `session.json` +- `press-release.md` +- `faq-external.md` +- `faq-internal.md` +- `demo/` +- `docs/` +- `telemetry.md` +- `requirements.md` +- `site/` + +Both runtimes must enforce the same gate: no stage advances until the Critic returns `VERDICT: PASS`, except where the documented max-revision pause behavior applies. From f89275f76ca52b148e59aa8279732988ebd7ce8f Mon Sep 17 00:00:00 2001 From: Brian McManus Date: Sat, 9 May 2026 16:59:31 -0700 Subject: [PATCH 02/27] Add shared core README --- shared/README.md | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) create mode 100644 shared/README.md diff --git a/shared/README.md b/shared/README.md new file mode 100644 index 0000000..f6b8558 --- /dev/null +++ b/shared/README.md @@ -0,0 +1,20 @@ +# Shared Working Backwards Core + +This directory contains runtime-neutral product definitions for AI-Product-Team. + +Claude Code and Codex adapters should both consume this shared core rather than redefining the Working Backwards process independently. + +## Contents + +- `pipeline.json` - canonical stage order, artifact names, gate rules, and runtime compatibility expectations. + +Planned shared directories: + +- `agents/` - runtime-neutral role definitions for each stage agent. +- `methodology/` - Working Backwards reference material. +- `rubrics/` - Critic rubrics used by every runtime. +- `templates/` - output and session templates. + +## Rule + +If a behavior affects the product process, define it here first. Runtime-specific adapters may explain how to execute the behavior in Claude Code or Codex, but they should not invent different stage semantics. From 4c56cb349a55ba54390ae669c3a567b7012bdee0 Mon Sep 17 00:00:00 2001 From: Brian McManus Date: Sat, 9 May 2026 16:59:44 -0700 Subject: [PATCH 03/27] Add shared pipeline spec --- shared/pipeline.json | 96 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 96 insertions(+) create mode 100644 shared/pipeline.json diff --git a/shared/pipeline.json b/shared/pipeline.json new file mode 100644 index 0000000..bddeada --- /dev/null +++ b/shared/pipeline.json @@ -0,0 +1,96 @@ +{ + "version": "0.1.0", + "name": "working-backwards-pipeline", + "description": "Runtime-neutral Working Backwards pipeline for AI-Product-Team.", + "max_revisions_per_stage": 3, + "persistence": { + "default": "local", + "optional": ["github"], + "session_root": "working-backwards/{session_id}" + }, + "gate_rule": { + "type": "critic-pass-required", + "description": "A stage cannot advance until the Critic returns VERDICT: PASS, except when max revisions are reached and the session pauses for more evidence." + }, + "stages": [ + { + "id": "press-release", + "label": "Press Release", + "agent": "press-release-writer", + "critic_rubric": "stage-1-press-release.json", + "artifact": "press-release.md", + "publishes_to_site": true + }, + { + "id": "faq-external", + "label": "External FAQ", + "agent": "faq-writer", + "agent_mode": "external", + "critic_rubric": "stage-2-external-faq.json", + "artifact": "faq-external.md", + "publishes_to_site": true + }, + { + "id": "faq-internal", + "label": "Internal FAQ", + "agent": "faq-writer", + "agent_mode": "internal", + "critic_rubric": "stage-2-internal-faq.json", + "artifact": "faq-internal.md", + "publishes_to_site": true + }, + { + "id": "demo", + "label": "Visual Demo", + "agent": "demo-builder", + "critic_rubric": "stage-3-demo.json", + "artifact": "demo/", + "publishes_to_site": true + }, + { + "id": "docs", + "label": "Documentation", + "agent": "docs-writer", + "critic_rubric": "stage-4-docs.json", + "artifact": "docs/", + "publishes_to_site": true + }, + { + "id": "telemetry", + "label": "Telemetry", + "agent": "telemetry-writer", + "critic_rubric": "stage-5-telemetry.json", + "artifact": "telemetry.md", + "publishes_to_site": false + }, + { + "id": "requirements", + "label": "Requirements", + "agent": "requirements-writer", + "critic_rubric": "stage-5-requirements.json", + "artifact": "requirements.md", + "publishes_to_site": false + } + ], + "required_session_artifacts": [ + "session.json", + "press-release.md", + "faq-external.md", + "faq-internal.md", + "demo/", + "docs/", + "telemetry.md", + "requirements.md", + "site/" + ], + "supported_runtimes": [ + { + "id": "claude-code", + "adapter_root": ".claude" + }, + { + "id": "codex", + "adapter_root": ".codex" + } + ] +} From 298c3484e3b6041dd0f4011ad6dfe1f82ebb1529 Mon Sep 17 00:00:00 2001 From: Brian McManus Date: Sat, 9 May 2026 17:00:51 -0700 Subject: [PATCH 04/27] Add Codex operating guide --- AGENTS.md | 46 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 46 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..fb32034 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,46 @@ +# Codex Guide for AI-Product-Team + +This repo defines a Working Backwards product pipeline that can run in Claude Code and Codex. + +Codex should treat `shared/` as the product source of truth and `.codex/` as the Codex adapter. The existing `.claude/` directory remains the Claude Code adapter. + +## Working Directory + +When working locally, use: + +```text +code/AI-Product-Team +``` + +## Core Rule + +Do not skip stages. The pipeline order is: + +1. Press Release +2. External FAQ +3. Internal FAQ +4. Visual Demo +5. Documentation +6. Telemetry +7. Requirements + +A stage advances only after Critic PASS, subject to the max-revision pause behavior documented in `shared/pipeline.json` and the runtime adapter instructions. + +## Codex Responsibilities + +When running the pipeline in Codex: + +- Read `shared/pipeline.json` first. +- Use the existing session layout under `working-backwards/{session-id}/`. +- Preserve compatibility with Claude-generated sessions. +- Write artifacts to disk before reporting completion. +- For demo and site work, run available local checks when shell access and dependencies permit. +- Do not silently resolve `[OPEN]` or `[BLOCKER]` items. + +## Adapter Boundary + +Codex-specific workflow instructions belong under `.codex/`. + +Product behavior, stage definitions, rubrics, templates, and methodology belong under `shared/`. + +If the same behavior is described in both places, prefer `shared/` unless the difference is explicitly about Codex tooling. From 9431c66960b93cc40b497f62f93daec53c27d7a7 Mon Sep 17 00:00:00 2001 From: Brian McManus Date: Sat, 9 May 2026 17:01:08 -0700 Subject: [PATCH 05/27] Add Codex working-backwards skill scaffold --- .codex/skills/working-backwards/SKILL.md | 52 ++++++++++++++++++++++++ 1 file changed, 52 insertions(+) create mode 100644 .codex/skills/working-backwards/SKILL.md diff --git a/.codex/skills/working-backwards/SKILL.md b/.codex/skills/working-backwards/SKILL.md new file mode 100644 index 0000000..be644ca --- /dev/null +++ b/.codex/skills/working-backwards/SKILL.md @@ -0,0 +1,52 @@ +--- +name: working-backwards +description: Start or resume a Working Backwards session in Codex using the shared AI-Product-Team pipeline. +argument-hint: "[feature idea] [--repo org/repo] | resume [session-id]" +--- + +# Codex Working Backwards Orchestrator + +Use this skill to run the AI-Product-Team Working Backwards pipeline in Codex. + +## Source of Truth + +Before acting, read: + +1. `shared/pipeline.json` +2. `shared/README.md` +3. Existing session state, if resuming + +The `.claude/` directory is useful reference material, but Codex behavior should be grounded in `shared/` so both runtimes remain compatible. + +## New Session + +1. Parse the feature idea and optional `--repo org/repo` flag. +2. Create a session ID: `wb-YYYYMMDD-HHMMSS`. +3. Create `working-backwards/{session-id}/session.json` using the shared pipeline stages. +4. Start at `press-release`. +5. Save artifacts locally by default. If GitHub persistence is requested, commit and push after each Critic PASS. + +## Resume Session + +1. Read `working-backwards/{session-id}/session.json`. +2. Resume from `current_stage`. +3. Preserve artifacts already marked complete. +4. Do not restart earlier stages unless the user explicitly asks. + +## Stage Execution + +For each stage: + +1. Read all prerequisite artifacts. +2. Produce or revise only the current stage artifact. +3. Run the Critic against the stage rubric. +4. If PASS, update `session.json` and advance. +5. If NEEDS REVISION, revise only failing dimensions. +6. After 3 failed revision cycles, save the best draft and pause for more evidence. + +## Codex Notes + +- Use file edits directly for generated artifacts. +- For Visual Demo and Site Builder stages, prefer runnable React/Vite/Express output consistent with the existing Claude adapter. +- Run local verification when available. +- Keep Claude compatibility: session schema and artifact paths must remain the same. From b2755c6cd200195e1d5b7bc067f44f2795eccf1c Mon Sep 17 00:00:00 2001 From: Brian McManus Date: Sat, 9 May 2026 17:03:17 -0700 Subject: [PATCH 06/27] Add Codex wb-status skill scaffold --- .codex/skills/wb-status/SKILL.md | 28 ++++++++++++++++++++++++++++ 1 file changed, 28 insertions(+) create mode 100644 .codex/skills/wb-status/SKILL.md diff --git a/.codex/skills/wb-status/SKILL.md b/.codex/skills/wb-status/SKILL.md new file mode 100644 index 0000000..182d1f7 --- /dev/null +++ b/.codex/skills/wb-status/SKILL.md @@ -0,0 +1,28 @@ +--- +name: wb-status +description: Display the current state of a Working Backwards session in Codex. Read-only. +argument-hint: "[session-id]" +--- + +# Codex Working Backwards Status + +This skill is read-only. It must not modify session files. + +## Steps + +1. Resolve the session ID from arguments. If omitted, inspect `working-backwards/` and choose automatically only when exactly one session exists. +2. Read `working-backwards/{session-id}/session.json`. +3. Display: + - session ID + - feature idea + - created and updated timestamps + - current stage + - each stage status, critic verdict, and revision count + - present and missing artifacts +4. Suggest the next command: + - resume if in progress + - review package if complete + +## Compatibility + +Use the stage list from `shared/pipeline.json` so Codex and Claude status output do not drift. From b1b8e26c32fbe20ece9a991ee906bec1c23db62c Mon Sep 17 00:00:00 2001 From: Brian McManus Date: Sat, 9 May 2026 17:03:23 -0700 Subject: [PATCH 07/27] Add dual-runtime roadmap --- ROADMAP.md | 85 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 85 insertions(+) create mode 100644 ROADMAP.md diff --git a/ROADMAP.md b/ROADMAP.md new file mode 100644 index 0000000..bcce8df --- /dev/null +++ b/ROADMAP.md @@ -0,0 +1,85 @@ +# Roadmap + +This roadmap focuses on making AI-Product-Team a dual-runtime Working Backwards product for Claude Code and Codex. + +## Now: Dual-Runtime Foundation + +### 1. Shared Core + +Create a runtime-neutral source of truth for the Working Backwards pipeline. + +Deliverables: + +- `shared/pipeline.json` +- `shared/README.md` +- Shared locations for methodology, rubrics, templates, and agent roles +- Compatibility contract for session artifacts + +### 2. Codex Adapter + +Add Codex-native instructions that can run the same pipeline without depending on Claude Code conventions. + +Deliverables: + +- `AGENTS.md` +- `.codex/skills/working-backwards/SKILL.md` +- `.codex/skills/wb-status/SKILL.md` + +### 3. Claude Adapter Preservation + +Keep the existing Claude Code extension working while reducing duplication over time. + +Deliverables: + +- Existing `.claude/` behavior remains intact +- Future refactor plan for pointing `.claude/` files at `shared/` + +## Next: Product Truth Refresh + +The README reflects the current pipeline better than the PRD in several places. Refresh the PRD so it describes the current 6-stage flow plus dual-runtime strategy. + +Deliverables: + +- Updated `prd-pm-ai-team.md` +- Resolved/obsolete open questions marked clearly +- New feature backlog captured in the PRD + +## Next: Session Index + +Add a local session index so PMs can inspect all sessions without remembering IDs. + +Deliverables: + +- `working-backwards/index.md` generation guidance +- Session status table +- Links to artifacts, demo, docs, and site + +## Later: Evidence Locker + +Add a durable place for research inputs that agents and the Critic can cite. + +Deliverables: + +- `evidence.md` or `evidence/` folder per session +- Evidence citation conventions +- Critic guidance for unsupported claims + +## Later: Per-Team Rubric Customization + +Allow teams to extend base rubrics without forking the methodology. + +Deliverables: + +- Team override file format +- Rubric version logging +- Merge rules for base and team-specific dimensions + +## Later: Exporters + +Add selected output integrations after the core pipeline is portable. + +Candidate targets: + +- Linear issues from requirements +- Notion page export +- Confluence-ready documentation From 1251837684399848cbf5ce4c7ca21aa9182d4614 Mon Sep 17 00:00:00 2001 From: Brian McManus Date: Sat, 9 May 2026 17:03:40 -0700 Subject: [PATCH 08/27] Add Codex adapter README --- .codex/README.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) create mode 100644 .codex/README.md diff --git a/.codex/README.md b/.codex/README.md new file mode 100644 index 0000000..8489059 --- /dev/null +++ b/.codex/README.md @@ -0,0 +1,14 @@ +# Codex Adapter + +This directory contains Codex-specific workflow instructions for AI-Product-Team. + +Codex should use the shared pipeline definition in `../shared/pipeline.json` and produce the same session artifacts as the Claude Code adapter. + +## Skills + +- `skills/working-backwards/SKILL.md` - start or resume a session +- `skills/wb-status/SKILL.md` - inspect session status without changing files + +## Status + +This adapter is currently scaffolded. The next implementation step is to move shared methodology, rubrics, templates, and role definitions into `shared/`, then update both Claude and Codex adapters to reference them. From ed85194a628af8ed584c93d534dc94495124fee2 Mon Sep 17 00:00:00 2001 From: Brian McManus Date: Sat, 9 May 2026 17:05:11 -0700 Subject: [PATCH 09/27] Add shared methodology reference --- shared/methodology/working-backwards.md | 70 +++++++++++++++++++++++++ 1 file changed, 70 insertions(+) create mode 100644 shared/methodology/working-backwards.md diff --git a/shared/methodology/working-backwards.md b/shared/methodology/working-backwards.md new file mode 100644 index 0000000..c68efda --- /dev/null +++ b/shared/methodology/working-backwards.md @@ -0,0 +1,70 @@ +# Working Backwards Methodology + +Working Backwards is a product development discipline: start from the customer experience and work backwards to the technology. The Press Release and FAQ are written before implementation requirements. + +The AI-Product-Team pipeline is intentionally stage-gated. Each stage must pass Critic review before the next stage unlocks. + +## Pipeline + +1. Press Release +2. External FAQ +3. Internal FAQ +4. Visual Demo +5. Documentation +6. Telemetry +7. Requirements + +## Stage 1: Press Release + +Written as if the product has already shipped. It forces the team to describe the product from the customer's perspective. + +Required sections: + +- Headline: one sentence with product name and specific customer benefit. +- Subheading: who the customer is and what they can now do. +- Problem paragraph: specific, evidenced pain. +- Solution paragraph: what the product does in plain language. +- Spokesperson quote: why this matters, not generic launch copy. +- Getting started: how a customer begins using it. +- Customer quote: specific and believable, marked as placeholder when not validated. + +## Stage 2: External FAQ + +The hardest questions a skeptical target customer would ask. Questions should focus on adoption blockers such as data/privacy, cost, workflow change, failure modes, and alternatives. + +Every question must be answered or marked `[OPEN - owner: X]`. + +## Stage 2: Internal FAQ + +The hardest questions from engineering, legal, finance, leadership, and go-to-market stakeholders. + +Open items that prevent a safe build must be marked `[BLOCKER - owner: X]`. + +## Stage 3: Visual Demo + +A working React + Express app that demonstrates the core user journey from the validated Press Release and FAQs. The demo should make the customer, problem, core action, and outcome visible. + +## Stage 4: Documentation + +Documentation written as if the product already ships. The format should match the product type: user guide, API/developer docs, admin/ops guide, or a combination. + +## Stage 5: Telemetry + +A measurement and instrumentation spec that defines how the product's success will be validated in production. It must cover adoption, non-adoption, time-to-value, and customer delight. + +## Stage 6: Requirements + +Engineer-ready requirements derived from the validated prior artifacts. Requirements must include testable acceptance criteria and must surface every relevant `[OPEN]` and `[BLOCKER]` item. + +## Open Item Handling + +Unresolved questions are marked `[OPEN - owner: X]`. They do not disappear. They must be carried forward and surfaced in downstream artifacts. + +A `[BLOCKER - owner: X]` is an open item that prevents the build from proceeding safely until resolved. + +## What This Is Not + +- Not a feature wishlist. +- Not a generic AI writing assistant. +- Not a template exercise. +- Not a process where stages can be skipped. From 81096690a7e07891c35d9440ef92f0bbace41048 Mon Sep 17 00:00:00 2001 From: Brian McManus Date: Sat, 9 May 2026 17:05:21 -0700 Subject: [PATCH 10/27] Add shared stage 1 rubric --- shared/rubrics/stage-1-press-release.json | 36 +++++++++++++++++++++++ 1 file changed, 36 insertions(+) create mode 100644 shared/rubrics/stage-1-press-release.json diff --git a/shared/rubrics/stage-1-press-release.json b/shared/rubrics/stage-1-press-release.json new file mode 100644 index 0000000..cef03fc --- /dev/null +++ b/shared/rubrics/stage-1-press-release.json @@ -0,0 +1,36 @@ +{ + "version": "1.0.0", + "stage": "press-release", + "dimensions": [ + { + "id": "customer-definition", + "name": "Customer Definition", + "pass_criteria": "A specific named persona, role, segment, or job title is identified. The reader knows exactly who has this problem.", + "fail_criteria": "Customer is vague: users, teams, enterprises, people, or customers without further specification. A new team member could not describe the customer after reading this." + }, + { + "id": "problem-evidence", + "name": "Problem Evidence", + "pass_criteria": "The problem is specific and evidenced with a concrete pain, a current workaround, a frequency, a cost, or a quote. The reader understands why this matters now.", + "fail_criteria": "The problem is generic without specifics. There is no evidence that this is a real, acute pain." + }, + { + "id": "customer-benefit", + "name": "Customer Benefit", + "pass_criteria": "The customer knows exactly what they get. The benefit is concrete, specific, and directly tied to the problem stated. The headline and solution paragraph agree.", + "fail_criteria": "The benefit is vague without saying what specifically changes for the customer." + }, + { + "id": "spokesperson-quote", + "name": "Spokesperson Quote", + "pass_criteria": "The quote explains why this product matters: the insight, the mission, or the opportunity. It says something a real person would say.", + "fail_criteria": "The quote is generic marketing language that could be copied onto any product announcement." + }, + { + "id": "customer-quote", + "name": "Customer Quote", + "pass_criteria": "The quote is specific and believable. It describes a real outcome or reaction in the customer's voice. Placeholder language is explicitly marked as [placeholder - replace with real customer quote].", + "fail_criteria": "The quote invents specific metrics or outcomes not grounded in PM-provided context without marking them as placeholders, or the quote is generic praise." + } + ] +} From 930cfd3d259dad499f8d1f858d9a5e88e498f39e Mon Sep 17 00:00:00 2001 From: Brian McManus Date: Sat, 9 May 2026 17:05:25 -0700 Subject: [PATCH 11/27] Add shared external FAQ rubric --- shared/rubrics/stage-2-external-faq.json | 30 ++++++++++++++++++++++++ 1 file changed, 30 insertions(+) create mode 100644 shared/rubrics/stage-2-external-faq.json diff --git a/shared/rubrics/stage-2-external-faq.json b/shared/rubrics/stage-2-external-faq.json new file mode 100644 index 0000000..e4f91ac --- /dev/null +++ b/shared/rubrics/stage-2-external-faq.json @@ -0,0 +1,30 @@ +{ + "version": "1.0.0", + "stage": "faq-external", + "dimensions": [ + { + "id": "question-quality", + "name": "Question Quality", + "pass_criteria": "Every question represents a genuine challenge a skeptical customer would raise about risk, cost, workflow change, data, competition, or failure modes.", + "fail_criteria": "Questions are softballs or leading questions that assume a positive answer. The set feels like a marketing FAQ rather than skeptical customer scrutiny." + }, + { + "id": "answer-completeness", + "name": "Answer Completeness", + "pass_criteria": "Every question has either a substantive answer or is explicitly marked [OPEN - owner: X] with a named owner.", + "fail_criteria": "One or more questions have no answer, are not marked [OPEN], or are marked open without a named owner." + }, + { + "id": "evasion", + "name": "No Evasive Answers", + "pass_criteria": "Each answer directly resolves the question asked. Genuine uncertainty is marked [OPEN] rather than dressed up as an answer.", + "fail_criteria": "One or more answers restate the question, deflect to vague future plans, or use marketing language to avoid a hard truth." + }, + { + "id": "coverage", + "name": "Coverage of Critical Concerns", + "pass_criteria": "The FAQ covers customer concerns most likely to block adoption: data/privacy, workflow change, cost/value, failure modes, and differentiation from alternatives.", + "fail_criteria": "The FAQ is missing one or more critical concern categories that a reasonable customer in the target segment would raise." + } + ] +} From 1f207ec318a7985c4a63a0e4867486a5daddaf00 Mon Sep 17 00:00:00 2001 From: Brian McManus Date: Sat, 9 May 2026 17:05:27 -0700 Subject: [PATCH 12/27] Add shared internal FAQ rubric --- shared/rubrics/stage-2-internal-faq.json | 30 ++++++++++++++++++++++++ 1 file changed, 30 insertions(+) create mode 100644 shared/rubrics/stage-2-internal-faq.json diff --git a/shared/rubrics/stage-2-internal-faq.json b/shared/rubrics/stage-2-internal-faq.json new file mode 100644 index 0000000..8c4594c --- /dev/null +++ b/shared/rubrics/stage-2-internal-faq.json @@ -0,0 +1,30 @@ +{ + "version": "1.0.0", + "stage": "faq-internal", + "dimensions": [ + { + "id": "coverage", + "name": "Stakeholder Coverage", + "pass_criteria": "The FAQ includes hard questions from at least three stakeholder perspectives: engineering, business/leadership, and legal/compliance when applicable.", + "fail_criteria": "One or more stakeholder perspectives are absent or represented only by softball questions." + }, + { + "id": "answer-completeness", + "name": "Answer Completeness", + "pass_criteria": "Every question has either a substantive answer or is explicitly marked [OPEN - owner: X] with a named owner.", + "fail_criteria": "One or more questions are unanswered without [OPEN] marking, or open items have no named owner." + }, + { + "id": "blocker-flagging", + "name": "Blocker Identification", + "pass_criteria": "Any open item that would prevent the build from proceeding is flagged as [BLOCKER - owner: X].", + "fail_criteria": "Build-blocking issues are buried in [OPEN] items without distinction or are not surfaced." + }, + { + "id": "evasion", + "name": "No Evasive Answers", + "pass_criteria": "Answers to hard questions are direct. Unknowns are marked [OPEN] rather than obscured with confident-sounding language.", + "fail_criteria": "Hard questions receive vague, aspirational, or deflecting answers rather than honest responses or [OPEN] flags." + } + ] +} From 125fe202f473f8cefec0aca7db2ebeaa52e48aa7 Mon Sep 17 00:00:00 2001 From: Brian McManus Date: Sat, 9 May 2026 17:05:29 -0700 Subject: [PATCH 13/27] Add shared demo rubric --- shared/rubrics/stage-3-demo.json | 30 ++++++++++++++++++++++++++++++ 1 file changed, 30 insertions(+) create mode 100644 shared/rubrics/stage-3-demo.json diff --git a/shared/rubrics/stage-3-demo.json b/shared/rubrics/stage-3-demo.json new file mode 100644 index 0000000..6ee34d3 --- /dev/null +++ b/shared/rubrics/stage-3-demo.json @@ -0,0 +1,30 @@ +{ + "version": "1.0.0", + "stage": "demo", + "dimensions": [ + { + "id": "pr-traceability", + "name": "Press Release Traceability", + "pass_criteria": "A stakeholder who has read the Press Release can use the demo and immediately recognize the product. The core customer, problem, and solution are visible in the app.", + "fail_criteria": "The demo looks generic. The specific customer persona, problem, or benefit from the Press Release is not evident." + }, + { + "id": "user-journey-coverage", + "name": "Core User Journey Coverage", + "pass_criteria": "The demo implements the primary user journey end-to-end: entry point, core action, and outcome.", + "fail_criteria": "The demo shows isolated screens or stops before the user reaches the outcome described in the Press Release." + }, + { + "id": "runnability", + "name": "Structural Runnability", + "pass_criteria": "All imported components, modules, and files exist. npm dependencies are real packages. Vite config and package scripts are syntactically correct.", + "fail_criteria": "Imports reference missing files, dependencies are fabricated or misspelled, scripts are malformed, or syntax errors would prevent loading." + }, + { + "id": "mock-data-honesty", + "name": "Mock Data Honesty", + "pass_criteria": "All data shown is clearly mock data or labelled as demo data. The demo does not imply real backend integration it does not have.", + "fail_criteria": "Mock data is presented in a way that could mislead stakeholders about what is actually built." + } + ] +} From 78ca43dbfbba669d34a0052de1d0a2e958cbf1b9 Mon Sep 17 00:00:00 2001 From: Brian McManus Date: Sat, 9 May 2026 17:07:06 -0700 Subject: [PATCH 14/27] Add shared docs rubric --- shared/rubrics/stage-4-docs.json | 36 ++++++++++++++++++++++++++++++++ 1 file changed, 36 insertions(+) create mode 100644 shared/rubrics/stage-4-docs.json diff --git a/shared/rubrics/stage-4-docs.json b/shared/rubrics/stage-4-docs.json new file mode 100644 index 0000000..9b4497c --- /dev/null +++ b/shared/rubrics/stage-4-docs.json @@ -0,0 +1,36 @@ +{ + "version": "1.1.0", + "stage": "docs", + "dimensions": [ + { + "id": "audience-journey-completeness", + "name": "Audience Journey Completeness", + "pass_criteria": "The documentation covers the primary user's complete journey from first access through core use to any required go-live or production steps.", + "fail_criteria": "One or more major stages of the user's journey are missing or too thin to be actionable." + }, + { + "id": "technical-internal-consistency", + "name": "Technical Internal Consistency", + "pass_criteria": "Any term, field name, endpoint, setting, or concept that appears in multiple documentation files uses identical naming throughout.", + "fail_criteria": "One or more terms, field names, or concepts are named differently across files." + }, + { + "id": "format-fit", + "name": "Format Fit for Product Type", + "pass_criteria": "The documentation format matches the product type: developer portal docs for APIs, task-oriented guides for user apps, setup and operations guides for admin/ops tools.", + "fail_criteria": "The documentation format is mismatched to the product or feels like a generic template." + }, + { + "id": "product-specificity", + "name": "Product Specificity", + "pass_criteria": "The documentation is written specifically for this product. Product name, capabilities, persona, and workflows from the Press Release are reflected.", + "fail_criteria": "The documentation is generic or could apply to any product of its type." + }, + { + "id": "pr-faq-grounding", + "name": "Press Release and FAQ Grounding", + "pass_criteria": "Every capability documented traces to the Press Release or FAQ. Open items that affect documentation are explicitly marked [TBD - pre-launch].", + "fail_criteria": "The docs describe capabilities not established in the PR or FAQ, contradict the PR, or silently resolve Internal FAQ open items." + } + ] +} From 22228d2cc1970fcdfc4741ab1a160e044df1f97d Mon Sep 17 00:00:00 2001 From: Brian McManus Date: Sat, 9 May 2026 17:07:09 -0700 Subject: [PATCH 15/27] Add shared telemetry rubric --- shared/rubrics/stage-5-telemetry.json | 36 +++++++++++++++++++++++++++ 1 file changed, 36 insertions(+) create mode 100644 shared/rubrics/stage-5-telemetry.json diff --git a/shared/rubrics/stage-5-telemetry.json b/shared/rubrics/stage-5-telemetry.json new file mode 100644 index 0000000..3832ec6 --- /dev/null +++ b/shared/rubrics/stage-5-telemetry.json @@ -0,0 +1,36 @@ +{ + "version": "1.0.0", + "stage": "telemetry", + "dimensions": [ + { + "id": "outcome-coverage", + "name": "Outcome Coverage", + "pass_criteria": "Every success criterion stated or implied in the Press Release has at least one metric that will validate it. The north star metric is clearly defined and linked to the core customer benefit.", + "fail_criteria": "One or more Press Release success criteria have no corresponding metric, or the north star metric is absent or generic." + }, + { + "id": "adoption-and-non-adoption", + "name": "Adoption and Non-Adoption Coverage", + "pass_criteria": "The spec addresses both who is using the product and who is not and why. Non-adoption metrics identify specific drop-off points with investigation triggers.", + "fail_criteria": "The spec covers adoption but treats non-adoption as a residual with no drop-off points or investigation triggers." + }, + { + "id": "time-to-value", + "name": "Time-to-Value Measurement", + "pass_criteria": "The spec defines a specific, observable activation event derived from the documented user journey, with a concrete event sequence.", + "fail_criteria": "The activation event is absent, vague, unmeasurable, or only described conceptually." + }, + { + "id": "customer-delight", + "name": "Customer Delight Measurement", + "pass_criteria": "The spec includes at least one satisfaction signal with a specific trigger condition, plus retention or return-rate definition.", + "fail_criteria": "Customer delight is absent or addressed only with a vague placeholder, and retention is not addressed." + }, + { + "id": "practical-implementability", + "name": "Practical Implementability", + "pass_criteria": "Every metric has a concrete measurement mechanism. The spec includes an Instrumentation Requirements section listing events that must be built.", + "fail_criteria": "Metrics are aspirational with no implementation path, events are unnamed, or instrumentation requirements are absent." + } + ] +} From fb3dceb02717a327015500345b52a92f89b95aba Mon Sep 17 00:00:00 2001 From: Brian McManus Date: Sat, 9 May 2026 17:07:11 -0700 Subject: [PATCH 16/27] Add shared requirements rubric --- shared/rubrics/stage-5-requirements.json | 36 ++++++++++++++++++++++++ 1 file changed, 36 insertions(+) create mode 100644 shared/rubrics/stage-5-requirements.json diff --git a/shared/rubrics/stage-5-requirements.json b/shared/rubrics/stage-5-requirements.json new file mode 100644 index 0000000..8a2c761 --- /dev/null +++ b/shared/rubrics/stage-5-requirements.json @@ -0,0 +1,36 @@ +{ + "version": "1.0.0", + "stage": "requirements", + "dimensions": [ + { + "id": "requirement-traceability", + "name": "Requirement Traceability", + "pass_criteria": "Every functional requirement traces to a specific capability, customer need, or constraint established in the Press Release, External FAQ, or Internal FAQ.", + "fail_criteria": "One or more requirements cannot be traced to prior artifacts or contradict them." + }, + { + "id": "testable-acceptance-criteria", + "name": "Testable Acceptance Criteria", + "pass_criteria": "Every requirement has at least one acceptance criterion in given/when/then format with an observable outcome.", + "fail_criteria": "Requirements lack acceptance criteria, criteria are not in given/when/then format, or criteria are vague or untestable." + }, + { + "id": "edge-case-coverage", + "name": "Edge Case Coverage", + "pass_criteria": "The requirements address failure modes, empty states, boundary conditions, and relevant error scenarios.", + "fail_criteria": "The requirements cover only the happy path and omit relevant edge cases." + }, + { + "id": "nonfunctional-requirements", + "name": "Non-Functional Requirements", + "pass_criteria": "Performance, security, scale, and compliance requirements are present or explicitly marked [OPEN - not established in Internal FAQ].", + "fail_criteria": "Non-functional requirements are missing or too vague to design against." + }, + { + "id": "open-item-propagation", + "name": "Open Item Propagation", + "pass_criteria": "Every relevant [OPEN] and [BLOCKER] item from the External and Internal FAQs is surfaced explicitly in requirements.", + "fail_criteria": "Open or blocker items are absent or silently resolved with invented assumptions." + } + ] +} From e253403064149276c1225d309e6c5151adac4aff Mon Sep 17 00:00:00 2001 From: Brian McManus Date: Sat, 9 May 2026 17:07:13 -0700 Subject: [PATCH 17/27] Add shared rubrics index --- shared/rubrics/README.md | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) create mode 100644 shared/rubrics/README.md diff --git a/shared/rubrics/README.md b/shared/rubrics/README.md new file mode 100644 index 0000000..91586fb --- /dev/null +++ b/shared/rubrics/README.md @@ -0,0 +1,19 @@ +# Shared Critic Rubrics + +These rubrics are the runtime-neutral Critic standards for AI-Product-Team. + +Claude Code and Codex adapters should use these files as the source of truth for stage evaluation. + +## Files + +- `stage-1-press-release.json` +- `stage-2-external-faq.json` +- `stage-2-internal-faq.json` +- `stage-3-demo.json` +- `stage-4-docs.json` +- `stage-5-telemetry.json` +- `stage-5-requirements.json` + +## Compatibility Note + +The existing Claude adapter currently keeps equivalent rubrics under `.claude/rubrics/`. During migration, changes should be made in `shared/rubrics/` first, then synchronized to runtime adapters until adapters read shared files directly. From 8f15ddd77e446cadf1cf904aabc65d57048b4892 Mon Sep 17 00:00:00 2001 From: Brian McManus Date: Sat, 9 May 2026 17:08:02 -0700 Subject: [PATCH 18/27] Document shared core and runtime adapters --- CLAUDE.md | 78 +++++++++++++++++++++++++++++++++---------------------- 1 file changed, 47 insertions(+), 31 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 2ea097f..b7da9b3 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,25 +1,41 @@ # AI-Product-Team -This repository is a Claude Code extension that guides product managers through Amazon's Working Backwards methodology using a multi-agent pipeline. +This repository is a Working Backwards product pipeline that can run through runtime-specific adapters. + +- `shared/` contains the runtime-neutral product definition: pipeline, methodology, rubrics, templates, and compatibility contract. +- `.claude/` contains the Claude Code adapter. +- `.codex/` contains the Codex adapter scaffold. + +The current Claude Code extension guides product managers through Amazon's Working Backwards methodology using a multi-agent pipeline. ## What this does Running `/working-backwards` starts a strict, stage-gated pipeline: -1. **Stage 1 — Press Release**: Write a customer-centric Press Release before any requirements -2. **Stage 2 — External FAQ**: Stress-test the PR with hard customer questions -3. **Stage 2 — Internal FAQ**: Stress-test with hard engineering/leadership questions -4. **Stage 3 — Visual Demo**: Build a working React + Express prototype of the core user journey -5. **Stage 4 — Documentation**: Write user-facing documentation as if the product ships today -6. **Stage 5 — Telemetry**: Define measurement and instrumentation specs -7. **Stage 6 — Requirements**: Translate the validated artifacts into engineer-ready specs +1. **Stage 1 - Press Release**: Write a customer-centric Press Release before any requirements +2. **Stage 2 - External FAQ**: Stress-test the PR with hard customer questions +3. **Stage 2 - Internal FAQ**: Stress-test with hard engineering/leadership questions +4. **Stage 3 - Visual Demo**: Build a working React + Express prototype of the core user journey +5. **Stage 4 - Documentation**: Write user-facing documentation as if the product ships today +6. **Stage 5 - Telemetry**: Define measurement and instrumentation specs +7. **Stage 6 - Requirements**: Translate the validated artifacts into engineer-ready specs Each stage must pass a Critic review before the next stage unlocks. No skipping. -After each Critic PASS for Stages 1–4, the validated content is automatically published to a marketing-ready website (`site/`) that builds progressively as the pipeline advances. +After each Critic PASS for Stages 1-4, the validated content is automatically published to a marketing-ready website (`site/`) that builds progressively as the pipeline advances. All session outputs are committed to this repo under `working-backwards/{session-id}/`. +## Runtime Adapters + +### Claude Code + +Claude Code uses the existing `.claude/agents/` and `.claude/skills/` files. These remain supported. + +### Codex + +Codex uses `AGENTS.md` plus `.codex/skills/`. Codex should read `shared/pipeline.json` before running or resuming a session and should preserve the same session layout used by Claude. + ## Prerequisites - `gh` CLI installed and authenticated: `brew install gh && gh auth login` @@ -27,37 +43,37 @@ All session outputs are committed to this repo under `working-backwards/{session ## Available commands -- `/working-backwards [feature idea]` — Start a new Working Backwards session -- `/working-backwards resume [session-id]` — Resume an in-progress session -- `/wb-status [session-id]` — View current session state (read-only) +- `/working-backwards [feature idea]` - Start a new Working Backwards session +- `/working-backwards resume [session-id]` - Resume an in-progress session +- `/wb-status [session-id]` - View current session state (read-only) ## Session output structure -``` +```text working-backwards/ {session-id}/ - press-release.md ← Stage 1 Critic PASS - faq-external.md ← Stage 2 External Critic PASS - faq-internal.md ← Stage 2 Internal Critic PASS - demo/ ← Stage 3 Critic PASS (npm install && npm start → localhost:3000) - docs/ ← Stage 4 Critic PASS - telemetry.md ← Stage 5 Critic PASS - requirements.md ← Stage 6 Critic PASS - site/ ← built at Stage 1, updated through Stage 4 (npm install && npm run dev → localhost:5173) - session.json ← updated after every agent interaction + press-release.md <- Stage 1 Critic PASS + faq-external.md <- Stage 2 External Critic PASS + faq-internal.md <- Stage 2 Internal Critic PASS + demo/ <- Stage 3 Critic PASS (npm install && npm start -> localhost:3000) + docs/ <- Stage 4 Critic PASS + telemetry.md <- Stage 5 Critic PASS + requirements.md <- Stage 6 Critic PASS + site/ <- built at Stage 1, updated through Stage 4 (npm install && npm run dev -> localhost:5173) + session.json <- updated after every agent interaction ``` ## Agents -- `press-release-writer` — Stage 1 worker -- `faq-writer` — Stage 2 worker (External and Internal modes) -- `demo-builder` — Stage 3 worker -- `docs-writer` — Stage 4 worker -- `telemetry-writer` — Stage 5 worker -- `requirements-writer` — Stage 6 worker -- `critic` — Reviews all stage outputs against versioned rubrics -- `site-builder` — Publishes validated artifacts to a marketing-ready website after each Stage 1–4 Critic PASS +- `press-release-writer` - Stage 1 worker +- `faq-writer` - Stage 2 worker (External and Internal modes) +- `demo-builder` - Stage 3 worker +- `docs-writer` - Stage 4 worker +- `telemetry-writer` - Stage 5 worker +- `requirements-writer` - Stage 6 worker +- `critic` - Reviews all stage outputs against versioned rubrics +- `site-builder` - Publishes validated artifacts to a marketing-ready website after each Stage 1-4 Critic PASS ## Rubrics -Stage-specific Critic rubrics live in `.claude/rubrics/`. They are versioned JSON files — update them without redeploying any agent. +Runtime-neutral Critic rubrics live in `shared/rubrics/`. The current Claude adapter also contains `.claude/rubrics/` for compatibility. During migration, update `shared/rubrics/` first and keep adapter copies synchronized until adapters read shared files directly. From 6ef8be84c392b143643dc5dbe496fb0c87b85f9e Mon Sep 17 00:00:00 2001 From: Brian McManus Date: Sat, 9 May 2026 17:11:47 -0700 Subject: [PATCH 19/27] Working Backwards [wb-20260510-001500]: session initialized --- .../wb-20260510-001500/session.json | 63 +++++++++++++++++++ 1 file changed, 63 insertions(+) create mode 100644 working-backwards/wb-20260510-001500/session.json diff --git a/working-backwards/wb-20260510-001500/session.json b/working-backwards/wb-20260510-001500/session.json new file mode 100644 index 0000000..bbc1002 --- /dev/null +++ b/working-backwards/wb-20260510-001500/session.json @@ -0,0 +1,63 @@ +{ + "session_id": "wb-20260510-001500", + "created_at": "2026-05-10T00:15:00Z", + "updated_at": "2026-05-10T00:15:00Z", + "persistence": "github", + "repo": "brianmc/AI-Product-Team", + "runtime": "codex", + "feature_idea": "Make AI-Product-Team work in both Codex and Claude Code from one shared Working Backwards core.", + "current_stage": "press-release", + "stages": { + "press-release": { + "status": "in-progress", + "critic_verdict": null, + "revision_count": 0, + "artifact_path": "working-backwards/wb-20260510-001500/press-release.md" + }, + "faq-external": { + "status": "pending", + "critic_verdict": null, + "revision_count": 0, + "artifact_path": "working-backwards/wb-20260510-001500/faq-external.md" + }, + "faq-internal": { + "status": "pending", + "critic_verdict": null, + "revision_count": 0, + "artifact_path": "working-backwards/wb-20260510-001500/faq-internal.md" + }, + "demo": { + "status": "pending", + "critic_verdict": null, + "revision_count": 0, + "artifact_path": "working-backwards/wb-20260510-001500/demo/" + }, + "docs": { + "status": "pending", + "critic_verdict": null, + "revision_count": 0, + "artifact_path": "working-backwards/wb-20260510-001500/docs/" + }, + "telemetry": { + "status": "pending", + "critic_verdict": null, + "revision_count": 0, + "artifact_path": "working-backwards/wb-20260510-001500/telemetry.md" + }, + "requirements": { + "status": "pending", + "critic_verdict": null, + "revision_count": 0, + "artifact_path": "working-backwards/wb-20260510-001500/requirements.md" + } + }, + "invocation_log": [ + { + "runtime": "codex", + "agent": "orchestrator", + "stage": "press-release", + "event": "session_initialized", + "timestamp": "2026-05-10T00:15:00Z" + } + ] +} From c0b4466e284b7834126706564c777db84582729f Mon Sep 17 00:00:00 2001 From: Brian McManus Date: Sat, 9 May 2026 17:12:31 -0700 Subject: [PATCH 20/27] Working Backwards [wb-20260510-001500]: Stage 1 Press Release draft --- .../wb-20260510-001500/press-release.md | 15 +++++++++++++++ 1 file changed, 15 insertions(+) create mode 100644 working-backwards/wb-20260510-001500/press-release.md diff --git a/working-backwards/wb-20260510-001500/press-release.md b/working-backwards/wb-20260510-001500/press-release.md new file mode 100644 index 0000000..8b2785c --- /dev/null +++ b/working-backwards/wb-20260510-001500/press-release.md @@ -0,0 +1,15 @@ +# AI-Product-Team Shared Runtime Core Lets PM Teams Run Working Backwards in Codex or Claude Code + +**Product teams and AI-tooling owners can now run the same rigorous Working Backwards pipeline in Codex and Claude Code without maintaining two divergent prompt systems.** + +**Seattle, May 2026** - AI-Product-Team today introduced Shared Runtime Core, a portability layer that lets teams run the AI-Product-Team Working Backwards process in both Codex and Claude Code from one canonical methodology, rubric set, and session format. + +Product teams adopting AI-assisted product planning often face a quiet but expensive problem: their best process becomes trapped in one agent runtime. A team starts with Claude Code because slash commands and subagents are convenient, then another team wants Codex because it is stronger for code editing, local verification, and generated demos. Soon the same Working Backwards process exists in two places, with slightly different rubrics, stage names, templates, and handoff rules. The divergence is subtle at first, then costly: PMs get different outputs depending on which tool they use, and maintainers have to update the methodology twice. + +Shared Runtime Core solves this by separating the product process from the runtime adapter. The stage order, Critic rubrics, methodology, templates, and session compatibility contract live in a shared directory. Claude Code keeps its existing `.claude/` adapter. Codex gains a `.codex/` adapter and repo-level operating guide. Both runtimes produce the same `working-backwards/{session-id}/` package, enforce the same Critic gates, and preserve the same artifact names from Press Release through Requirements. + +"The product is not the slash command or the tool wrapper. The product is the discipline: start with the customer, ask the hard questions, prove the experience, document it, measure it, and only then write requirements," said the AI-Product-Team maintainer. "Shared Runtime Core lets teams keep that discipline intact even as they choose the AI coding environment that fits the job." + +Teams get started by opening the repo in either Claude Code or Codex. Claude users continue running `/working-backwards`. Codex users follow `AGENTS.md` and the `.codex/skills/working-backwards` adapter. In both cases, sessions are saved to the same artifact structure and can be inspected with the same status model. + +"We wanted Codex for demo generation and local verification, but our Working Backwards process already lived in Claude Code," said a product operations lead using AI-Product-Team [placeholder - replace with real customer quote]. "The shared core means we do not have to pick one tool or explain why the same product idea gets reviewed by different standards in different environments." From f825e1af8a2ff44aceb281ce0c34477a7f1724d8 Mon Sep 17 00:00:00 2001 From: Brian McManus Date: Sat, 9 May 2026 17:12:44 -0700 Subject: [PATCH 21/27] Working Backwards [wb-20260510-001500]: Stage 1 Critic PASS --- .../critic-stage-1-press-release.md | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) create mode 100644 working-backwards/wb-20260510-001500/critic-stage-1-press-release.md diff --git a/working-backwards/wb-20260510-001500/critic-stage-1-press-release.md b/working-backwards/wb-20260510-001500/critic-stage-1-press-release.md new file mode 100644 index 0000000..56b5bfe --- /dev/null +++ b/working-backwards/wb-20260510-001500/critic-stage-1-press-release.md @@ -0,0 +1,18 @@ +# Critic Review: Stage 1 Press Release + +VERDICT: PASS +RUBRIC_VERSION: 1.0.0 + +SUMMARY: The Press Release clearly identifies product teams and AI-tooling owners as the customer, names the concrete pain of divergent runtime-specific process definitions, and explains the customer benefit of a shared Working Backwards core with compatible Claude Code and Codex adapters. + +## Dimension Results + +- customer-definition: PASS +- problem-evidence: PASS +- customer-benefit: PASS +- spokesperson-quote: PASS +- customer-quote: PASS + +## Notes + +The customer quote is marked as a placeholder, which is appropriate because no validated customer quote has been provided yet. From 209bffc7a761f5dcbcb47ed45f6388ee82afb023 Mon Sep 17 00:00:00 2001 From: Brian McManus Date: Sat, 9 May 2026 17:16:13 -0700 Subject: [PATCH 22/27] Working Backwards [wb-20260510-001500]: advance to External FAQ --- .../wb-20260510-001500/session.json | 25 +++++++++++++++---- 1 file changed, 20 insertions(+), 5 deletions(-) diff --git a/working-backwards/wb-20260510-001500/session.json b/working-backwards/wb-20260510-001500/session.json index bbc1002..0526a03 100644 --- a/working-backwards/wb-20260510-001500/session.json +++ b/working-backwards/wb-20260510-001500/session.json @@ -1,21 +1,21 @@ { "session_id": "wb-20260510-001500", "created_at": "2026-05-10T00:15:00Z", - "updated_at": "2026-05-10T00:15:00Z", + "updated_at": "2026-05-10T00:22:00Z", "persistence": "github", "repo": "brianmc/AI-Product-Team", "runtime": "codex", "feature_idea": "Make AI-Product-Team work in both Codex and Claude Code from one shared Working Backwards core.", - "current_stage": "press-release", + "current_stage": "faq-external", "stages": { "press-release": { - "status": "in-progress", - "critic_verdict": null, + "status": "complete", + "critic_verdict": "PASS", "revision_count": 0, "artifact_path": "working-backwards/wb-20260510-001500/press-release.md" }, "faq-external": { - "status": "pending", + "status": "in-progress", "critic_verdict": null, "revision_count": 0, "artifact_path": "working-backwards/wb-20260510-001500/faq-external.md" @@ -58,6 +58,21 @@ "stage": "press-release", "event": "session_initialized", "timestamp": "2026-05-10T00:15:00Z" + }, + { + "runtime": "codex", + "agent": "press-release-writer", + "stage": "press-release", + "event": "artifact_created", + "timestamp": "2026-05-10T00:20:00Z" + }, + { + "runtime": "codex", + "agent": "critic", + "stage": "press-release", + "event": "critic_pass", + "rubric_version": "1.0.0", + "timestamp": "2026-05-10T00:22:00Z" } ] } From 4ce1b7291198eed2d28447f5f6b6de31e2f1eff1 Mon Sep 17 00:00:00 2001 From: Brian McManus Date: Sat, 9 May 2026 17:18:36 -0700 Subject: [PATCH 23/27] Working Backwards [wb-20260510-001500]: Stage 2 External FAQ draft --- .../wb-20260510-001500/faq-external.md | 33 +++++++++++++++++++ 1 file changed, 33 insertions(+) create mode 100644 working-backwards/wb-20260510-001500/faq-external.md diff --git a/working-backwards/wb-20260510-001500/faq-external.md b/working-backwards/wb-20260510-001500/faq-external.md new file mode 100644 index 0000000..b4b8a27 --- /dev/null +++ b/working-backwards/wb-20260510-001500/faq-external.md @@ -0,0 +1,33 @@ +# External FAQ: AI-Product-Team Shared Runtime Core + +## Q1: Why should I care whether AI-Product-Team works in both Codex and Claude Code? I only use one tool today. + +If your team truly uses only one AI coding environment and expects that to remain true, this may not matter immediately. The problem appears when process artifacts become tied to a tool rather than to the team's product discipline. If the Working Backwards methodology, rubrics, and templates live only inside one runtime's adapter, switching tools or adding a second tool means rebuilding the process or accepting drift. Shared Runtime Core protects the process from tool choice. + +## Q2: Does supporting two runtimes make the product more complicated for PMs? + +It should not. PMs should still experience one Working Backwards pipeline: Press Release, External FAQ, Internal FAQ, Visual Demo, Documentation, Telemetry, Requirements. The runtime adapter should be mostly invisible once a session starts. The added complexity is for maintainers, who now have a clearer boundary between shared product behavior and runtime-specific execution instructions. + +## Q3: Will Claude Code and Codex produce identical outputs? + +No, not word-for-word. They are different AI environments, and their writing style and tool behavior may differ. The promise is compatibility, not byte-for-byte identity: the same stage order, artifact names, Critic rubrics, gate rules, session schema, and open-item handling. A team should be able to understand and continue a session regardless of which supported runtime produced it. + +## Q4: How do I know the Codex version is not a weaker copy of the Claude version? + +Codex support should be measured against the shared compatibility contract, not against whether it copies Claude implementation details. In fact, Codex may be stronger for stages that require file editing, running local checks, generated demos, and UI verification. The key requirement is that Codex uses the same shared pipeline and rubrics, not that it mimics Claude's slash-command mechanics. + +## Q5: What happens if the shared core and a runtime adapter disagree? + +The shared core should win unless the difference is explicitly about runtime tooling. For example, stage order, rubrics, and artifact names belong to `shared/`. Tool invocation details belong to `.claude/` or `.codex/`. During the migration period, adapter copies may exist for compatibility, but changes should be made in `shared/` first and synchronized outward. + +## Q6: Does this mean teams have to migrate old Claude sessions? + +No. Existing Claude-generated sessions should remain valid because the compatibility contract preserves the same `working-backwards/{session-id}/` artifact layout. Migration work should focus on future adapters reading shared definitions, not rewriting prior session artifacts. + +## Q7: What is the main risk of this feature? + +The main risk is false portability: adding Codex files that look official but do not actually execute the same process. That would create the very drift the feature is meant to prevent. The mitigation is to define a shared pipeline spec, shared rubrics, and validation checks before treating Codex support as complete. + +## Q8: When should a team choose Codex versus Claude Code for a session? + +[OPEN - owner: product maintainer] The initial guidance is that Claude Code remains the established path, while Codex is attractive for implementation-heavy stages like Visual Demo and generated site verification. We need real usage to decide whether teams should choose one runtime for the full session or move sessions between runtimes by stage. From d8b81e8715ec3ac99267804a453af0c2e8795165 Mon Sep 17 00:00:00 2001 From: Brian McManus Date: Sat, 9 May 2026 17:22:18 -0700 Subject: [PATCH 24/27] Working Backwards [wb-20260510-001500]: External FAQ Critic PASS --- .../critic-stage-2-external-faq.md | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) create mode 100644 working-backwards/wb-20260510-001500/critic-stage-2-external-faq.md diff --git a/working-backwards/wb-20260510-001500/critic-stage-2-external-faq.md b/working-backwards/wb-20260510-001500/critic-stage-2-external-faq.md new file mode 100644 index 0000000..46ce3fd --- /dev/null +++ b/working-backwards/wb-20260510-001500/critic-stage-2-external-faq.md @@ -0,0 +1,17 @@ +# Critic Review: Stage 2 External FAQ + +VERDICT: PASS +RUBRIC_VERSION: 1.0.0 + +SUMMARY: The External FAQ addresses skeptical adoption concerns directly, including tool choice value, PM complexity, output parity, adapter disagreement, migration risk, false portability, and runtime-selection uncertainty. + +## Dimension Results + +- question-quality: PASS +- answer-completeness: PASS +- evasion: PASS +- coverage: PASS + +## Notes + +The FAQ includes one `[OPEN - owner: product maintainer]` item about when teams should choose Codex versus Claude Code. This is appropriately marked because runtime-selection guidance requires real usage evidence. From a960405bef720e943d5ecc33be7f9c8a22ccba15 Mon Sep 17 00:00:00 2001 From: Brian McManus Date: Sat, 9 May 2026 17:23:31 -0700 Subject: [PATCH 25/27] Working Backwards [wb-20260510-001500]: advance to Internal FAQ --- .../wb-20260510-001500/session.json | 25 +++++++++++++++---- 1 file changed, 20 insertions(+), 5 deletions(-) diff --git a/working-backwards/wb-20260510-001500/session.json b/working-backwards/wb-20260510-001500/session.json index 0526a03..1fb0c6b 100644 --- a/working-backwards/wb-20260510-001500/session.json +++ b/working-backwards/wb-20260510-001500/session.json @@ -1,12 +1,12 @@ { "session_id": "wb-20260510-001500", "created_at": "2026-05-10T00:15:00Z", - "updated_at": "2026-05-10T00:22:00Z", + "updated_at": "2026-05-10T00:34:00Z", "persistence": "github", "repo": "brianmc/AI-Product-Team", "runtime": "codex", "feature_idea": "Make AI-Product-Team work in both Codex and Claude Code from one shared Working Backwards core.", - "current_stage": "faq-external", + "current_stage": "faq-internal", "stages": { "press-release": { "status": "complete", @@ -15,13 +15,13 @@ "artifact_path": "working-backwards/wb-20260510-001500/press-release.md" }, "faq-external": { - "status": "in-progress", - "critic_verdict": null, + "status": "complete", + "critic_verdict": "PASS", "revision_count": 0, "artifact_path": "working-backwards/wb-20260510-001500/faq-external.md" }, "faq-internal": { - "status": "pending", + "status": "in-progress", "critic_verdict": null, "revision_count": 0, "artifact_path": "working-backwards/wb-20260510-001500/faq-internal.md" @@ -73,6 +73,21 @@ "event": "critic_pass", "rubric_version": "1.0.0", "timestamp": "2026-05-10T00:22:00Z" + }, + { + "runtime": "codex", + "agent": "faq-writer", + "stage": "faq-external", + "event": "artifact_created", + "timestamp": "2026-05-10T00:31:00Z" + }, + { + "runtime": "codex", + "agent": "critic", + "stage": "faq-external", + "event": "critic_pass", + "rubric_version": "1.0.0", + "timestamp": "2026-05-10T00:34:00Z" } ] } From 3fd407ee6e157e2d479924b498d95fe1428ddf7d Mon Sep 17 00:00:00 2001 From: Brian McManus Date: Sat, 9 May 2026 18:40:01 -0700 Subject: [PATCH 26/27] Working Backwards [wb-20260510-001500]: Stage 2 Internal FAQ draft --- .../wb-20260510-001500/faq-internal.md | 80 +++++++++++++++++++ 1 file changed, 80 insertions(+) create mode 100644 working-backwards/wb-20260510-001500/faq-internal.md diff --git a/working-backwards/wb-20260510-001500/faq-internal.md b/working-backwards/wb-20260510-001500/faq-internal.md new file mode 100644 index 0000000..993443e --- /dev/null +++ b/working-backwards/wb-20260510-001500/faq-internal.md @@ -0,0 +1,80 @@ +# Internal FAQ: AI-Product-Team Shared Runtime Core + +## Q1: What does "dual-runtime support" mean beyond adding `.codex/` files? + +Dual-runtime support means Claude Code and Codex can both run the same Working Backwards process from a shared source of truth and produce compatible session artifacts. A cosmetic Codex folder is not enough. The minimum bar is: + +- A shared pipeline definition for stage order, artifacts, and gate rules. +- Shared Critic rubrics used by both runtimes. +- A stable session schema both runtimes can read and update. +- Codex adapter instructions that can start, resume, and inspect sessions. +- Validation that a session produced by one runtime remains understandable by the other. + +Until those pieces work, Codex support should be described as scaffolded rather than complete. + +## Q2: What is the biggest technical risk? + +The biggest risk is adapter drift. If `.claude/` and `.codex/` each contain full copies of the process, they will diverge over time. One adapter may add a stage, update a rubric, or change artifact expectations while the other remains stale. That would break the product promise. + +Mitigation: define product behavior in `shared/` first, then make runtime adapters thin. During migration, duplicated adapter content should be treated as compatibility glue and synchronized from `shared/`. + +## Q3: Should we refactor the existing Claude adapter immediately to read only from `shared/`? + +Not all at once. The existing Claude adapter is the working implementation and should not be destabilized just to make the repo look cleaner. The safer sequence is: + +1. Add shared core files. +2. Add Codex adapter scaffold. +3. Update docs to define the adapter boundary. +4. Move one low-risk source at a time, starting with rubrics and methodology. +5. Add validation checks for parity. +6. Only then reduce large duplicated orchestration sections. + +## Q4: What validation do we need before marking Codex support as ready? + +We need at least one end-to-end Codex-authored session that reaches Requirements with the expected artifact layout. We also need compatibility checks that confirm: + +- `session.json` contains every stage from `shared/pipeline.json`. +- Every completed stage has its required artifact. +- Every Critic review records a rubric version. +- `[OPEN]` and `[BLOCKER]` items propagate to downstream stages. +- Demo and site artifacts are structurally runnable when local shell access is available. + +[OPEN - owner: engineering] Decide whether these checks should be a script, a Codex skill, a GitHub Action, or all three. + +## Q5: How do we prevent runtime-specific tool assumptions from leaking into the shared core? + +The shared core should describe product behavior, not tool mechanics. It can say "run the Critic using the stage rubric" but should not say "use Claude Agent tool" or "use Codex apply_patch." Those belong in adapters. + +A practical rule: if an instruction would be true in both Claude Code and Codex, it belongs in `shared/`. If it names a runtime tool, permission model, slash command, or local verification capability, it belongs in the adapter. + +## Q6: Can a session move between Claude Code and Codex mid-pipeline? + +[OPEN - owner: product maintainer] The desired answer is yes, but the contract is not proven yet. It requires both runtimes to preserve the same session schema, artifact paths, stage IDs, and Critic review records. Mid-pipeline handoff should not be promised until we test a session started in Claude and resumed in Codex, plus the reverse. + +## Q7: What are the legal, privacy, or security implications? + +No new data category is introduced by dual-runtime support. The same session artifacts are written to local disk or optionally pushed to GitHub. The main security concern is clarity: users must understand which runtime is handling their product context and where artifacts are persisted. + +If future integrations export to Notion, Linear, Confluence, or other systems, those integrations should have separate security review. They are not required for dual-runtime support. + +## Q8: What is the maintenance cost? + +Maintenance cost increases if adapters duplicate the process. Maintenance cost decreases if the shared core becomes the true source of truth. The core tradeoff is upfront migration work versus long-term clarity. + +Near-term maintainers must keep `.claude/rubrics/` and `shared/rubrics/` synchronized until Claude reads shared rubrics directly. That is acceptable as a transition state but should not become permanent. + +## Q9: What should ship first? + +The first shippable milestone should be "Codex-compatible scaffold," not "complete Codex parity." It should include: + +- `shared/pipeline.json` +- Shared methodology and rubrics +- `AGENTS.md` +- `.codex/skills/working-backwards/SKILL.md` +- `.codex/skills/wb-status/SKILL.md` +- A pilot Working Backwards session generated on the Codex branch +- Clear documentation that Codex support is scaffolded and what remains before parity + +## Q10: What blocks implementation from proceeding safely? + +[BLOCKER - owner: engineering] Local shell execution is currently failing in the active desktop session, which prevents local validation of generated demos, sites, and any future validation scripts. Documentation and GitHub-side artifact work can continue, but Codex parity cannot be considered complete until local execution and verification work reliably. From da5fcea4a0f26c5f392f56286d54b7b70b7a405a Mon Sep 17 00:00:00 2001 From: Brian McManus Date: Sun, 10 May 2026 12:34:21 -0700 Subject: [PATCH 27/27] Working Backwards [wb-20260510-001500]: Internal FAQ Critic PASS --- .../critic-stage-2-internal-faq.md | 26 +++++++++++++++++++ 1 file changed, 26 insertions(+) create mode 100644 working-backwards/wb-20260510-001500/critic-stage-2-internal-faq.md diff --git a/working-backwards/wb-20260510-001500/critic-stage-2-internal-faq.md b/working-backwards/wb-20260510-001500/critic-stage-2-internal-faq.md new file mode 100644 index 0000000..e299fd7 --- /dev/null +++ b/working-backwards/wb-20260510-001500/critic-stage-2-internal-faq.md @@ -0,0 +1,26 @@ +# Critic Review: Stage 2 Internal FAQ + +VERDICT: PASS +RUBRIC_VERSION: 1.0.0 + +SUMMARY: The Internal FAQ directly covers engineering feasibility, product sequencing, validation requirements, security boundaries, maintenance cost, and explicitly marks unresolved handoff and validation risks. + +## Dimension Results + +- coverage: PASS +- answer-completeness: PASS +- blocker-flagging: PASS +- evasion: PASS + +## Notes + +The FAQ includes two `[OPEN - owner: ...]` items: + +- Decide whether compatibility checks should be a script, Codex skill, GitHub Action, or all three. +- Decide when mid-pipeline handoff between Claude Code and Codex can be promised. + +The FAQ also includes one `[BLOCKER - owner: engineering]` item: + +- Local shell execution is currently failing in the active desktop session, preventing complete local validation of generated demos, sites, and future validation scripts. + +These are appropriately marked and should propagate into downstream demo, docs, telemetry, and requirements artifacts.