[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-researcher.agent.md

@@ -98,6 +98,12 @@ DO NOT include: suggestions/recommendations - pure factual research
 - Completeness: All required sections present
 - Format compliance: Per `Research Format Guide` (YAML)
 
+## 4.1 Self-Critique (Reflection)
+- Verify all required sections present (files_analyzed, patterns_found, open_questions, gaps)
+- Check research_metadata confidence and coverage are justified by evidence
+- Validate findings are factual (no opinions/suggestions)
+- If confidence < 0.85 or gaps found: re-run with expanded scope, document limitations
+
 ## 5. Output
 - Save: `docs/plan/{plan_id}/research_findings_{focus_area}.yaml` (use timestamp if focus_area empty)
 - Log Failure: If status=failed, write to `docs/plan/{plan_id}/logs/{agent}_{task_id}_{timestamp}.yaml`
@@ -124,7 +130,9 @@ DO NOT include: suggestions/recommendations - pure factual research
   "plan_id": "[plan_id]",
   "summary": "[brief summary ≤3 sentences]",
   "failure_type": "transient|fixable|needs_replan|escalate", // Required when status=failed
-  "extra": {}
+  "extra": {
+    "research_path": "docs/plan/{plan_id}/research_findings_{focus_area}.yaml"
+  }
 }
 ```
 
@@ -146,6 +154,8 @@ research_metadata:
   scope: string # breadth and depth of exploration
   confidence: string # high | medium | low
   coverage: number # percentage of relevant files examined
+  decision_blockers: number
+  research_blockers: number
 
 files_analyzed: # REQUIRED
 - file: string
@@ -234,11 +244,14 @@ testing_patterns: # IF APPLICABLE - Only if domain has specific testing patterns
 open_questions: # REQUIRED
 - question: string
   context: string # Why this question emerged during research
+  type: decision_blocker | research | nice_to_know
+  affects: [string] # impacted task IDs
 
 gaps: # REQUIRED
 - area: string
   description: string
-  impact: string # How this gap affects understanding of the domain
+  impact: decision_blocker | research_blocker | nice_to_know
+  affects: [string] # impacted task IDs
 ```
 
 # Sequential Thinking Criteria