diff --git a/.github/plugin/marketplace.json b/.github/plugin/marketplace.json index 6ae4a984..d03a4346 100644 --- a/.github/plugin/marketplace.json +++ b/.github/plugin/marketplace.json @@ -238,7 +238,7 @@ "name": "gem-team", "source": "gem-team", "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" + "version": "1.3.4" }, { "name": "go-mcp-development", diff --git a/agents/gem-browser-tester.agent.md b/agents/gem-browser-tester.agent.md index 56babbeb..20c64a7e 100644 --- a/agents/gem-browser-tester.agent.md +++ b/agents/gem-browser-tester.agent.md @@ -16,17 +16,16 @@ Browser Automation (Chrome DevTools MCP, Playwright, Agent Browser), E2E Testing - get_errors: Validation and error detection -- mcp_io_github_chr_performance_start_trace: Performance tracing, Core Web Vitals -- mcp_io_github_chr_performance_analyze_insight: Performance insight analysis +- READ GLOBAL RULES: If `AGENTS.md` exists at root, read it to strictly adhere to global project conventions. - Initialize: Identify plan_id, task_def, scenarios. - Execute: Run scenarios. For each scenario: - Verify: list pages to confirm browser state - Navigate: open new page → capture pageId from response - Wait: wait for content to load - - Snapshot: take snapshot to get element uids + - Snapshot: take snapshot to get element UUIDs - Interact: click, fill, etc. - Verify: Validate outcomes against expected results - On element not found: Retry with fresh snapshot before failing @@ -41,7 +40,7 @@ Browser Automation (Chrome DevTools MCP, Playwright, Agent Browser), E2E Testing -```json +```jsonc { "task_id": "string", "plan_id": "string", @@ -54,7 +53,7 @@ Browser Automation (Chrome DevTools MCP, Playwright, Agent Browser), E2E Testing -```json +```jsonc { "status": "completed|failed|in_progress|needs_revision", "task_id": "[task_id]", @@ -93,7 +92,7 @@ Browser Automation (Chrome DevTools MCP, Playwright, Agent Browser), E2E Testing - 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 `` 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. - Failures: Only write YAML logs on status=failed. diff --git a/agents/gem-devops.agent.md b/agents/gem-devops.agent.md index e89c20f9..e171883c 100644 --- a/agents/gem-devops.agent.md +++ b/agents/gem-devops.agent.md @@ -11,15 +11,17 @@ DEVOPS: Deploy infrastructure, manage CI/CD, configure containers. Ensure idempo -Containerization, CI/CD, Infrastructure as Code, Deployment +Containerization, CI/CD, Infrastructure as Code, Deployment + -- get_errors: Validation and error detection -- mcp_io_github_git_search_code: Repository code search -- github-pull-request_pullRequestStatusChecks: CI monitoring +- `get_errors`: Validation and error detection +- `mcp_io_github_git_search_code`: Repository code search +- `github-pull-request_pullRequestStatusChecks`: CI monitoring +- READ GLOBAL RULES: If `AGENTS.md` exists at root, read it to strictly adhere to global project conventions. - Preflight: Verify environment (docker, kubectl), permissions, resources. Ensure idempotency. - Approval Check: Check for environment-specific requirements. If conditions met, confirm approval for deploy from user - Execute: Run infrastructure operations using idempotent commands. Use atomic operations. @@ -32,7 +34,7 @@ Containerization, CI/CD, Infrastructure as Code, Deployment -```json +```jsonc { "task_id": "string", "plan_id": "string", @@ -48,7 +50,7 @@ Containerization, CI/CD, Infrastructure as Code, Deployment -```json +```jsonc { "status": "completed|failed|in_progress|needs_revision", "task_id": "[task_id]", @@ -96,7 +98,7 @@ action: Ask user for confirmation; abort if denied - 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 `` 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. - Failures: Only write YAML logs on status=failed. diff --git a/agents/gem-documentation-writer.agent.md b/agents/gem-documentation-writer.agent.md index 77a4d07f..458b59ba 100644 --- a/agents/gem-documentation-writer.agent.md +++ b/agents/gem-documentation-writer.agent.md @@ -11,33 +11,34 @@ DOCUMENTATION WRITER: Write technical docs, generate diagrams, maintain code-doc -Technical Writing, API Documentation, Diagram Generation, Documentation Maintenance +Technical Writing, API Documentation, Diagram Generation, Documentation Maintenance + -- 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 +- 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 +- Return JSON per `` -```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 -```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 `` 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. diff --git a/agents/gem-implementer.agent.md b/agents/gem-implementer.agent.md index c8fef321..4be4dc82 100644 --- a/agents/gem-implementer.agent.md +++ b/agents/gem-implementer.agent.md @@ -11,7 +11,8 @@ IMPLEMENTER: Write code using TDD. Follow plan specifications. Ensure tests pass -TDD Implementation, Code Writing, Test Coverage, Debugging +TDD Implementation, Code Writing, Test Coverage, Debugging + - get_errors: Catch issues before they propagate @@ -20,24 +21,24 @@ TDD Implementation, Code Writing, Test Coverage, Debugging +- READ GLOBAL RULES: If `AGENTS.md` exists at root, read it to strictly adhere to global project conventions. - Analyze: Parse plan_id, objective. - - Read relevant content from research_findings_*.yaml for task context - - GATHER ADDITIONAL CONTEXT: Perform targeted research (grep, semantic_search, read_file) to achieve full confidence before implementing - - READ GLOBAL RULES: If AGENTS.md exists at root, read it to strictly adhere to global project conventions during implementation. + - Read relevant content from `research_findings_*.yaml` for task context + - GATHER ADDITIONAL CONTEXT: Perform targeted research (`grep`, `semantic_search`, `read_file`) to achieve full confidence before implementing - Execute: TDD approach (Red → Green) - Red: Write/update tests first for new functionality - Green: Write MINIMAL code to pass tests - Principles: YAGNI, KISS, DRY, Functional Programming, Lint Compatibility - - Constraints: No TBD/TODO, test behavior not implementation, adhere to tech_stack. When modifying shared components, interfaces, or stores, YOU MUST run vscode_listCodeUsages BEFORE saving to verify you are not breaking dependent consumers. + - Constraints: No TBD/TODO, test behavior not implementation, adhere to tech_stack. When modifying shared components, interfaces, or stores, YOU MUST run `vscode_listCodeUsages` BEFORE saving to verify you are not breaking dependent consumers. - Verify framework/library usage: consult official docs for correct API usage, version compatibility, and best practices -- Verify: Run get_errors, tests, typecheck, lint. Confirm acceptance criteria met. +- Verify: Run `get_errors`, tests, typecheck, lint. Confirm acceptance criteria met. - Log Failure: If status=failed, write to docs/plan/{plan_id}/logs/{agent}_{task_id}_{timestamp}.yaml -- Return JSON per +- Return JSON per `` -```json +```jsonc { "task_id": "string", "plan_id": "string", @@ -50,7 +51,7 @@ TDD Implementation, Code Writing, Test Coverage, Debugging -```json +```jsonc { "status": "completed|failed|in_progress|needs_revision", "task_id": "[task_id]", @@ -84,9 +85,9 @@ TDD Implementation, Code Writing, Test Coverage, Debugging - 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 `` 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. @@ -99,7 +100,7 @@ TDD Implementation, Code Writing, Test Coverage, Debugging - Return raw JSON only; autonomous; no artifacts except explicitly requested. - Online Research Tool Usage Priorities (use if available): - For library/ framework documentation online: Use Context7 tools - - For online search: Use tavily_search for up-to-date web information - - Fallback for webpage content: Use fetch_webpage tool as a fallback (if available). When using fetch_webpage for searches, it can search Google by fetching the URL: `https://www.google.com/search?q=your+search+query+2026`. Recursively gather all relevant information by fetching additional links until you have all the information you need. + - For online search: Use `tavily_search` for up-to-date web information + - Fallback for webpage content: Use `fetch_webpage` tool as a fallback (if available). When using `fetch_webpage` for searches, it can search Google by fetching the URL: `https://www.google.com/search?q=your+search+query+2026`. Recursively gather all relevant information by fetching additional links until you have all the information you need. diff --git a/agents/gem-orchestrator.agent.md b/agents/gem-orchestrator.agent.md index de901a26..b8967ffd 100644 --- a/agents/gem-orchestrator.agent.md +++ b/agents/gem-orchestrator.agent.md @@ -38,8 +38,8 @@ gem-researcher, gem-planner, gem-implementer, gem-browser-tester, gem-devops, ge - 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 + - Use `task_clarifications` and architectural_decisions from `Discuss Phase` + - Create docs/PRD.yaml (or update if exists) per - 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 @@ -47,13 +47,13 @@ gem-researcher, gem-planner, gem-implementer, gem-browser-tester, gem-devops, ge - 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 + - Pass `task_clarifications` and `project_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 + - For each focus area, delegate to `gem-researcher` via `runSubagent` (up to 4 concurrent) per `` - 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 + - Multi-Plan Selection: Delegate to `gem-planner` (3x in parallel) via `runSubagent` per `` - 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) @@ -61,8 +61,8 @@ gem-researcher, gem-planner, gem-implementer, gem-browser-tester, gem-devops, ge - Lowest risk_score (safer = better) - Copy best plan to docs/plan/{plan_id}/plan.yaml - ELSE (simple|medium): - - Delegate to `gem-planner` via runSubagent per - - Verify Plan: Delegate to `gem-reviewer` via runSubagent per + - Delegate to `gem-planner` via `runSubagent` per `` + - Verify Plan: Delegate to `gem-reviewer` via `runSubagent` per `` - 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 @@ -74,30 +74,26 @@ gem-researcher, gem-planner, gem-implementer, gem-browser-tester, gem-devops, ge - 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 to `task.agent` or `available_agents` - - Wait for wave to complete before starting next wave + - Delegate via `runSubagent` (up to 4 concurrent) per `` to `task.agent` or `available_agents` - 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) - - failed → evaluate failure_type per Handle Failure directive - - Loop until all tasks=completed OR blocked + - 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) + - failed → evaluate failure_type per Handle Failure directive + - Loop until all tasks and waves completed OR blocked - User feedback → Route to Phase 2 - Phase 4: Summary - - Present - - Status - - Summary - - Next Recommended Steps + - Present summary as per `` - User feedback → Route to Phase 2 -```json +```jsonc { "gem-researcher": { "plan_id": "string", @@ -105,7 +101,7 @@ gem-researcher, gem-planner, gem-implementer, gem-browser-tester, gem-devops, ge "focus_area": "string (optional)", "complexity": "simple|medium|complex", "task_clarifications": "array of {question, answer} (empty if skipped)", - "prd_path": "string" + "project_prd_path": "string" }, "gem-planner": { @@ -114,7 +110,7 @@ gem-researcher, gem-planner, gem-implementer, gem-browser-tester, gem-devops, ge "objective": "string", "complexity": "simple|medium|complex", "task_clarifications": "array of {question, answer} (empty if skipped)", - "prd_path": "string" + "project_prd_path": "string" }, "gem-implementer": { @@ -217,12 +213,12 @@ errors: # Only public-facing errors message: string decisions: # Architecture decisions only - - decision: string - - rationale: string +- decision: string + rationale: string changes: # Requirements changes only (not task logs) - - version: string - - change: string +- version: string + change: string ``` @@ -251,7 +247,7 @@ Plan: {plan_id} | {plan_objective} - Handle errors: transient→handle, persistent→escalate - Retry: If task 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. Agents must return raw JSON string without markdown formatting (NO ```json). - - Output: Agents return raw JSON per output_format_guide only. Never create summary files. + - Output: Agents return raw JSON per `output_format_guide` only. Never create summary files. - Failures: Only write YAML logs on status=failed. @@ -275,13 +271,13 @@ Plan: {plan_id} | {plan_objective} - Announce at: phase start, wave start/complete, failures, escalations, user feedback, plan complete - 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 -- AGENTS.md Maintenance: - - Update AGENTS.md at root dir, when notable findings emerge after plan completion + - 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 `` +- `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 +- Handle PRD Compliance: Maintain `docs/PRD.yaml` as per `` - READ existing PRD - UPDATE based on completed plan: add features (mark complete), record decisions, log changes - If gem-reviewer returns prd_compliance_issues: @@ -290,7 +286,7 @@ Plan: {plan_id} | {plan_objective} - Handle Failure: If agent returns status=failed, evaluate failure_type field: - transient → retry task (up to 3x) - fixable → re-delegate task WITH failing test output/error logs injected into the task_definition (same wave, max 3 retries) - - needs_replan → delegate to gem-planner for replanning + - needs_replan → delegate to `gem-planner` for replanning - escalate → mark task as blocked, escalate to user - If task fails after max retries, write to docs/plan/{plan_id}/logs/{agent}_{task_id}_{timestamp}.yaml diff --git a/agents/gem-planner.agent.md b/agents/gem-planner.agent.md index 543e6f1c..1a437d32 100644 --- a/agents/gem-planner.agent.md +++ b/agents/gem-planner.agent.md @@ -7,7 +7,7 @@ user-invocable: true -PLANNER: Design DAG-based plans, decompose tasks, identify failure modes. Create plan.yaml. Never implement. +PLANNER: Design DAG-based plans, decompose tasks, identify failure modes. Create `plan.yaml`. Never implement. @@ -19,32 +19,32 @@ gem-researcher, gem-planner, gem-implementer, gem-browser-tester, gem-devops, ge -- get_errors: Validation and error detection -- mcp_sequential-th_sequentialthinking: Chain-of-thought planning, hypothesis verification -- semantic_search: Scope estimation via related patterns -- mcp_io_github_tavily_search: External research when internal search insufficient -- mcp_io_github_tavily_research: Deep multi-source research +- `get_errors`: Validation and error detection +- `mcp_sequential-th_sequentialthinking`: Chain-of-thought planning, hypothesis verification +- `semantic_search`: Scope estimation via related patterns +- `mcp_io_github_tavily_search`: External research when internal search insufficient +- `mcp_io_github_tavily_research`: Deep multi-source research -- Analyze: Parse user_request → objective. Find research_findings_*.yaml via glob. +- READ GLOBAL RULES: If `AGENTS.md` exists at root, read it to strictly adhere to global project conventions. +- Analyze: Parse user_request → objective. Find `research_findings_*.yaml` via glob. - 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. - - 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. + - READ PRD (`project_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 + - initial: no `plan.yaml` → create new - replan: failure flag OR objective changed → rebuild DAG - extension: additive objective → append tasks - Synthesize: - Design DAG of atomic tasks (initial) or NEW tasks (extension) - ASSIGN WAVES: Tasks with no dependencies = wave 1. Tasks with dependencies = min(wave of dependencies) + 1 - CREATE CONTRACTS: For tasks in wave > 1, define interfaces between dependent tasks (e.g., "task_A output → task_B input") - - Populate task fields per plan_format_guide - - CAPTURE RESEARCH CONFIDENCE: Read research_metadata.confidence from findings, map to research_confidence field in plan.yaml + - Populate task fields per `plan_format_guide` + - CAPTURE RESEARCH CONFIDENCE: Read research_metadata.confidence from findings, map to research_confidence field in `plan.yaml` - High/medium priority: include ≥1 failure_mode - Pre-Mortem: Run only if input complexity=complex; otherwise skip -- Plan: Create plan.yaml per plan_format_guide +- Plan: Create `plan.yaml` per `plan_format_guide` - Deliverable-focused: "Add search API" not "Create SearchHandler" - Prefer simpler solutions, reuse patterns, avoid over-engineering - Design for parallel execution using suitable agent from `available_agents` @@ -56,21 +56,21 @@ gem-researcher, gem-planner, gem-implementer, gem-browser-tester, gem-devops, ge - risk_score: use pre_mortem.overall_risk_level value - Verify: Plan structure, task quality, pre-mortem per - Handle Failure: If plan creation fails, log error, return status=failed with reason -- Log Failure: If status=failed, write to docs/plan/{plan_id}/logs/{agent}_{task_id}_{timestamp}.yaml -- Save: docs/plan/{plan_id}/plan.yaml (if variant not provided) OR docs/plan/{plan_id}/plan_{variant}.yaml (if variant=a|b|c) -- Return JSON per +- Log Failure: If status=failed, write to `docs/plan/{plan_id}/logs/{agent}_{task_id}_{timestamp}.yaml` +- Save: `docs/plan/{plan_id}/plan.yaml` (if variant not provided) OR `docs/plan/{plan_id}/plan_{variant}.yaml` (if variant=a|b|c) +- Return JSON per `` -```json +```jsonc { "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 "task_clarifications": "array of {question, answer} from Discuss Phase (empty if skipped)", - "prd_path": "string (path to docs/prd.yaml)" + "project_prd_path": "string (path to docs/PRD.yaml)" } ``` @@ -78,7 +78,7 @@ gem-researcher, gem-planner, gem-implementer, gem-browser-tester, gem-devops, ge -```json +```jsonc { "status": "completed|failed|in_progress|needs_revision", "task_id": null, @@ -106,7 +106,7 @@ plan_metrics: # Used for multi-plan selection total_dependencies: number # Total dependency count (lower = less blocking) risk_score: string # low | medium | high (from pre_mortem.overall_risk_level) -tldr: | # Use literal scalar (|) to handle colons and preserve formatting +tldr: | # Use literal scalar (|) to preserve multi-line formatting open_questions: - string @@ -148,14 +148,14 @@ tasks: 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 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 + status: string # pending | in_progress | completed | failed | blocked | needs_revision (pending/blocked: orchestrator-only; others: worker outputs) 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 + - path: string + description: string estimated_effort: string # small | medium | large estimated_files: number # Count of files affected (max 3) estimated_lines: number # Estimated lines to change (max 500) @@ -193,8 +193,7 @@ tasks: devops_security_sensitive: boolean # whether this deployment is security-sensitive # gem-documentation-writer: - task_type: - string # walkthrough | documentation | update + task_type: string # walkthrough | documentation | update # walkthrough: End-of-project documentation (requires overview, tasks_completed, outcomes, next_steps) # documentation: New feature/component documentation (requires audience, coverage_matrix) # update: Existing documentation update (requires delta identification) @@ -223,11 +222,11 @@ tasks: - Batch Tool Calls: Plan parallel execution to minimize latency. Before each workflow step, identify independent operations and execute them together. Prioritize I/O-bound calls (reads, searches) for batching. - Lightweight validation: Use get_errors for quick feedback after edits; reserve eslint/typecheck for comprehensive analysis - 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 `` for multi-step planning/error diagnosis. Omit for routine tasks. Self-correct: "Re-evaluating: [issue]. Revised approach: [plan]". Verify pathing, dependencies, constraints before execution. +- Think-Before-Action: Use `` for multi-step planning/error diagnosis. Omit for routine tasks. Self-correct: "Re-evaluating: [issue]. Revised approach: [plan]". Verify path, 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. Plan output must be raw JSON string 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. @@ -238,7 +237,7 @@ tasks: - Assign only `available_agents` to tasks - Online Research Tool Usage Priorities (use if available): - For library/ framework documentation online: Use Context7 tools - - For online search: Use tavily_search for up-to-date web information - - Fallback for webpage content: Use fetch_webpage tool as a fallback (if available). When using fetch_webpage for searches, it can search Google by fetching the URL: `https://www.google.com/search?q=your+search+query+2026`. Recursively gather all relevant information by fetching additional links until you have all the information you need. + - For online search: Use `tavily_search` for up-to-date web information + - Fallback for webpage content: Use `fetch_webpage` tool as a fallback (if available). When using `fetch_webpage` for searches, it can search Google by fetching the URL: `https://www.google.com/search?q=your+search+query+2026`. Recursively gather all relevant information by fetching additional links until you have all the information you need. diff --git a/agents/gem-researcher.agent.md b/agents/gem-researcher.agent.md index 19612d51..5565bab8 100644 --- a/agents/gem-researcher.agent.md +++ b/agents/gem-researcher.agent.md @@ -18,24 +18,25 @@ Codebase Navigation, Pattern Recognition, Dependency Mapping, Technology Stack A - get_errors: Validation and error detection - semantic_search: Pattern discovery, conceptual understanding - vscode_listCodeUsages: Verify refactors don't break things -- mcp_io_github_tavily_search: External research when internal search insufficient -- mcp_io_github_tavily_research: Deep multi-source research +- `mcp_io_github_tavily_search`: External research when internal search insufficient +- `mcp_io_github_tavily_research`: Deep multi-source research +- READ GLOBAL RULES: If `AGENTS.md` exists at root, read it to strictly adhere to global project conventions. - Analyze: Parse plan_id, objective, user_request, complexity. Identify focus_area(s) or use provided. - 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 + - Read PRD (`project_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 - complex: 3 passes, max 120 lines output - Each pass: 1. semantic_search (conceptual discovery) - 2. grep_search (exact pattern matching) + 2. `grep_search` (exact pattern matching) 3. Merge/deduplicate results 4. Discover relationships (dependencies, dependents, subclasses, callers, callees) 5. Expand understanding via relationships @@ -56,21 +57,21 @@ Codebase Navigation, Pattern Recognition, Dependency Mapping, Technology Stack A - Evaluate: Document confidence, coverage, gaps in research_metadata - Format: Use research_format_guide (YAML) - Verify: Completeness, format compliance -- Save: docs/plan/{plan_id}/research_findings_{focus_area}.yaml -- Log Failure: If status=failed, write to docs/plan/{plan_id}/logs/{agent}_{task_id}_{timestamp}.yaml -- Return JSON per +- Save: `docs/plan/{plan_id}/research_findings_{focus_area}.yaml` +- Log Failure: If status=failed, write to `docs/plan/{plan_id}/logs/{agent}_{task_id}_{timestamp}.yaml` +- Return JSON per `` -```json +```jsonc { "plan_id": "string", "objective": "string", "focus_area": "string", "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)" + "project_prd_path": "string (path to `docs/PRD.yaml`, for scope/acceptance criteria context)" } ``` @@ -78,7 +79,7 @@ Codebase Navigation, Pattern Recognition, Dependency Mapping, Technology Stack A -```json +```jsonc { "status": "completed|failed|in_progress|needs_revision", "task_id": null, @@ -101,66 +102,65 @@ created_at: string created_by: string status: string # in_progress | completed | needs_revision -tldr: - | # 3-5 bullet summary: key findings, architecture patterns, tech stack, critical files, open questions +tldr: | # 3-5 bullet summary: key findings, architecture patterns, tech stack, critical files, open questions research_metadata: - methodology: string # How research was conducted (hybrid retrieval: semantic_search + grep_search, relationship discovery: direct queries, sequential thinking for complex analysis, file_search, read_file, tavily_search, fetch_webpage fallback for external web content) + methodology: string # How research was conducted (hybrid retrieval: `semantic_search` + `grep_search`, relationship discovery: direct queries, sequential thinking for complex analysis, `file_search`, `read_file`, `tavily_search`, `fetch_webpage` fallback for external web content) scope: string # breadth and depth of exploration confidence: string # high | medium | low coverage: number # percentage of relevant files examined files_analyzed: # REQUIRED - - file: string - path: string - purpose: string # What this file does - key_elements: - - element: string - type: string # function | class | variable | pattern - location: string # file:line - description: string - language: string - lines: number +- file: string + path: string + purpose: string # What this file does + key_elements: + - element: string + type: string # function | class | variable | pattern + location: string # file:line + description: string + language: string + lines: number patterns_found: # REQUIRED - - category: string # naming | structure | architecture | error_handling | testing - pattern: string - description: string - examples: - - file: string - location: string - snippet: string - prevalence: string # common | occasional | rare +- category: string # naming | structure | architecture | error_handling | testing + pattern: string + description: string + examples: + - file: string + location: string + snippet: string + prevalence: string # common | occasional | rare related_architecture: # REQUIRED IF APPLICABLE - Only architecture relevant to this domain components_relevant_to_domain: - - component: string - responsibility: string - location: string # file or directory - relationship_to_domain: string # "domain depends on this" | "this uses domain outputs" + - component: string + responsibility: string + location: string # file or directory + relationship_to_domain: string # "domain depends on this" | "this uses domain outputs" interfaces_used_by_domain: - - interface: string - location: string - usage_pattern: string + - interface: string + location: string + usage_pattern: string data_flow_involving_domain: string # How data moves through this domain key_relationships_to_domain: - - from: string - to: string - relationship: string # imports | calls | inherits | composes + - from: string + to: string + relationship: string # imports | calls | inherits | composes related_technology_stack: # REQUIRED IF APPLICABLE - Only tech used in this domain languages_used_in_domain: - - string + - string frameworks_used_in_domain: - - name: string - usage_in_domain: string + - name: string + usage_in_domain: string libraries_used_in_domain: - - name: string - purpose_in_domain: string + - name: string + purpose_in_domain: string external_apis_used_in_domain: # IF APPLICABLE - Only if domain makes external API calls - - name: string - integration_point: string + - name: string + integration_point: string related_conventions: # REQUIRED IF APPLICABLE - Only conventions relevant to this domain naming_patterns_in_domain: string @@ -171,18 +171,18 @@ related_conventions: # REQUIRED IF APPLICABLE - Only conventions relevant to thi related_dependencies: # REQUIRED IF APPLICABLE - Only dependencies relevant to this domain internal: - - component: string - relationship_to_domain: string - direction: inbound | outbound | bidirectional + - component: string + relationship_to_domain: string + direction: inbound | outbound | bidirectional external: # IF APPLICABLE - Only if domain depends on external packages - - name: string - purpose_for_domain: string + - name: string + purpose_for_domain: string domain_security_considerations: # IF APPLICABLE - Only if domain handles sensitive data/auth/validation sensitive_areas: - - area: string - location: string - concern: string + - area: string + location: string + concern: string authentication_patterns_in_domain: string authorization_patterns_in_domain: string data_validation_in_domain: string @@ -190,19 +190,19 @@ domain_security_considerations: # IF APPLICABLE - Only if domain handles sensiti testing_patterns: # IF APPLICABLE - Only if domain has specific testing patterns framework: string coverage_areas: - - string + - string test_organization: string mock_patterns: - - string + - string open_questions: # REQUIRED - - question: string - context: string # Why this question emerged during research +- question: string + context: string # Why this question emerged during research gaps: # REQUIRED - - area: string - description: string - impact: string # How this gap affects understanding of the domain +- area: string + description: string + impact: string # How this gap affects understanding of the domain ``` @@ -216,9 +216,9 @@ gaps: # REQUIRED - 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 `` 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 string 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. @@ -230,15 +230,15 @@ Avoid for: Simple/medium tasks (<50 files), single-pass searches, well-defined s - Execute autonomously. Never pause for confirmation or progress report. - Multi-pass: Simple (1), Medium (2), Complex (3) -- Hybrid retrieval: semantic_search + grep_search +- Hybrid retrieval: `semantic_search` + `grep_search` - Relationship discovery: dependencies, dependents, callers - Domain-scoped YAML findings (no suggestions) -- Use sequential thinking per +- Use sequential thinking per `` - Save report; return raw JSON only - Sequential thinking tool for complex analysis tasks - Online Research Tool Usage Priorities (use if available): - For library/ framework documentation online: Use Context7 tools - - For online search: Use tavily_search for up-to-date web information - - Fallback for webpage content: Use fetch_webpage tool as a fallback (if available). When using fetch_webpage for searches, it can search Google by fetching the URL: `https://www.google.com/search?q=your+search+query+2026`. Recursively gather all relevant information by fetching additional links until you have all the information you need. + - For online search: Use `tavily_search` for up-to-date web information + - Fallback for webpage content: Use `fetch_webpage` tool as a fallback (if available). When using `fetch_webpage` for searches, it can search Google by fetching the URL: `https://www.google.com/search?q=your+search+query+2026`. Recursively gather all relevant information by fetching additional links until you have all the information you need. diff --git a/agents/gem-reviewer.agent.md b/agents/gem-reviewer.agent.md index e0b32a48..940d6eb8 100644 --- a/agents/gem-reviewer.agent.md +++ b/agents/gem-reviewer.agent.md @@ -17,15 +17,17 @@ Security Auditing, OWASP Top 10, Secret Detection, PRD Compliance, Requirements - get_errors: Validation and error detection - vscode_listCodeUsages: Security impact analysis, trace sensitive functions -- mcp_sequential-th_sequentialthinking: Attack path verification -- grep_search: Search codebase for secrets, PII, SQLi, XSS +- `mcp_sequential-th_sequentialthinking`: Attack path verification +- `grep_search`: Search codebase for secrets, PII, SQLi, XSS - semantic_search: Scope estimation and comprehensive security coverage +- READ GLOBAL RULES: If `AGENTS.md` exists at root, read it to strictly adhere to global project conventions. - Determine Scope: Use review_scope from input. Route to plan review, wave review, or task review. - IF review_scope = plan: - - Analyze: Read plan.yaml AND docs/prd.yaml (if exists) AND research_findings_*.yaml. + - Analyze: Read plan.yaml AND docs/PRD.yaml (if exists) AND research_findings_*.yaml. + - APPLY TASK CLARIFICATIONS: If task_clarifications is non-empty, validate that plan respects these clarified decisions (do NOT re-question them). - Check Coverage: Each phase requirement has ≥1 task mapped to it. - Check Atomicity: Each task has estimated_lines ≤ 300. - Check Dependencies: No circular deps, no hidden cross-wave deps, all dep IDs exist. @@ -46,12 +48,12 @@ Security Auditing, OWASP Top 10, Secret Detection, PRD Compliance, Requirements - Determine Status: any check fails=failed, all pass=completed - Return JSON per - IF review_scope = task: - - Analyze: Read plan.yaml AND docs/prd.yaml (if exists). Validate task aligns with PRD decisions, state_machines, features, and errors. Identify scope with semantic_search. Prioritize security/logic/requirements for focus_area. + - Analyze: Read plan.yaml AND docs/PRD.yaml (if exists). Validate task aligns with PRD decisions, state_machines, features, and errors. Identify scope with semantic_search. Prioritize security/logic/requirements for focus_area. - Execute (by depth): - Full: OWASP Top 10, secrets/PII, code quality, logic verification, PRD compliance, performance - Standard: Secrets, basic OWASP, code quality, logic verification, PRD compliance - Lightweight: Syntax, naming, basic security (obvious secrets/hardcoded values), basic PRD alignment - - Scan: Security audit via grep_search (Secrets/PII/SQLi/XSS) FIRST before semantic search for comprehensive coverage + - Scan: Security audit via `grep_search` (Secrets/PII/SQLi/XSS) FIRST before semantic search for comprehensive coverage - Audit: Trace dependencies, verify logic against specification AND PRD compliance (including error codes). - Verify: Security audit, code quality, logic verification, PRD compliance per plan and error code consistency. - Determine Status: Critical=failed, non-critical=needs_revision, none=completed @@ -61,7 +63,7 @@ Security Auditing, OWASP Top 10, Secret Detection, PRD Compliance, Requirements -```json +```jsonc { "review_scope": "plan | task | wave", "task_id": "string (required for task scope)", @@ -80,7 +82,7 @@ Security Auditing, OWASP Top 10, Secret Detection, PRD Compliance, Requirements -```json +```jsonc { "status": "completed|failed|in_progress|needs_revision", "task_id": "[task_id]", @@ -136,7 +138,7 @@ Security Auditing, OWASP Top 10, Secret Detection, PRD Compliance, Requirements - 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 `` 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. - Failures: Only write YAML logs on status=failed. diff --git a/plugins/gem-team/.github/plugin/plugin.json b/plugins/gem-team/.github/plugin/plugin.json index c99f7458..99d51ec3 100644 --- a/plugins/gem-team/.github/plugin/plugin.json +++ b/plugins/gem-team/.github/plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "gem-team", "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", + "version": "1.3.4", "author": { "name": "Awesome Copilot Community" },