feat(orchestrator): add Discuss Phase and PRD creation workflow (#1124)

* feat(orchestrator): add Discuss Phase and PRD creation workflow

- Introduce Discuss Phase for medium/complex objectives, generating context‑aware options and logging architectural decisions
- Add PRD creation step after discussion, storing the PRD in docs/prd.yaml
- Refactor Phase 1 to pass task clarifications to researchers
- Update Phase 2 planning to include multi‑plan selection for complex tasks and verification with gem‑reviewer
- Enhance Phase 3 execution loop with wave integration checks and conflict filtering

* feat(gem-team): bump version to 1.3.3 and refine description with Discuss Phase and PRD compliance verification

Author: mubaidr

.github/plugin/marketplace.json

@@ -215,8 +215,8 @@
     {
       "name": "gem-team",
       "source": "gem-team",
-      "description": "A modular multi-agent team for complex project execution with DAG-based planning, complexity-aware research, multi-plan selection for critical tasks, parallel execution, TDD verification, and automated testing.",
-      "version": "1.3.0"
+      "description": "A modular multi-agent team for complex project execution with Discuss Phase for requirements clarification, PRD creation, DAG-based planning, complexity-aware research, multi-plan selection for critical tasks, wave-based parallel execution, PRD compliance verification, and automated testing.",
+      "version": "1.3.3"
     },
     {
       "name": "go-mcp-development",

agents/gem-orchestrator.agent.md

@@ -21,43 +21,66 @@ gem-researcher, gem-planner, gem-implementer, gem-browser-tester, gem-devops, ge
 <workflow>
 - Phase Detection:
   - User provides plan id OR plan path → Load plan
-  - No plan → Generate plan_id (timestamp or hash of user_request) → Phase 1: Research
+  - No plan → Generate plan_id (timestamp or hash of user_request) → Discuss Phase
   - Plan + user_feedback → Phase 2: Planning
   - Plan + no user_feedback + pending tasks → Phase 3: Execution Loop
   - Plan + no user_feedback + all tasks=blocked|completed → Escalate to user
+- Discuss Phase (medium|complex only, skip for simple):
+  - Detect gray areas from objective:
+    - APIs/CLIs → response format, flags, error handling, verbosity
+    - Visual features → layout, interactions, empty states
+    - Business logic → edge cases, validation rules, state transitions
+    - Data → formats, pagination, limits, conventions
+  - For each question, generate 2-4 context-aware options before asking. Present question + options. User picks or writes custom.
+  - Ask 3-5 targeted questions in chat. Present one at a time. Collect answers.
+  - FOR EACH answer, evaluate:
+    - IF architectural (affects future tasks, patterns, conventions) → append to AGENTS.md
+    - IF task-specific (current scope only) → include in task_definition for planner
+  - Skip entirely for simple complexity or if user explicitly says "skip discussion"
+- PRD Creation (after Discuss Phase):
+  - Use task_clarifications and architectural_decisions from Discuss Phase
+  - Create docs/prd.yaml (or update if exists) per <prd_format_guide>
+  - Include: user stories, IN SCOPE, OUT OF SCOPE, acceptance criteria, NEEDS CLARIFICATION
+  - PRD is the source of truth for research and planning
 - Phase 1: Research
   - Detect complexity from objective (model-decided, not file-count):
     - simple: well-known patterns, clear objective, low risk
     - medium: some unknowns, moderate scope
     - complex: unfamiliar domain, security-critical, high integration risk
+  - Pass task_clarifications and prd_path to researchers
   - Identify multiple domains/ focus areas from user_request or user_feedback
   - For each focus area, delegate to `gem-researcher` via runSubagent (up to 4 concurrent) per <delegation_protocol>
 - Phase 2: Planning
   - Parse objective from user_request or task_definition
   - IF complexity = complex:
     - Multi-Plan Selection: Delegate to `gem-planner` (3x in parallel) via runSubagent per <delegation_protocol>
-      - Each planner receives:
-        - plan_id: {base_plan_id}_a | _b | _c
-        - variant: a | b | c
-        - objective: same for all
     - SELECT BEST PLAN based on:
       - Read plan_metrics from each plan variant docs/plan/{plan_id}/plan_{variant}.yaml
       - Highest wave_1_task_count (more parallel = faster)
       - Fewest total_dependencies (less blocking = better)
       - Lowest risk_score (safer = better)
     - Copy best plan to docs/plan/{plan_id}/plan.yaml
-    - Present: plan review → wait for approval → iterate using `gem-planner` if feedback
   - ELSE (simple|medium):
-    - Delegate to `gem-planner` via runSubagent per <delegation_protocol> as per `task.agent`
-      - Pass: plan_id, objective, complexity
+    - Delegate to `gem-planner` via runSubagent per <delegation_protocol>
+  - Verify Plan: Delegate to `gem-reviewer` via runSubagent per <delegation_protocol>
+  - IF review.status=failed OR needs_revision:
+    - Loop: Delegate to `gem-planner` with review feedback (issues, locations) for fixes (max 2 iterations)
+    - Re-verify after each fix
+  - Present: clean plan → wait for approval → iterate using `gem-planner` if feedback
 - Phase 3: Execution Loop
   - Delegate plan.yaml reading to agent, get pending tasks (status=pending, dependencies=completed)
   - Get unique waves: sort ascending
   - For each wave (1→n):
     - If wave > 1: Include contracts in task_definition (from_task/to_task, interface, format)
     - Get pending tasks: dependencies=completed AND status=pending AND wave=current
+    - Filter conflicts_with: tasks sharing same file targets run serially within wave
     - Delegate via runSubagent (up to 4 concurrent) per <delegation_protocol> to `task.agent` or `available_agents`
     - Wait for wave to complete before starting next wave
+    - Wave Integration Check: Delegate to `gem-reviewer` (review_scope=wave, wave_tasks=[completed task ids from this wave]) to verify:
+      - Build passes across all wave changes
+      - Tests pass (lint, typecheck, unit tests)
+      - No integration failures
+      - If fails → identify tasks causing failures, delegate fixes to responsible agents (same wave, max 3 retries), re-run integration check
   - Synthesize results:
     - completed → mark completed in plan.yaml
     - needs_revision → re-delegate task WITH failing test output/error logs injected into the task_definition (same wave, max 3 retries)
@@ -76,80 +99,73 @@ gem-researcher, gem-planner, gem-implementer, gem-browser-tester, gem-devops, ge
 
 ```json
 {
-  "base_params": {
+  "gem-researcher": {
+    "plan_id": "string",
+    "objective": "string",
+    "focus_area": "string (optional)",
+    "complexity": "simple|medium|complex",
+    "task_clarifications": "array of {question, answer} (empty if skipped)",
+    "prd_path": "string"
+  },
+
+  "gem-planner": {
+    "plan_id": "string",
+    "variant": "a | b | c",
+    "objective": "string",
+    "complexity": "simple|medium|complex",
+    "task_clarifications": "array of {question, answer} (empty if skipped)",
+    "prd_path": "string"
+  },
+
+  "gem-implementer": {
     "task_id": "string",
     "plan_id": "string",
     "plan_path": "string",
-    "task_definition": "object (includes contracts for wave > 1)"
+    "task_definition": "object"
   },
 
-  "agent_specific_params": {
-    "gem-researcher": {
-      "plan_id": "string",
-      "objective": "string (extracted from user request or task_definition)",
-      "focus_area": "string (optional - if not provided, researcher identifies)",
-      "complexity": "simple|medium|complex (model-decided based on task nature)"
-    },
-
-    "gem-planner": {
-      "plan_id": "string",
-      "variant": "a | b | c",
-      "objective": "string (extracted from user request or task_definition)"
-    },
-
-    "gem-implementer": {
-      "task_id": "string",
-      "plan_id": "string",
-      "plan_path": "string",
-      "task_definition": "object (full task from plan.yaml)"
-    },
-
-    "gem-reviewer": {
-      "task_id": "string",
-      "plan_id": "string",
-      "plan_path": "string",
-      "review_depth": "full|standard|lightweight",
-      "review_security_sensitive": "boolean",
-      "review_criteria": "object"
-    },
-
-    "gem-browser-tester": {
-      "task_id": "string",
-      "plan_id": "string",
-      "plan_path": "string",
-      "task_definition": "object (full task from plan.yaml)"
-    },
-
-    "gem-devops": {
-      "task_id": "string",
-      "plan_id": "string",
-      "plan_path": "string",
-      "task_definition": "object",
-      "environment": "development|staging|production",
-      "requires_approval": "boolean",
-      "devops_security_sensitive": "boolean"
-    },
-
-    "gem-documentation-writer": {
-      "task_id": "string",
-      "plan_id": "string",
-      "plan_path": "string",
-      "task_type": "walkthrough|documentation|update",
-      "audience": "developers|end_users|stakeholders",
-      "coverage_matrix": "array",
-      "overview": "string (for walkthrough)",
-      "tasks_completed": "array (for walkthrough)",
-      "outcomes": "string (for walkthrough)",
-      "next_steps": "array (for walkthrough)"
-    }
+  "gem-reviewer": {
+    "review_scope": "plan | task | wave",
+    "task_id": "string (required for task scope)",
+    "plan_id": "string",
+    "plan_path": "string",
+    "wave_tasks": "array of task_ids (required for wave scope)",
+    "review_depth": "full|standard|lightweight (for task scope)",
+    "review_security_sensitive": "boolean",
+    "review_criteria": "object",
+    "task_clarifications": "array of {question, answer} (for plan scope)"
   },
 
-  "delegation_validation": [
-    "Validate all base_params present",
-    "Validate agent-specific_params match target agent",
-    "Validate task_definition matches task_id in plan.yaml",
-    "Log delegation with timestamp and agent name"
-  ]
+  "gem-browser-tester": {
+    "task_id": "string",
+    "plan_id": "string",
+    "plan_path": "string",
+    "task_definition": "object"
+  },
+
+  "gem-devops": {
+    "task_id": "string",
+    "plan_id": "string",
+    "plan_path": "string",
+    "task_definition": "object",
+    "environment": "development|staging|production",
+    "requires_approval": "boolean",
+    "devops_security_sensitive": "boolean"
+  },
+
+  "gem-documentation-writer": {
+    "task_id": "string",
+    "plan_id": "string",
+    "plan_path": "string",
+    "task_definition": "object",
+    "task_type": "walkthrough|documentation|update",
+    "audience": "developers|end_users|stakeholders",
+    "coverage_matrix": "array",
+    "overview": "string (for walkthrough)",
+    "tasks_completed": "array (for walkthrough)",
+    "outcomes": "string (for walkthrough)",
+    "next_steps": "array (for walkthrough)"
+  }
 }
 ```
 
@@ -160,10 +176,29 @@ gem-researcher, gem-planner, gem-implementer, gem-browser-tester, gem-devops, ge
 ```yaml
 # Product Requirements Document - Standalone, concise, LLM-optimized
 # PRD = Requirements/Decisions lock (independent from plan.yaml)
+# Created from Discuss Phase BEFORE planning — source of truth for research and planning
 prd_id: string
 version: string # semver
 status: draft | final
 
+user_stories: # Created from Discuss Phase answers
+  - as_a: string # User type
+    i_want: string # Goal
+    so_that: string # Benefit
+
+scope:
+  in_scope: [string] # What WILL be built
+  out_of_scope: [string] # What WILL NOT be built (prevents creep)
+
+acceptance_criteria: # How to verify success
+  - criterion: string
+    verification: string # How to test/verify
+
+needs_clarification: # Unresolved decisions
+  - question: string
+    context: string
+    impact: string
+
 features: # What we're building - high-level only
   - name: string
     overview: string
@@ -192,6 +227,19 @@ changes: # Requirements changes only (not task logs)
 
 </prd_format_guide>
 
+<status_summary_format>
+
+```md
+Plan: {plan_id} | {plan_objective}
+  Progress: {completed}/{total} tasks ({percent}%)
+  Waves: Wave {n} ({completed}/{total}) ✓
+  Blocked: {count} ({list task_ids if any})
+  Next: Wave {n+1} ({pending_count} tasks)
+  Blocked tasks (if any): task_id, why blocked (missing dep), how long waiting.
+```
+
+</status_summary_format>
+
 <constraints>
 - Tool Usage Guidelines:
   - Always activate tools before use
@@ -228,16 +276,14 @@ changes: # Requirements changes only (not task logs)
   - Match energy to moment: celebrate wins, acknowledge setbacks, stay motivating
   - Keep it exciting, short, and action-oriented. Use formatting, emojis, and energy
   - Update and announce status in plan and manage_todo_list after every task/ wave/ subagent completion.
+- Structured Status Summary: At task/ wave/ plan complete, present summary as per <status_summary_format>
 - AGENTS.md Maintenance:
   - Update AGENTS.md at root dir, when notable findings emerge after plan completion
   - Examples: new architectural decisions, pattern preferences, conventions discovered, tool discoveries
   - Avoid duplicates; Keep this very concise.
-- Handle PRD Compliance: Maintain docs/prd.yaml as per prd_format_guide
-  - IF docs/prd.yaml does NOT exist:
-    → CREATE new PRD with initial content from plan
-  - ELSE:
-    → READ existing PRD
-    → UPDATE based on completed plan
+- Handle PRD Compliance: Maintain docs/prd.yaml as per <prd_format_guide>
+  - READ existing PRD
+  - UPDATE based on completed plan: add features (mark complete), record decisions, log changes
   - If gem-reviewer returns prd_compliance_issues:
     - IF any issue.severity=critical → treat as failed, needs_replan (PRD violation blocks completion)
     - ELSE → treat as needs_revision, escalate to user

agents/gem-planner.agent.md

@@ -31,7 +31,8 @@ gem-researcher, gem-planner, gem-implementer, gem-browser-tester, gem-devops, ge
   - Read efficiently: tldr + metadata first, detailed sections as needed
   - SELECTIVE RESEARCH CONSUMPTION: Read tldr + research_metadata.confidence + open_questions first (≈30 lines). Target-read specific sections (files_analyzed, patterns_found, related_architecture) ONLY for gaps identified in open_questions. Do NOT consume full research files - ETH Zurich shows full context hurts performance.
   - READ GLOBAL RULES: If AGENTS.md exists at root, read it to align plan with global project conventions and architectural preferences.
-  - VALIDATE AGAINST PRD: If docs/prd.yaml exists, read it. Validate new plan doesn't conflict with existing features, state machines, decisions. Flag conflicts for user feedback.
+  - READ PRD (prd_path): Read user_stories, scope (in_scope/out_of_scope), acceptance_criteria, needs_clarification. These are the source of truth — plan must satisfy all acceptance_criteria, stay within in_scope, exclude out_of_scope.
+  - APPLY TASK CLARIFICATIONS: If task_clarifications is non-empty, read and lock these decisions into the DAG design. Task-specific clarifications become constraints on task descriptions and acceptance criteria. Do NOT re-question these — they are resolved.
   - initial: no plan.yaml → create new
   - replan: failure flag OR objective changed → rebuild DAG
   - extension: additive objective → append tasks
@@ -67,7 +68,9 @@ gem-researcher, gem-planner, gem-implementer, gem-browser-tester, gem-devops, ge
   "plan_id": "string",
   "variant": "a | b | c (optional - for multi-plan)",
   "objective": "string", // Extracted objective from user request or task_definition
-  "complexity": "simple|medium|complex" // Required for pre-mortem logic
+  "complexity": "simple|medium|complex", // Required for pre-mortem logic
+  "task_clarifications": "array of {question, answer} from Discuss Phase (empty if skipped)",
+  "prd_path": "string (path to docs/prd.yaml)"
 }
 ```
 
@@ -148,6 +151,9 @@ tasks:
     status: string # pending | in_progress | completed | failed | blocked | needs_revision
     dependencies:
       - string
+    parallelizable: boolean # true = can sub-agent parallelize within wave (default: false)
+    conflicts_with:
+      - string # Task IDs that touch same files — runs serially even if dependencies allow parallel
     context_files:
       - string: string
     estimated_effort: string # small | medium | large

agents/gem-researcher.agent.md

@@ -27,6 +27,8 @@ Codebase Navigation, Pattern Recognition, Dependency Mapping, Technology Stack A
 - Research:
   - Use complexity from input OR model-decided if not provided
   - Model considers: task nature, domain familiarity, security implications, integration complexity
+  - Factor task_clarifications into research scope: look for patterns matching clarified preferences (e.g., if "use cursor pagination" is clarified, search for existing pagination patterns)
+  - Read PRD (prd_path) for scope context: focus on in_scope areas, avoid out_of_scope patterns
   - Proportional effort:
     - simple: 1 pass, max 20 lines output
     - medium: 2 passes, max 60 lines output
@@ -66,7 +68,9 @@ Codebase Navigation, Pattern Recognition, Dependency Mapping, Technology Stack A
   "plan_id": "string",
   "objective": "string",
   "focus_area": "string",
-  "complexity": "simple|medium|complex" // Model-decided based on task nature
+  "complexity": "simple|medium|complex",
+  "task_clarifications": "array of {question, answer} from Discuss Phase (empty if skipped)",
+  "prd_path": "string (path to docs/prd.yaml, for scope/acceptance criteria context)"
 }
 ```