CLAUDE

Agents Module CLAUDE.md

Purpose

Provides specialized subagents for complex operations in team-management, including multi-provider issue tracking synchronization (GitLab, Jira, GitHub / Gitea), code review, and task management automation.

Narrative Summary

The agents module implements the delegation pattern for team-management, providing specialized subagents that operate in separate context windows to handle complex, file-heavy operations. Each agent is designed for a specific domain of expertise and operates independently to avoid context pollution in the main conversation thread.

With the addition of multi-provider issue tracking integration, the agents module now includes sophisticated synchronization capabilities that handle bidirectional sync between Claude tasks and external issues (GitLab, Jira, GitHub / Gitea), including error recovery, conflict resolution, and batch operations across different providers.

Module Structure

Agent Files

• context-gathering.md - Task context manifest creation
• context-refinement.md - Session discovery integration
• code-review.md - Security and quality review; output template includes a ## ✨ Strengths (1-3) section before Critical Issues (omit section entirely if nothing genuinely stands out — no performative praise)
• spec-compliance-reviewer.md - Read-only agent that audits the git diff (including untracked files via git ls-files --others --exclude-standard) against task Success Criteria. Returns PASS/FAIL verdict with per-criterion coverage breakdown and scope-creep flags; the coverage report is keyed on SC-IDs (SC-1, SC-2, ...) when criteria carry them, falling back to verbatim criterion text for unnumbered/legacy tasks (incl. the ## Criteria short form). Output is structured so the orchestrator can write the SPEC_REVIEW: PASSED sentinel via protocol_save_note, which gates the code-review step's post_func require_spec_review_passed. Tools: Read, Grep, Glob, Bash.
• code-cleanliness.md - Code quality and maintainability analysis
• code-explorer.md - Existing codebase feature analysis and execution flow tracing
• code-architect.md - Architecture design and implementation blueprints
• logging.md - Work log consolidation and cleanup
• service-documentation.md - CLAUDE.md file maintenance
• critic.md - Devil's advocate analysis for proposals and brainstorm topics
• user-perspective.md - End-user impact and UX analysis
• risk-security-analyst.md - Combined risk, dependency, and security assessment
• scope-strategist.md - Scope definition and implementation phasing
• codex-cli.md - Pass-through wrapper agent that shells out to the codex CLI (codex review --uncommitted for review, codex exec -s read-only for exec); the caller owns the full prompt. Each codex invocation runs under an env -i PATH HOME scrub so plugin userConfig secrets are not inherited. Full contract (timeout fallback, sandbox, output shape) in the root CLAUDE.md "AI Provider Integration".
• agy-cli.md - Pass-through wrapper agent that shells out to the Google Antigravity (agy) CLI (agy --add-dir "$PWD" --dangerously-skip-permissions --print-timeout 300s -p ... — NO --sandbox, which breaks git on macOS) behind a 330s external watchdog. skip-permissions gets past the headless soft-deny and is CONTAINED by a project-local .agents/hooks.json read-only deny-gate (deployed by shared_state.ensure_agy_readonly_gate_deployed when agy is enabled); the wrapper preflight-verifies the gate and refuses to run uncontained. Snapshots git status/git diff HEAD before-and-after and prepends an agy review WARNING: agy modified files... line if agy mutated files (detect & report, never auto-revert). Runs under the same env -i PATH HOME scrub; failure surfaces as agy review unavailable: <reason>. Full contract (watchdog fallback, mutation-check details) in the root CLAUDE.md "AI Provider Integration".
• Provider Extensibility: Agent system supports future issue tracking provider agents