Imported from pkodzis/hcpctl (.github/AGENTS.md). Install upstream with npx skills add pkodzis/hcpctl --skill .github. Copyright stays with the author.

hcpctl — Custom Agents Registry

Agent Architecture

User
 ├── @feature         (end-to-end coordinator, orchestrates all phases)
 │    ├── subagent → design     (requirements + plan, read-only)
 │    ├── subagent → critic     (plan review, iterates with design, different model)
 │    ├── subagent → api-perf   (API query efficiency review, iterates with design)
 │    ├── subagent → implement  (Rust/clap implementation)
 │    ├── subagent → test       (coverage gaps, write missing tests)
 │    └── subagent → review     (post-implementation verification, different model)
 ├── @design          (analysis + planning, read-only, handoff to @feature)
 ├── @implement       (feature implementation, standalone or subagent)
 ├── @test            (test coverage, standalone or subagent)
 ├── @review          (code review, standalone or subagent)
 ├── @guide           (docs/src/guides maintainer, analysis-first, dynamic coverage)
 └── @code_review     (comprehensive code review orchestrator)
      ├── subagent → code_review_duplicates  (find duplicate patterns)
      ├── subagent → code_review_dead_code   (unused exports, dead code)
      ├── subagent → code_review_errors      (error handling consistency)
      └── subagent → code_review_security    (security vulnerabilities)

Agent Catalog

Feature Pipeline Agents

Code Review Agents

Model diversity: Design, implementation, and api-perf use Claude Opus 4.6 for deep reasoning. Critic uses Gemini 3.1 Pro for independent perspective during plan review. Review and code review analyzers use GPT-5.3-Codex for post-implementation verification — different models catch different issues.

Key access controls:

• Feature has disable-model-invocation: true — only user-invokable, never spawned as a subagent
• Critic has user-invokable: false — only feature spawns it, never appears in the dropdown
• Feature declares agents: [design, critic, api-perf, implement, test, review] — explicit subagent allowlist
• api-perf has user-invokable: false — only feature spawns it after design↔critic converge
• Design has a handoff to feature — after user reviews the plan, one click to start execution
• code_review has disable-model-invocation: true — only user-invokable, never a subagent
• All 4 code_review_* analyzers have user-invokable: false — only code_review orchestrator spawns them

Workflow Patterns

Pattern 1: Full Automation (recommended for new features)

1. Switch to @feature — describe what you want
2. Feature creates .feature-runs/<timestamp>-<slug>/ forensic trail directory
3. Feature runs the full pipeline autonomously, saving every subagent output:
   • Design↔Critic loop (max 7 iterations until APPROVE or consensus)
   • API Performance Review — api-perf validates API call efficiency (max 3 iterations with design)
   • Human Gate — plan presented to user for approval before implementation
   • Implement the approved plan
   • Test — fill coverage gaps
   • Review — final quality check
   • Fix loop — if review finds bugs/violations (max 2 rounds)
4. Delivers final report (to trail + chat)

Pattern 2: Design First (for complex tasks needing human review of plan)

1. Switch to @design — describe requirements
2. Review the plan yourself
3. Click Execute Plan handoff button → switches to @feature
4. Feature creates forensic trail, takes over from Phase 2 (implement → test → review)

Pattern 3: Specialist (for focused work)

Switch directly to @implement, @test, or @review for targeted tasks.

Pattern 4: Comprehensive Code Review

1. Switch to @code_review — optionally describe focus areas
2. Orchestrator spawns all 4 analyzers in parallel:
   • Duplicates, Dead Code, Error Handling, Security
3. Collects all findings, deduplicates, prioritizes
4. Writes ./code-review-<timestamp>.md with full report
5. Presents executive summary

Design ↔ Critic Iterative Loop

The @feature coordinator runs a peer-review loop between design and critic:

feature (coordinator)
 ├── 1. Spawn design    → produces plan
 ├── 2. Spawn critic    → reviews plan (verdict: APPROVE or REVISE)
 ├── 3. If REVISE: send critic's issues back to design
 ├── 4. Repeat steps 2-3 (max 7 iterations)
 ├── 5. Spawn api-perf  → reviews API query efficiency (verdict: APPROVE or REJECT)
 ├── 6. If REJECT: send api-perf feedback to design, then re-review (max 3 iterations)
 ├── 7. Human gate      → present plan to user, wait for approval
 └── 8. Proceed to implementation

• Convergence: Critic issues APPROVE when all issues are resolved or only LOW severity remain
• No consensus: If 7 iterations reached without APPROVE, feature coordinator proceeds with latest plan and documents unresolved disagreements
• API perf: After design↔critic converge, api-perf reviews for fetch-all-filter-locally anti-patterns, server-side filtering opportunities, query order optimization
• Human gate: Plan is presented to user for approval before implementation begins

Retry Policy

The feature coordinator NEVER assumes a failed subagent's role:

1. Retry same subagent with error context appended (up to 3 attempts)
2. After 3 failures, document the failure and skip that phase
3. Never attempt the work directly — specialists exist for a reason

Conventions

• Agent files: .github/agents/<name>.agent.md
• All agents inherit copilot-instructions.md (tech stack, top rules, key conventions)
• Guide agent maintains docs/src/guides/*.md dynamically (no hardcoded topic list)
• Worker agents (implement, test, review) have default flags — user-invokable and subagent-ready
• Feature has disable-model-invocation: true — only user-invokable, never a subagent
• Critic has user-invokable: false — only feature spawns it, never user-facing
• Design has handoffs to feature — guided workflow from plan to execution
• code_review has disable-model-invocation: true — coordinator only, never a subagent
• code_review_* analyzers have user-invokable: false — spawned only by code_review orchestrator
• code_review output goes to ./code-review-<timestamp>.md (gitignored)
• Feature forensic trails go to .feature-runs/<timestamp>-<slug>/ (gitignored)

Forensic Trail

Every @feature run creates a full audit trail in .feature-runs/<timestamp>-<slug>/:

.feature-runs/20260223-143021-add-get-variables/
  00-request.md              # original request (verbatim)
  01-design-v1.md            # first design output
  02-critic-v1.md            # first critic review
  03-design-v2.md            # revised design (if REVISE)
  04-critic-v2.md            # second review (if needed)
  ...
  NN-api-perf-v1.md          # API performance review
  NN-plan-approved.md        # final plan (+ disagreements if no consensus)
  NN-implement.md            # implementation log
  NN-test.md                 # test audit
  NN-review.md               # review findings
  NN-report.md               # final summary (ALWAYS LAST)

This is NOT project documentation — it is process forensics. Every subagent's complete raw output is preserved so design decisions, trade-offs, and iteration history can be reconstructed after the fact.

Adding a New Agent

1. Create .github/agents/<name>.agent.md
2. Add YAML frontmatter: description, model, tools, agents (if coordinator), handoffs (if workflow)
3. Update this file (catalog table + architecture diagram)