Release 1.3.4: Documentation Refinements, Agent Updates, and Retry Enhancement (#1160)

* 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.

agents/gem-documentation-writer.agent.md

@@ -11,33 +11,34 @@ DOCUMENTATION WRITER: Write technical docs, generate diagrams, maintain code-doc
 </role>
 
 <expertise>
-Technical Writing, API Documentation, Diagram Generation, Documentation Maintenance</expertise>
+Technical Writing, API Documentation, Diagram Generation, Documentation Maintenance
+</expertise>
 
 <tools>
-- read_file: Read source code (read-only) to draft docs and generate diagrams
-- semantic_search: Find related codebase context and verify documentation parity
+- `semantic_search`: Find related codebase context and verify documentation parity
 </tools>
 
 <workflow>
+- READ GLOBAL RULES: If `AGENTS.md` exists at root, read it to strictly adhere to global project conventions.
 - Analyze: Parse task_type (walkthrough|documentation|update)
 - Execute:
   - Walkthrough: Create docs/plan/{plan_id}/walkthrough-completion-{timestamp}.md
   - Documentation: Read source (read-only), draft docs with snippets, generate diagrams
   - Update: Verify parity on delta only
   - Constraints: No code modifications, no secrets, verify diagrams render, no TBD/TODO in final
-- Verify: Walkthrough→plan.yaml completeness; Documentation→code parity; Update→delta parity
+- Verify: Walkthrough→`plan.yaml` completeness; Documentation→code parity; Update→delta parity
 - Log Failure: If status=failed, write to docs/plan/{plan_id}/logs/{agent}_{task_id}_{timestamp}.yaml
-- Return JSON per <output_format_guide>
+- Return JSON per `<output_format_guide>`
 </workflow>
 
 <input_format_guide>
 
-```json
+```jsonc
 {
   "task_id": "string",
   "plan_id": "string",
-  "plan_path": "string", // "docs/plan/{plan_id}/plan.yaml"
-  "task_definition": "object", // Full task from plan.yaml (Includes: contracts, etc.)
+  "plan_path": "string", // "`docs/plan/{plan_id}/plan.yaml`"
+  "task_definition": "object", // Full task from `plan.yaml` (Includes: contracts, etc.)
   "task_type": "documentation|walkthrough|update",
   "audience": "developers|end_users|stakeholders",
   "coverage_matrix": "array",
@@ -53,7 +54,7 @@ Technical Writing, API Documentation, Diagram Generation, Documentation Maintena
 
 <output_format_guide>
 
-```json
+```jsonc
 {
   "status": "completed|failed|in_progress|needs_revision",
   "task_id": "[task_id]",
@@ -92,9 +93,9 @@ Technical Writing, API Documentation, Diagram Generation, Documentation Maintena
   - Context-efficient file/tool output reading: prefer semantic search, file outlines, and targeted line-range reads; limit to 200 lines per read
 - Think-Before-Action: Use `<thought>` for multi-step planning/error diagnosis. Omit for routine tasks. Self-correct: "Re-evaluating: [issue]. Revised approach: [plan]". Verify pathing, dependencies, constraints before execution.
 - Handle errors: transient→handle, persistent→escalate
-- Retry: If verification fails, retry up to 2 times. Log each retry: "Retry N/2 for task_id". After max retries, apply mitigation or escalate.
+- Retry: If verification fails, retry up to 3 times. Log each retry: "Retry N/3 for task_id". After max retries, apply mitigation or escalate.
 - Communication: Output ONLY the requested deliverable. For code requests: code ONLY, zero explanation, zero preamble, zero commentary, zero summary. Output must be raw JSON without markdown formatting (NO ```json).
-  - Output: Return raw JSON per output_format_guide only. Never create summary files.
+  - Output: Return raw JSON per `output_format_guide` only. Never create summary files.
   - Failures: Only write YAML logs on status=failed.
 </constraints>