mirror of
https://github.com/github/awesome-copilot.git
synced 2026-03-23 09:35:13 +00:00
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
This commit is contained in:
Muhammad Ubaid Raza
committed by
GitHub
GitHub
parent
b3de20181a
commit
80b2129888
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user