[gem-team] New Agents + magic keywords + coverage tracking + contract checks (#1227)

* 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

* chore(release): bump marketplace version to 1.3.4

- Update `marketplace.json` version from `1.3.3` to `1.3.4`.
- Refine `gem-browser-tester.agent.md`:
  - Replace "UUIDs" typo with correct spelling.
  - Adjust wording and formatting for clarity.
  - Update JSON code fences to use ````jsonc````.
  - Modify workflow description to reference `AGENTS.md` when present.
- Refine `gem-devops.agent.md`:
  - Align expertise list formatting.
  - Standardize tool list syntax with back‑ticks.
  - Minor wording improvements.
- Increase retry attempts in `gem-browser-tester.agent.md` from 2 to 3 attempts.
- Minor typographical and formatting corrections across agent documentation.

* refactor: rename prd_path to project_prd_path in agent configurations

- Updated gem-orchestrator.agent.md to use `project_prd_path` instead of `prd_path` in task definitions and delegation logic.
- Updated gem-planner.agent.md to reference `project_prd_path` and clarify PRD reading.
- Updated gem-researcher.agent.md to use `project_prd_path` and adjust PRD consumption logic.
- Applied minor wording improvements and consistency fixes across the orchestrator, planner, and researcher documentation.

* feat(plugin): expand marketplace description, bump version to 1.4.0; revamp gem-browser-tester agent documentation with clearer role, expertise, and workflow specifications.

* chore: remove outdated plugin metadata fields from README.plugins.md and plugin.json

* feat(tooling): bump marketplace version to 1.5.0 and refine validation thresholds

- Update marketplace.json version from 1.4.0 to 1.5.0
- Adjust validation criteria in gem-browser-tester.agent.md to trigger additional tests when coverage < 0.85 or confidence < 0.85
- Refine accessibility compliance description, adding runtime validation and SPEC‑based accessibility notes- Add new gem-code-simplifier.agent.md documentation for code refactoring
- Update README and plugin metadata to reflect version change and new tooling

* docs: improve bug‑fix delegation description and delegation‑first guidance in gem‑orchestrator.agent.md

- Clarified the two‑step diagnostic‑then‑fix flow for bug fixes using gem‑debugger and gem‑implementer.
- Updated the “Delegation First” checklist to stress that **no** task, however small, should be performed directly by the orchestrator, emphasizing sub‑agent delegation and retry/escalation strategy.

---------

Co-authored-by: Aaron Powell <me@aaron-powell.com>

agents/gem-planner.agent.md

@@ -15,7 +15,7 @@ Task Decomposition, DAG Design, Pre-Mortem Analysis, Risk Assessment
 
 # Available Agents
 
-gem-researcher, gem-implementer, gem-browser-tester, gem-devops, gem-reviewer, gem-documentation-writer
+gem-researcher, gem-implementer, gem-browser-tester, gem-devops, gem-reviewer, gem-documentation-writer, gem-debugger, gem-critic, gem-code-simplifier, gem-designer
 
 # Knowledge Sources
 
@@ -122,6 +122,12 @@ Pipeline Stages:
 - Pre-mortem: overall_risk_level defined, critical_failure_modes present for high/medium risk
 - Implementation spec: code_structure, affected_areas, component_details defined
 
+### 4.3 Self-Critique (Reflection)
+- Verify plan satisfies all acceptance_criteria from PRD
+- Check DAG maximizes parallelism (wave_1_task_count is reasonable)
+- Validate all tasks have agent assignments from available_agents list
+- If confidence < 0.85 or gaps found: re-design, document limitations
+
 ## 5. Handle Failure
 - If plan creation fails, log error, return status=failed with reason
 - If status=failed, write to `docs/plan/{plan_id}/logs/{agent}_{task_id}_{timestamp}.yaml`
@@ -210,7 +216,9 @@ tasks:
     title: string
     description: | # Use literal scalar to handle colons and preserve formatting
     wave: number # Execution wave: 1 runs first, 2 waits for 1, etc.
-    agent: string # gem-researcher | gem-implementer | gem-browser-tester | gem-devops | gem-reviewer | gem-documentation-writer
+    agent: string # gem-researcher | gem-implementer | gem-browser-tester | gem-devops | gem-reviewer | gem-documentation-writer | gem-debugger | gem-critic | gem-code-simplifier | gem-designer
+    prototype: boolean # true for prototype tasks, false for full feature
+    covers: [string] # Optional list of acceptance criteria IDs covered by this task
     priority: string # high | medium | low (reflection triggers: high=always, medium=if failed, low=no reflection)
     status: string # pending | in_progress | completed | failed | blocked | needs_revision (pending/blocked: orchestrator-only; others: worker outputs)
     dependencies:
@@ -220,6 +228,11 @@ tasks:
     context_files:
       - path: string
         description: string
+planning_pass: number # Current planning iteration pass
+planning_history:
+  - pass: number
+    reason: string
+    timestamp: string
     estimated_effort: string # small | medium | large
     estimated_files: number # Count of files affected (max 3)
     estimated_lines: number # Estimated lines to change (max 300)
@@ -304,9 +317,36 @@ tasks:
 - Over-engineering solutions
 - Vague or implementation-focused task descriptions
 
+# Agent Assignment Guidelines
+
+Use this table to select the appropriate agent for each task:
+
+| Task Type | Primary Agent | When to Use |
+|:----------|:--------------|:------------|
+| Code implementation | gem-implementer | Feature code, bug fixes, refactoring |
+| Research/analysis | gem-researcher | Exploration, pattern finding, investigating |
+| Planning/strategy | gem-planner | Creating plans, DAGs, roadmaps |
+| UI/UX work | gem-designer | Layouts, themes, components, design systems |
+| Refactoring | gem-code-simplifier | Dead code, complexity reduction, cleanup |
+| Bug diagnosis | gem-debugger | Root cause analysis (if requested), NOT for implementation |
+| Code review | gem-reviewer | Security, compliance, quality checks |
+| Browser testing | gem-browser-tester | E2E, UI testing, accessibility |
+| DevOps/deployment | gem-devops | Infrastructure, CI/CD, containers |
+| Documentation | gem-documentation-writer | Docs, READMEs, walkthroughs |
+| Critical review | gem-critic | Challenge assumptions, edge cases |
+| Complex project | All 11 agents | Orchestrator selects based on task type |
+
+**Special assignment rules:**
+- UI/Component tasks: gem-implementer for implementation, gem-designer for design review AFTER
+- Security tasks: Always assign gem-reviewer with review_security_sensitive=true
+- Refactoring tasks: Can assign gem-code-simplifier instead of gem-implementer
+- Debug tasks: gem-debugger diagnoses but does NOT fix (implementer does the fix)
+- Complex waves: Plan for gem-critic after wave completion (complex only)
+
 # Directives
 
 - Execute autonomously. Never pause for confirmation or progress report.
 - Pre-mortem: identify failure modes for high/medium tasks
 - Deliverable-focused framing (user outcomes, not code)
 - Assign only `available_agents` to tasks
+- Use Agent Assignment Guidelines above for proper routing