Skip to content

feat: Phase 2 CWE-78 Incident Remediation - Operational Capabilities#20

Merged
rjmurillo merged 13 commits into
mainfrom
enhancement/4-phase-2
Dec 14, 2025
Merged

feat: Phase 2 CWE-78 Incident Remediation - Operational Capabilities#20
rjmurillo merged 13 commits into
mainfrom
enhancement/4-phase-2

Conversation

@rjmurillo

Copy link
Copy Markdown
Owner

Summary

Complete implementation of Phase 2 for CWE-78 Incident Remediation (Issue #4). This PR implements all 6 operational capability issues that build on Phase 1's foundation work.

Changes

Issue #6: Agent Interview Protocol

  • Created .agents/governance/agent-interview-protocol.md with 8 standardized questions
  • Added response template and sample security agent interview
  • Enables systematic capability discovery for all agents

Issue #5: Orchestrator Routing Logic

  • Created docs/task-classification-guide.md for task type/complexity/risk classification
  • Created docs/orchestrator-routing-algorithm.md with explicit routing pseudocode
  • Added visual flowcharts in docs/diagrams/routing-flowchart.md
  • Updated orchestrator agents on all 3 platforms with routing rules

Issue #10: Security Agent Enhancement

  • Expanded security agent to 5 capabilities:
    • Static analysis (CWE patterns)
    • Secret detection
    • Code quality metrics
    • Architecture audits
    • Security best practices
  • Updated security agents on all 3 platforms

Issue #8: Governance Framework

  • Created ADR template with agent-specific fields
  • Established steering committee charter
  • Documented 6 agent design principles
  • Created agent consolidation process
  • Added public governance overview

Issue #9: Auto-trigger Security Agent

  • Created infrastructure file pattern detection (10 categories)
  • Implemented detection scripts (Python and PowerShell)
  • Integrated into pre-commit hook (non-blocking warning)
  • Added security review section to PR template

Issue #7: Agent Invocation Metrics

  • Defined 8 key metrics in docs/agent-metrics.md
  • Created baseline report with pre-Phase 2 measurements
  • Added dashboard template for monthly reporting
  • Implemented collection scripts (Python and PowerShell)
  • Created CI workflow for weekly automated collection

Type of Change

  • New feature (non-breaking change adding functionality)
  • Infrastructure/CI change
  • Documentation update

Testing

  • Manual testing completed
  • Pre-commit hooks validate markdown
  • Security detection confirmed working in commit output
  • Metrics scripts tested locally

Agent Review

Security Review

Required for: Authentication, authorization, CI/CD, git hooks, secrets, infrastructure

  • Security agent reviewed infrastructure changes
  • Security patterns applied (see .agents/security/)

Files requiring security review:

  • .github/workflows/agent-metrics.yml
  • .githooks/pre-commit
  • .agents/utilities/security-detection/detect_infrastructure.py

Other Agent Reviews

  • Architect reviewed design changes
  • Critic validated implementation plan

Checklist

  • Code follows project style guidelines
  • Self-review completed
  • Comments added for complex logic
  • Documentation updated (if applicable)
  • No new warnings introduced

Related Issues

Fixes #4 (Phase 2)
Fixes #5
Fixes #6
Fixes #7
Fixes #8
Fixes #9
Fixes #10


🤖 Generated with Claude Code

rjmurillo and others added 7 commits December 13, 2025 23:05
Add agent interview protocol for standardized capability discovery:
- 8 standardized questions for comprehensive agent documentation
- Interview response template for consistent formatting
- Sample security agent interview demonstrating the format
- Phase 2 implementation plan for all related issues

This establishes the foundation for maintaining accurate agent
capabilities and enabling accurate orchestrator routing.

Closes #6

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Add explicit routing algorithm for task-to-agent assignment:
- Task classification guide with type/complexity/risk dimensions
- Orchestrator routing algorithm with pseudocode implementation
- Visual routing flowchart for quick reference
- Updated orchestrator agents on all 3 platforms with routing references

The algorithm validates against the CWE-78 incident scenario and would
have correctly routed the task through security + devops agents.

Closes #5

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Add comprehensive security audit capabilities:
- Capability 1: Static analysis checklist with CWE patterns
- Capability 2: Secret detection patterns for credentials/tokens
- Capability 3: Code quality security guide for complexity metrics
- Capability 4: Architecture security audit template
- Capability 5: Security best practices enforcement guide

Updated security agent on all 3 platforms (Claude, VS Code, Copilot CLI)
with references to new capability documentation.

Closes #10

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Add comprehensive governance framework for agent system evolution:
- ADR template with agent-specific fields for proposals
- Steering committee charter with roles and decision processes
- Agent design principles (6 core principles)
- Agent consolidation process with triggers and procedures
- Public governance overview documentation

This establishes formal processes for adding, modifying, and
consolidating agents to maintain system health.

Closes #8

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Add infrastructure file detection and security review triggers:
- Infrastructure file patterns documentation with 10 categories
- Security detection utility (PowerShell and Python versions)
- Pre-commit hook integration (non-blocking warning)
- PR template with security review checklist

When infrastructure or security-critical files are changed,
developers see a warning recommending security agent review.

Closes #9

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Fixes #7

Implement the 8 key metrics for measuring agent system health:
- Metric 1: Invocation Rate by Agent
- Metric 2: Agent Coverage
- Metric 3: Shift-Left Effectiveness (baseline documented)
- Metric 4: Infrastructure Code Review Rate
- Metric 5: Usage Distribution by Agent
- Metric 6: Agent Review Turnaround Time (baseline documented)
- Metric 7: Vulnerability Discovery Timeline (baseline documented)
- Metric 8: Compliance with Agent Policies (baseline documented)

Artifacts created:
- docs/agent-metrics.md: Metric definitions and measurement methods
- .agents/metrics/baseline-report.md: Pre-Phase 2 baseline measurements
- .agents/metrics/dashboard-template.md: Monthly reporting template
- .agents/utilities/metrics/collect_metrics.py: Python collection script
- .agents/utilities/metrics/collect-metrics.ps1: PowerShell collection script
- .agents/utilities/metrics/SKILL.md: Usage documentation
- .github/workflows/agent-metrics.yml: Weekly automated collection

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Copilot AI review requested due to automatic review settings December 14, 2025 07:49

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

This PR implements Phase 2 of the CWE-78 Incident Remediation effort, building operational capabilities on top of Phase 1's foundation work. The implementation addresses 6 issues (#5-#10) to enhance the multi-agent system's security, routing, governance, and observability capabilities. The changes are well-structured, comprehensive, and demonstrate a systematic approach to preventing future security incidents like the CWE-78 shell injection that motivated this work.

Key changes:

  • Enhanced security agent with 5 comprehensive capabilities spanning vulnerability scanning, secret detection, code quality auditing, architecture security, and best practices enforcement
  • Introduced explicit orchestrator routing algorithm with task classification, complexity assessment, and risk-level determination
  • Established governance framework including ADR templates, steering committee charter, agent design principles, and consolidation processes
  • Implemented automated security detection for infrastructure changes with pre-commit hook integration and PR template updates
  • Created metrics collection system tracking 8 key metrics for agent system health and effectiveness
  • Developed agent interview protocol with standardized questions for capability discovery

Reviewed changes

Copilot reviewed 37 out of 37 changed files in this pull request and generated 2 comments.

Show a summary per file
File Description
vs-code-agents/security.agent.md Expanded security agent with 5 capabilities replacing simple responsibilities list
claude/security.md Identical security agent expansion for Claude platform
copilot-cli/security.agent.md Security agent expansion for Copilot CLI (consistency across platforms)
vs-code-agents/orchestrator.agent.md Added routing algorithm references, quick classification table, and mandatory routing rules
claude/orchestrator.md Orchestrator updates matching VS Code version
copilot-cli/orchestrator.agent.md Orchestrator updates for Copilot CLI platform
docs/task-classification-guide.md Comprehensive guide for classifying tasks by type, complexity, and risk level
docs/orchestrator-routing-algorithm.md Detailed routing algorithm with pseudocode and decision logic
docs/diagrams/routing-flowchart.md Visual flowcharts for routing decisions and classification
docs/agent-metrics.md Definition of 8 key metrics for agent system observability
docs/agent-governance.md Public overview of governance framework and processes
.github/workflows/agent-metrics.yml CI workflow for automated weekly metrics collection
.github/PULL_REQUEST_TEMPLATE.md PR template with security review checkboxes
.githooks/pre-commit Integration of security detection warning (non-blocking)
.agents/utilities/security-detection/detect_infrastructure.py Python script for detecting security-critical file changes
.agents/utilities/security-detection/detect-infrastructure.ps1 PowerShell equivalent of detection script
.agents/utilities/security-detection/SKILL.md Documentation for security detection utility
.agents/utilities/metrics/collect_metrics.py Python script for collecting agent metrics from git history
.agents/utilities/metrics/collect-metrics.ps1 PowerShell equivalent of metrics collection
.agents/utilities/metrics/SKILL.md Documentation for metrics collection utility
.agents/security/*.md (5 files) Detailed security capability documentation (static analysis, secrets, code quality, architecture, best practices)
.agents/security/infrastructure-file-patterns.md Pattern definitions for infrastructure file detection
.agents/metrics/dashboard-template.md Template for monthly metrics dashboards
.agents/metrics/baseline-report.md Baseline measurements establishing pre-Phase 2 state
.agents/governance/*.md (6 files) Governance framework documents including ADR template, charter, principles, consolidation process, interview protocol
.agents/planning/phase-2-implementation-plan.md Comprehensive implementation plan for Phase 2
CLAUDE.md Updated with note about using codebase-context tools

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Comment thread .agents/utilities/metrics/collect_metrics.py
Comment thread .agents/utilities/metrics/collect_metrics.py Outdated
@coderabbitai

coderabbitai Bot commented Dec 14, 2025

Copy link
Copy Markdown

Note

Other AI code review bot(s) detected

CodeRabbit has detected other AI code review bot(s) in this pull request and will avoid duplicating their findings in the review comments. This may lead to a less comprehensive review.

📝 Walkthrough

Walkthrough

Adds a non-blocking security-detection step to the pre-commit hook, a new PR template, a weekly/manual agent-metrics GitHub Actions workflow, a markdownlint exclusion, and extensive documentation for agent governance, routing, metrics, classification, and security-agent capabilities. Only executable changes: the pre-commit hook and the workflow.

Changes

Cohort / File(s) Summary
Pre-commit hook
\.githooks/pre-commit
Runs an optional SECURITY_DETECTION_SCRIPT (uses python3 if available, else python) after markdown linting when the path exists and is not a symlink; invocation is non-blocking (exit status ignored).
CI / Metrics workflow
\.github/workflows/agent-metrics.yml
Adds weekly/manual GitHub Actions workflow that checks out code, sets up Python 3.11, runs a metrics collection script for a configurable window, produces metrics-report.txt (and JSON optionally), appends formatted job summaries, uploads a metrics artifact, and optionally runs a threshold check emitting warnings for coverage/infra-rate breaches.
Markdown lint config
\.markdownlint-cli2.yaml
Adds exclusion glob !.serena/memories/** to ignore markdown under that path from linting.
PR template
\.github/PULL_REQUEST_TEMPLATE.md
Adds standardized PR template with Summary, Changes, Type of Change checklist, Testing, Agent Review (security review prompts and files requiring security review), Checklist, Related Issues, and optional UI screenshot note.
Agent governance & processes
docs/agent-governance.md, CLAUDE.md
New governance document defining design principles, agent lifecycle, ADR process, consolidation triggers, steering committee, thresholds, and quick-reference criteria; small editorial additions to CLAUDE.md.
Routing / orchestrator docs
docs/orchestrator-routing-algorithm.md, docs/diagrams/routing-flowchart.md, docs/task-classification-guide.md
Adds a four-phase routing algorithm (classify, select, execute, synthesize), decision matrices, Python examples, ASCII flowcharts, task classification guide (type/complexity/risk), validation examples (including CWE-78).
Agent metrics docs
docs/agent-metrics.md
New metrics doc defining 8 invocation metrics, formulas, collection methods, targets, dashboard templates, and sampling cadence.
Orchestrator agent docs
claude/orchestrator.md, copilot-cli/orchestrator.agent.md, vs-code-agents/orchestrator.agent.md
Expands orchestrator agent docs with new agent categories (security, devops, explainer), routing heuristics, quick classification table, mandatory agent rules, and handoff protocol guidance.
Security agent docs
claude/security.md, copilot-cli/security.agent.md, vs-code-agents/security.agent.md
Replaces a generic responsibility list with five explicit security capabilities (static analysis, secret detection, code-quality/security audit, architecture/boundary review, best-practices enforcement) with detailed bullets and references.

Sequence Diagram(s)

mermaid
sequenceDiagram
autonumber
participant Dev as Developer (local)
participant Hook as .githooks/pre-commit
participant Markdown as markdownlint
participant SecScript as SECURITY_DETECTION_SCRIPT (python)
Note over Hook,SecScript: Pre-commit flow (non-blocking security check)
Dev->>Hook: git commit
Hook->>Markdown: run markdownlint
Markdown-->>Hook: exit (pass/fail)
Hook->>SecScript: if path exists && not symlink -> invoke (python3|python) --git-staged
SecScript-->>Hook: exit (ignored)
Hook-->>Dev: allow commit to proceed

mermaid
sequenceDiagram
autonumber
participant GH as GitHub Actions Runner
participant Repo as Repository
participant Python as Python 3.11 environment
participant Metrics as metrics collection script
participant Artifact as GitHub Artifacts
Note over GH,Artifact: Weekly/manual metrics workflow
GH->>Repo: checkout (full history)
GH->>Python: setup python 3.11
GH->>Metrics: run collect_metrics(days, format)
Metrics-->>GH: metrics-report.txt / metrics.json
GH->>GH: append formatted summary (render JSON if requested)
GH->>Artifact: upload metrics-report.txt (retention 90 days)
alt threshold-check enabled
GH->>Metrics: run metrics in JSON mode
Metrics-->>GH: coverage, infra_rate
GH->>GH: compute alerts, post warnings in job summary
end

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

  • Areas needing attention:
    • \.githooks/pre-commit: verify safe path checks, symlink handling, python selection, and explicit ignoring of script exit codes.
    • \.github/workflows/agent-metrics.yml: check period calculation, artifact retention, JSON vs text handling, and threshold computation logic.
    • Documentation consistency: thresholds and triggers in governance, metrics, and routing docs should align and be measurable.

Possibly related issues

  • rjmurillo/vs-code-agents#19 — Security agent expansion: this PR adds the non-blocking SECURITY_DETECTION_SCRIPT invocation targeting the same pre-commit detection point.
  • rjmurillo/vs-code-agents#20 — Auto-trigger security for infra/auth: the pre-commit non-blocking detection and PR template items map to the requested warning/auto-trigger behavior.
  • rjmurillo/vs-code-agents#21 — Governance framework: addressed by docs/agent-governance.md.
  • rjmurillo/vs-code-agents#22 — Metrics & observability: addressed by docs/agent-metrics.md and the agent-metrics workflow.
  • rjmurillo/vs-code-agents#24 / #5 — Orchestrator routing algorithm: addressed by docs/orchestrator-routing-algorithm.md and routing diagrams.
  • rjmurillo/vs-code-agents#25 — Pre-commit security detection behavior: directly related to the pre-commit change.
  • feat: Add markdown linting requirements for agent templates #14 — Markdown linting and pre-commit overlap: related to pre-commit hook and markdownlint exclusion.

Pre-merge checks and finishing touches

✅ Passed checks (5 passed)
Check name Status Explanation
Title check ✅ Passed Title follows conventional commit format (feat: ...) and accurately describes Phase 2 implementation of CWE-78 remediation with operational capabilities.
Description check ✅ Passed Description comprehensively outlines all 6 Phase 2 issues with specific files, changes, and testing performed; clearly related to changeset.
Linked Issues check ✅ Passed PR implementation covers all linked issues (#5-#10): routing algorithm, interview protocol, security enhancement, governance framework, auto-trigger detection, and metrics. All objectives from parent issue #4 Phase 2 are addressed.
Out of Scope Changes check ✅ Passed Changes align with Phase 2 scope: documentation, governance artifacts, automation integration, agent enhancements, and metrics. Minor edits to CLAUDE.md and .markdownlint-cli2.yaml support the core objectives.
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
✨ Finishing touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Post copyable unit tests in a comment
  • Commit unit tests in branch enhancement/4-phase-2

📜 Recent review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between c41ca44 and 9ef49d8.

⛔ Files ignored due to path filters (3)
  • .serena/memories/coderabbit-config-optimization-strategy.md is excluded by !.serena/**
  • .serena/memories/coderabbit-noise-reduction-research.md is excluded by !.serena/**
  • .serena/memories/pr-review-noise-skills.md is excluded by !.serena/**
📒 Files selected for processing (1)
  • CLAUDE.md (1 hunks)
🚧 Files skipped from review as they are similar to previous changes (1)
  • CLAUDE.md
🧰 Additional context used
🔍 Remote MCP DeepWiki

Summary of additional repository context most relevant to reviewing this PR

  • Agent system overview: repo provides 18 specialized agents (orchestrator, analyst, architect, implementer, security, etc.) with 1:1 parity across three platform implementations (vs-code-agents/, copilot-cli/, claude/). Agents coordinate via explicit handoffs and write artifacts to a standardized .agents/ directory structure.,

  • Memory & skill system: agents use a memory-first protocol backed by cloudmcp-manager (tools: memory-search_nodes, memory-open_nodes, memory-create_entities, memory-add_observations, memory-create_relations). Skill/retrospective flows use atomicity scoring (95–100/70–94/40–69/<40) to decide what learnings become persistent skills. This matters for PR changes that affect memory or skill citation (e.g., new PR template entries, where to record auto-detections).

  • Output locations & naming conventions: All agents save artifacts under .agents/ with strict patterns (e.g., .agents/architecture/ ADR-NNN-.md, .agents/planning/ NNN--plan.md, .agents/analysis/ NNN--analysis.md, .agents/qa/ NNN--test-report.md, .agents/retrospective/YYYY-MM-DD-*.md). PR should reference these paths for generated metrics, reports, or security docs.

  • Installation & scripts: repo includes installation scripts (scripts/install-*.ps1) that deploy agents and create the .agents/ scaffold; per-repo install is the recommended/required pattern for Copilot CLI. Verify PR changes align with those scripts if they alter agent files or add new directories.

  • Platform parity / drift detection: any semantic changes to an agent's core identity, responsibilities, handoffs, memory protocol, constraints, output dirs, skill-citation format, or atomicity scoring MUST be mirrored across the three platform implementations. The repository enforces a drift-detection / review checklist (.github/copilot-code-review.md). For this PR (many agent docs changed + pre-commit hook), ensure core behavior changes (e.g., security capability definitions, routing algorithm) are synchronized across vs-code-agents/, copilot-cli/, and claude/.

  • Orchestrator & routing docs: PR adds detailed orchestrator routing algorithm, task classification, flowcharts, and pseudocode — these are high-impact behavioral documents that the orchestrator agent, planner, critic, and security agent implementations must reflect consistently. Confirm that examples/pseudocode align with agent definitions and handoff rules.

  • Pre-commit / auto-trigger relevance: repository already uses agent-driven workflows and memory-first patterns; the PR's non-blocking SECURITY_DETECTION_SCRIPT addition to .githooks/pre-commit fits the existing design (non-blocking warnings, shift-left objective). Ensure the hook's behavior, message text, and any files listed in PR template map to the agent detection patterns and the documented file patterns (infrastructure/auth paths) so automation and metrics can pick them up.

  • Metrics & CI artifacts: docs/agent-metrics.md and the new workflow (agent-metrics.yml) expect artifacts and standardized outputs (metrics-report.txt, JSON). Confirm workflow uploads and artifact names match the output directory conventions and that the metrics script paths reflect the installed scripts and .agents/ locations.

  • Known platform caveat: GitHub Copilot CLI global installation is broken (Issue [ALERT] PR Maintenance Workflow Failed #452) so any reviewer testing agent installs should use per-repo installation; CI/test guidance in PR should reflect that.

Quick reviewer actions to reduce drift/risk

  • Verify all semantic changes to agent behavior (security capabilities, routing rules, interview protocol, metric definitions) are present in all three platform directories (vs-code-agents/, copilot-cli/, claude/).
  • Confirm .githooks/pre-commit change only warns (non-blocking) and its output/paths are referenced in the PR template and agent-detection docs so metrics and memory entries can be correlated.
  • Ensure new docs produce artifacts under .agents/ with correct filenames and that agent-metrics workflow references those paths exactly.
  • Run installation scripts (per-repo) and exercise key agent invocations (orchestrator → security) to validate handoff and memory-create behavior for the new auto-detection flow (use per-repo install; Copilot CLI global install is unreliable).

Sources used

  • DeepWiki repository wiki structure listing and full wiki contents for rjmurillo/vs-code-agents:,

Comment @coderabbitai help to get the list of available commands and usage tips.

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 7

📜 Review details

Configuration used: CodeRabbit UI

Review profile: ASSERTIVE

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between fb1a5be and 0f298ab.

⛔ Files ignored due to path filters (22)
  • .agents/architecture/ADR-TEMPLATE.md is excluded by !.agents/**
  • .agents/governance/agent-consolidation-process.md is excluded by !.agents/**
  • .agents/governance/agent-design-principles.md is excluded by !.agents/**
  • .agents/governance/agent-interview-protocol.md is excluded by !.agents/**
  • .agents/governance/interview-response-template.md is excluded by !.agents/**
  • .agents/governance/interviews/security-interview.md is excluded by !.agents/**
  • .agents/governance/steering-committee-charter.md is excluded by !.agents/**
  • .agents/metrics/baseline-report.md is excluded by !.agents/**
  • .agents/metrics/dashboard-template.md is excluded by !.agents/**
  • .agents/planning/phase-2-implementation-plan.md is excluded by !.agents/**
  • .agents/security/architecture-security-template.md is excluded by !.agents/**
  • .agents/security/code-quality-security.md is excluded by !.agents/**
  • .agents/security/infrastructure-file-patterns.md is excluded by !.agents/**
  • .agents/security/secret-detection-patterns.md is excluded by !.agents/**
  • .agents/security/security-best-practices.md is excluded by !.agents/**
  • .agents/security/static-analysis-checklist.md is excluded by !.agents/**
  • .agents/utilities/metrics/SKILL.md is excluded by !.agents/**
  • .agents/utilities/metrics/collect-metrics.ps1 is excluded by !.agents/**
  • .agents/utilities/metrics/collect_metrics.py is excluded by !.agents/**
  • .agents/utilities/security-detection/SKILL.md is excluded by !.agents/**
  • .agents/utilities/security-detection/detect-infrastructure.ps1 is excluded by !.agents/**
  • .agents/utilities/security-detection/detect_infrastructure.py is excluded by !.agents/**
📒 Files selected for processing (15)
  • .githooks/pre-commit (1 hunks)
  • .github/PULL_REQUEST_TEMPLATE.md (1 hunks)
  • .github/workflows/agent-metrics.yml (1 hunks)
  • CLAUDE.md (1 hunks)
  • claude/orchestrator.md (2 hunks)
  • claude/security.md (1 hunks)
  • copilot-cli/orchestrator.agent.md (2 hunks)
  • copilot-cli/security.agent.md (1 hunks)
  • docs/agent-governance.md (1 hunks)
  • docs/agent-metrics.md (1 hunks)
  • docs/diagrams/routing-flowchart.md (1 hunks)
  • docs/orchestrator-routing-algorithm.md (1 hunks)
  • docs/task-classification-guide.md (1 hunks)
  • vs-code-agents/orchestrator.agent.md (2 hunks)
  • vs-code-agents/security.agent.md (1 hunks)
🧰 Additional context used
🪛 LanguageTool
docs/orchestrator-routing-algorithm.md

[uncategorized] ~365-~365: The official name of this software platform is spelled with a capital “H”.
Context: ... - docker-compose*.yml - *.yml (in .github) ### Research Indicators Keywords...

(GITHUB)

docs/task-classification-guide.md

[grammar] ~196-~196: Use a hyphen to join words.
Context: ...hanges with test coverage - Feature flag protected changes - Internal tooling mod...

(QB_NEW_EN_HYPHEN)


[uncategorized] ~236-~236: The official name of this software platform is spelled with a capital “H”.
Context: ...ug Fix | Simple/Multi-Step | Medium | | .github/workflows/* | Infrastructure | Multi-D...

(GITHUB)

claude/orchestrator.md

[uncategorized] ~128-~128: The official name of this software platform is spelled with a capital “H”.
Context: ...ecurity, architect, implementer, qa | | .github/workflows/*, .githooks/* | Infrastru...

(GITHUB)

.github/PULL_REQUEST_TEMPLATE.md

[style] ~15-~15: Consider using a different verb for a more formal wording.
Context: ...nge - [ ] Bug fix (non-breaking change fixing an issue) - [ ] New feature (non-breaki...

(FIX_RESOLVE)

copilot-cli/orchestrator.agent.md

[uncategorized] ~117-~117: The official name of this software platform is spelled with a capital “H”.
Context: ...ecurity, architect, implementer, qa | | .github/workflows/*, .githooks/* | Infrastru...

(GITHUB)

🪛 markdownlint-cli2 (0.18.1)
vs-code-agents/orchestrator.agent.md

117-117: Fenced code blocks should have a language specified

(MD040, fenced-code-language)


107-107: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

docs/task-classification-guide.md

189-189: Fenced code blocks should have a language specified

(MD040, fenced-code-language)


117-117: Fenced code blocks should have a language specified

(MD040, fenced-code-language)


107-107: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

docs/diagrams/routing-flowchart.md

189-189: Fenced code blocks should have a language specified

(MD040, fenced-code-language)


117-117: Fenced code blocks should have a language specified

(MD040, fenced-code-language)


107-107: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

docs/agent-metrics.md

189-189: Fenced code blocks should have a language specified

(MD040, fenced-code-language)


117-117: Fenced code blocks should have a language specified

(MD040, fenced-code-language)


107-107: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

claude/orchestrator.md

117-117: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

copilot-cli/orchestrator.agent.md

117-117: Fenced code blocks should have a language specified

(MD040, fenced-code-language)


107-107: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

🔇 Additional comments (16)
CLAUDE.md (1)

165-166: LGTM - Clear guideline addition.

The new guideline to check team patterns using codebase-context tools before code generation/review is practical and well-placed in the utilities section.

.github/PULL_REQUEST_TEMPLATE.md (1)

1-69: LGTM - Comprehensive PR template with strong security focus.

The template effectively integrates security review requirements with clear checkboxes and file listing prompts. The structure supports the PR's objective to ensure infrastructure and auth changes receive security review.

docs/diagrams/routing-flowchart.md (1)

368-408: LGTM - Excellent practical example.

The CWE-78 routing example effectively demonstrates the four-phase routing process with concrete agent selections and handoffs, making the abstract flowcharts actionable.

claude/orchestrator.md (2)

115-138: LGTM - Clear routing guidance with actionable rules.

The new routing algorithm section with quick classification table and mandatory agent rules provides concrete decision-making criteria. The requirement for security agent on **/Auth/** and .githooks/* files directly supports the CWE-78 remediation objectives.


111-113: Security, devops, and explainer agent descriptions align well.

The updated capability matrix entries clearly define each agent's primary function and best-use cases, supporting improved routing decisions.

claude/security.md (1)

28-66: LGTM - Consistent capability structure across platforms.

The security agent capabilities are consistently defined across Claude and Copilot platforms, ensuring uniform security coverage. The five capabilities (static analysis, secret detection, code quality, architecture audit, best practices) comprehensively address security concerns.

Note: The same documentation file references should be verified as mentioned in the review of copilot-cli/security.agent.md.

docs/agent-governance.md (3)

17-26: LGTM - Clear and measurable design principles.

The six design principles provide specific, actionable criteria for agent design. The 20% overlap threshold and 30-second entry criteria are concrete and testable, supporting effective governance.


39-47: LGTM - Specific consolidation thresholds.

The consolidation triggers use measurable thresholds (>20% overlap, <5% invocations, >3 misroutes/month) that enable objective decision-making about agent lifecycle management.


9-15: Verify governance artifact files exist.

The governance artifacts table references several foundational documents. Ensure these files are created as part of this PR or are tracked in related issues.

docs/agent-metrics.md (1)

1-300: Well-structured metrics documentation with clear definitions and measurement strategies.

The 8 metrics are clearly defined with formulas, collection methods, targets, and baselines. Cross-references to related documentation and CI workflow are consistent and actionable. Once you address the markdown linting (missing language identifiers), this file is ready.

docs/task-classification-guide.md (1)

1-374: Comprehensive and actionable task classification framework aligned with PR objectives.

The three-dimension classification (Type, Complexity, Risk) is clear, the examples are concrete (including the CWE-78 incident), and the decision flowchart makes routing explicit. The framework directly supports the orchestrator routing algorithm and agent selection documented elsewhere in the PR.

vs-code-agents/security.agent.md (1)

18-56: Well-structured capability model for security agent.

Restructuring responsibilities into five explicit, documented capabilities (Static Analysis, Secret Detection, Code Quality, Architecture Audit, Best Practices) makes agent routing more precise and measurable. Each capability has a clear scope and supporting documentation reference.

copilot-cli/orchestrator.agent.md (1)

100-127: Routing algorithm documentation properly integrated into orchestrator agent guide.

New agent descriptions (security, devops, explainer), Quick Classification table, Mandatory Agent Rules, and extended routing heuristics align with the detailed routing algorithm and task classification guides. Consistent cross-referencing supports users in understanding when to route to each agent.

Also applies to: 140-141

vs-code-agents/orchestrator.agent.md (1)

100-127: Consistent routing guidance across VS Code and Copilot CLI platforms.

The orchestrator agent documentation is synchronized: new agent capabilities, Quick Classification table, Mandatory Agent Rules, and routing heuristics match the Copilot CLI version, ensuring users on either platform see the same routing logic.

Also applies to: 140-141

docs/orchestrator-routing-algorithm.md (2)

1-100: Comprehensive four-phase routing algorithm with clear classification and agent selection logic.

The algorithm provides explicit pseudocode for task type classification, complexity assessment, risk determination, and agent sequencing. The use of wildcards in agent sequence matching (lines 164–178) allows flexible routing while mandatory agent rules enforce critical constraints (lines 187–203).


208-336: Execution strategy and conflict resolution are well-reasoned and safety-first.

Serial execution of dependent agents (analyst → implementer, architect → implementer) prevents race conditions. Conflict resolution prioritizes security concerns, making explicit tradeoff decisions where agents disagree. The CWE-78 validation example confirms the routing algorithm would have caught the triggering incident.

Comment thread .githooks/pre-commit
Comment thread .github/workflows/agent-metrics.yml
Comment thread .github/workflows/agent-metrics.yml
Comment thread copilot-cli/security.agent.md
Comment thread docs/agent-metrics.md
Comment thread docs/diagrams/routing-flowchart.md
Comment thread docs/task-classification-guide.md
rjmurillo and others added 2 commits December 14, 2025 00:09
Document fallback pattern when cloudmcp-manager memory tools fail:
- memory-add_observations, memory-create_entities, etc. can fall back to
- write_memory, read_memory, list_memories, delete_memory, edit_memory

This provides a resilience mechanism for memory operations during tool failures
or when cloudmcp-manager is unavailable.

Fixes: Serena memory migration task
- Remove unused `import os` from collect_metrics.py (addresses Copilot comment)
- Add symlink validation (MEDIUM-002) to security detection block for
  consistency with markdown linting section (addresses CodeRabbit nitpick)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Copilot AI commented Dec 14, 2025

Copy link
Copy Markdown
Contributor

@rjmurillo I've opened a new pull request, #21, to work on those changes. Once the pull request is ready, I'll request review from you.

Copilot AI commented Dec 14, 2025

Copy link
Copy Markdown
Contributor

@rjmurillo I've opened a new pull request, #22, to work on those changes. Once the pull request is ready, I'll request review from you.

Initialize Serena MCP onboarding with comprehensive project knowledge:

Onboarding memories (shared across team):
- project-overview.md: Project purpose, features, tech stack, agent catalog
- codebase-structure.md: Directory layout, artifact locations, key files
- code-style-conventions.md: Markdown standards, commit format, agent conventions
- suggested-commands.md: Windows/git/linting commands, installation scripts
- task-completion-checklist.md: Pre-commit checks, commit standards, artifact locations

Skills migration from .agents/skills/:
- skills-linting.md: 9 linting skills + 2 anti-patterns (99.8% violation reduction)
- skills-documentation.md: 11 documentation skills + 2 anti-patterns
- skills-workflow.md: 10 workflow skills + 3 anti-patterns
- skills-utilities.md: 2 utility automation skills

Total: 32 skills + 7 anti-patterns at 85-95% atomicity

Configuration:
- .serena/project.yml: Serena MCP project settings
- .serena/.gitignore: Cache exclusion (memories intentionally tracked for team knowledge)

This provides persistent cross-session memory for all agents and learnings from
Phase 1 development cycle. Memories are team-shared artifacts, not user-specific cache.
@rjmurillo

Copy link
Copy Markdown
Owner Author

@coderabbitai This is a false positive. All five security documentation files do exist in this PR:

.agents/security/static-analysis-checklist.md     ✓ EXISTS
.agents/security/secret-detection-patterns.md     ✓ EXISTS
.agents/security/code-quality-security.md         ✓ EXISTS
.agents/security/architecture-security-template.md ✓ EXISTS
.agents/security/security-best-practices.md       ✓ EXISTS

These files were created as part of Issue #10 (Security Agent Enhancement). The analysis appears to have run before the commit was fully processed.

Reference commit: a579104 - 'feat(security): expand security agent to 5 capabilities (#10)'

@rjmurillo

Copy link
Copy Markdown
Owner Author

@coderabbitai All code blocks in docs/agent-metrics.md already have language identifiers:

  • Line 15, 43, 78, 106, 112, 164, 184: text
  • Line 55: regex
  • Lines 245, 255: bash

No changes needed - the file passes markdownlint validation.

@rjmurillo

Copy link
Copy Markdown
Owner Author

@coderabbitai All fenced code blocks in docs/diagrams/routing-flowchart.md already have the text language identifier. The ASCII flowcharts use text which is appropriate for their content. No changes needed.

@coderabbitai

coderabbitai Bot commented Dec 14, 2025

Copy link
Copy Markdown

Tip

For best results, initiate chat on the files or code changes.

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# Check if the five security documentation files exist
echo "=== Checking existence of security documentation files ==="
for file in \
  ".agents/security/static-analysis-checklist.md" \
  ".agents/security/secret-detection-patterns.md" \
  ".agents/security/code-quality-security.md" \
  ".agents/security/architecture-security-template.md" \
  ".agents/security/security-best-practices.md"; do
  if [ -f "$file" ]; then
    echo "✓ EXISTS: $file"
  else
    echo "✗ MISSING: $file"
  fi
done

echo ""
echo "=== Checking commit a579104 ==="
git log --oneline --all | grep "a579104" || echo "Commit not found in log (first 7 chars)"

echo ""
echo "=== Checking recent commits related to security agent ==="
git log --oneline --all -10 | grep -i "security\|#10" || echo "No recent security-related commits found"

echo ""
echo "=== Listing all files in .agents/security/ directory ==="
if [ -d ".agents/security" ]; then
  ls -la ".agents/security/"
else
  echo "Directory .agents/security does not exist"
fi

Length of output: 745


🏁 Script executed:

#!/bin/bash
echo "=== Files changed in commit a579104 ==="
git show --name-status a579104

echo ""
echo "=== Searching for any .agents directory ==="
find . -type d -name ".agents" 2>/dev/null || echo "No .agents directory found"

echo ""
echo "=== Searching for security-related markdown files ==="
fd -e md security 2>/dev/null | head -20 || find . -name "*security*.md" -type f 2>/dev/null | head -20

echo ""
echo "=== Checking if files exist in commit a579104 ==="
git ls-tree -r a579104 --name-only | grep -i "security" | grep ".agents"

Length of output: 1786


🏁 Script executed:

#!/bin/bash
echo "=== Current branch and HEAD ==="
git branch --show-current
git rev-parse HEAD

echo ""
echo "=== Check if a579104 is an ancestor of current HEAD ==="
git merge-base --is-ancestor a579104 HEAD && echo "✓ a579104 IS in current branch history" || echo "✗ a579104 NOT in current branch history"

echo ""
echo "=== Check current HEAD vs a579104 ==="
if [ "$(git rev-parse HEAD)" = "$(git rev-parse a579104)" ]; then
  echo "Current HEAD IS commit a579104"
else
  echo "Current HEAD is NOT commit a579104"
  echo "HEAD: $(git rev-parse HEAD)"
  echo "a579104: $(git rev-parse a579104)"
fi

echo ""
echo "=== List commits between a579104 and HEAD ==="
git log --oneline a579104..HEAD 2>/dev/null || echo "Cannot compute range"

echo ""
echo "=== Check if .agents directory is in .gitignore ==="
if [ -f ".gitignore" ]; then
  grep -n "\.agents" .gitignore || echo "No .agents pattern in .gitignore"
else
  echo "No .gitignore file found"
fi

echo ""
echo "=== Try to checkout the .agents directory from a579104 ==="
git checkout a579104 -- .agents/security/ 2>&1 || echo "Failed to checkout"

echo ""
echo "=== Verify files now exist ==="
ls -la .agents/security/ 2>/dev/null || echo "Directory still doesn't exist"

Length of output: 1177


🏁 Script executed:

#!/bin/bash
echo "=== Check each commit after a579104 for changes to .agents/security ==="
for commit in 0570607 6201ec8 0f298ab 9c43426 30abb3d a71bcc5 c41ca44; do
  echo ""
  echo "--- Commit $commit ---"
  git log --oneline -1 $commit
  git diff --name-status $commit^..$commit | grep ".agents/security" || echo "  (no .agents/security changes)"
done

echo ""
echo "=== Check full diff from a579104 to HEAD for .agents/security ==="
git diff --name-status a579104..HEAD | grep ".agents/security" || echo "No .agents/security changes found"

echo ""
echo "=== Show all files in a579104 under .agents/security ==="
git ls-tree -r a579104 .agents/security/

echo ""
echo "=== Show all files in HEAD under .agents/security ==="
git ls-tree -r HEAD .agents/security/ 2>/dev/null || echo "No .agents/security in HEAD"

echo ""
echo "=== Check if files were moved or renamed ==="
git log --follow --name-status --oneline a579104..HEAD -- ".agents/security/*" 2>/dev/null || echo "No history found"

Length of output: 2454


🏁 Script executed:

#!/bin/bash
echo "=== Verify files exist in HEAD by reading them with git show ==="
for file in \
  ".agents/security/static-analysis-checklist.md" \
  ".agents/security/secret-detection-patterns.md" \
  ".agents/security/code-quality-security.md" \
  ".agents/security/architecture-security-template.md" \
  ".agents/security/security-best-practices.md"; do
  echo ""
  echo "--- Checking $file ---"
  if git show HEAD:"$file" > /dev/null 2>&1; then
    echo "✓ EXISTS in HEAD commit"
    echo "First line: $(git show HEAD:"$file" | head -1)"
  else
    echo "✗ NOT FOUND in HEAD commit"
  fi
done

echo ""
echo "=== Check sparse checkout configuration ==="
if [ -f ".git/info/sparse-checkout" ]; then
  echo "Sparse checkout is configured:"
  cat .git/info/sparse-checkout
else
  echo "No sparse checkout configuration found"
fi

echo ""
echo "=== Check git config for sparse checkout ==="
git config core.sparseCheckout || echo "core.sparseCheckout not set"

Length of output: 956


@rjmurillo You're absolutely correct—this is indeed a false positive, and I apologize for the error.

All five security documentation files do exist in the PR commits:

.agents/security/static-analysis-checklist.md     ✓ EXISTS (commit a579104)
.agents/security/secret-detection-patterns.md     ✓ EXISTS (commit a579104)
.agents/security/code-quality-security.md         ✓ EXISTS (commit a579104)
.agents/security/architecture-security-template.md ✓ EXISTS (commit a579104)
.agents/security/security-best-practices.md       ✓ EXISTS (commit a579104)

Root cause: The repository uses sparse checkout with the pattern !.agents/**, which excludes the .agents directory from the working tree. The files exist in the git commit history (confirmed via git ls-tree and git show HEAD:...) but weren't visible in the working directory during my analysis.

The files were properly added in commit a579104 as part of Issue #10 and are present in the current HEAD of the PR branch.

@rjmurillo

Copy link
Copy Markdown
Owner Author

@coderabbitai These are separate bullet points in a list of indicators, not a single joined concept:

**Indicators**:

- Production code changes with test coverage
- Feature flag protected changes
- Internal tooling modifications

Each bullet is an independent indicator for Medium Risk classification. No grammar fix needed - the structure is intentional.

@coderabbitai

coderabbitai Bot commented Dec 14, 2025

Copy link
Copy Markdown

Tip

For best results, initiate chat on the files or code changes.

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# Check the code blocks in docs/agent-metrics.md
cat docs/agent-metrics.md | grep -n '```' -A 1 | head -50

Length of output: 837


@rjmurillo You're correct. I verified the file and all code blocks in docs/agent-metrics.md already have proper language identifiers (text, regex, bash). My original comment was incorrect—the file was already compliant. No changes needed.

@coderabbitai

coderabbitai Bot commented Dec 14, 2025

Copy link
Copy Markdown

Tip

For best results, initiate chat on the files or code changes.

@rjmurillo You're correct—I misread the structure. Each bullet point is an independent indicator, not part of a compound sentence requiring conjunctions. The formatting is correct as-is. No changes needed.

@coderabbitai

coderabbitai Bot commented Dec 14, 2025

Copy link
Copy Markdown

Tip

For best results, initiate chat on the files or code changes.

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# Check the fenced code blocks in docs/diagrams/routing-flowchart.md
cat docs/diagrams/routing-flowchart.md | grep -n '```'

Length of output: 156


@rjmurillo: Confirmed. All 8 code blocks have the text identifier. My review comment was incorrect.

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 2

♻️ Duplicate comments (1)
.githooks/pre-commit (1)

193-214: Consider warning when Python is unavailable.

The security detection block correctly handles the symlink check and non-blocking execution. However, if the script exists but neither python3 nor python is available, the block silently skips with no user feedback. The markdown linting section warns when its tool is missing (lines 118-120); this section should do the same for consistency.

Apply this diff to add a missing-dependency warning:

 elif [ -f "$SECURITY_DETECTION_SCRIPT" ]; then
     if command -v python3 &> /dev/null; then
         echo_info "Checking for security-critical file changes..."
         python3 "$SECURITY_DETECTION_SCRIPT" --git-staged || true
     elif command -v python &> /dev/null; then
         echo_info "Checking for security-critical file changes..."
         python "$SECURITY_DETECTION_SCRIPT" --git-staged || true
+    else
+        echo_info "Python not available. Skipping security detection."
     fi
 fi
📜 Review details

Configuration used: CodeRabbit UI

Review profile: ASSERTIVE

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 0f298ab and c41ca44.

⛔ Files ignored due to path filters (15)
  • .agents/critique/phase1-plan-review.md is excluded by !.agents/**
  • .agents/planning/PRD-copilot-response-handling.md is excluded by !.agents/**
  • .agents/planning/phase1-implementation-plan.md is excluded by !.agents/**
  • .agents/utilities/metrics/collect_metrics.py is excluded by !.agents/**
  • .serena/.gitignore is excluded by !.serena/**
  • .serena/memories/code-style-conventions.md is excluded by !.serena/**
  • .serena/memories/codebase-structure.md is excluded by !.serena/**
  • .serena/memories/project-overview.md is excluded by !.serena/**
  • .serena/memories/skills-documentation.md is excluded by !.serena/**
  • .serena/memories/skills-linting.md is excluded by !.serena/**
  • .serena/memories/skills-utilities.md is excluded by !.serena/**
  • .serena/memories/skills-workflow.md is excluded by !.serena/**
  • .serena/memories/suggested-commands.md is excluded by !.serena/**
  • .serena/memories/task-completion-checklist.md is excluded by !.serena/**
  • .serena/project.yml is excluded by !.serena/**
📒 Files selected for processing (3)
  • .githooks/pre-commit (1 hunks)
  • .markdownlint-cli2.yaml (1 hunks)
  • CLAUDE.md (1 hunks)
🧰 Additional context used
📓 Path-based instructions (1)
**/*.md

⚙️ CodeRabbit configuration file

**/*.md: Writing Quality: - Grade 9 reading level - Active voice, direct address - Short sentences (under 15 words ideal) - No fluff, filler, or marketing language - Replace adjectives with data where possible - Every sentence must pass the "so what" test
Flag These: - Passive voice - Vague language (nearly, some, almost, very) - Jargon without definitions - Outdated information conflicting with code changes in same PR - Missing context for new features or APIs
Ignore: - Minor style preferences - Heading level choices - Link formatting variations

Files:

  • CLAUDE.md
🔍 Remote MCP DeepWiki

Based on my comprehensive search of the vs-code-agents repository, here's the additional context gathered to help with reviewing this pull request:

Repository Overview The repository maintains a multi-agent system with 18 specialized agents deployed across three platforms:

  • VS Code (GitHub Copilot Chat) - agents in vs-code-agents/ directory
  • GitHub Copilot CLI - agents in copilot-cli/ directory
  • Claude Code CLI - agents in claude/ directory

Each platform has identical agent behavior enforced through 1:1 parity requirements, with platform-specific syntax adaptations only for frontmatter, tool references, and invocation syntax.

Agent System Architecture The system consists of 18 specialized agents organized into functional layers:

Core Workflow Agents

  • orchestrator: Routes complex tasks to appropriate specialist agents
  • analyst: Pre-implementation research and root cause analysis
  • architect: Design governance and ADR creation
  • planner: Work breakdown and milestone definition
  • critic: Plan validation (mandatory quality gate)
  • implementer: Production code execution following Software Hierarchy of Needs
  • qa: Test strategy design and verification
  • security: Vulnerability assessment and threat modeling

Supporting Agents

  • memory: Cross-session persistence via cloudmcp-manager
  • skillbook: Learned strategy management with atomicity scoring
  • retrospective: Post-implementation learning extraction
  • devops, roadmap, explainer, task-generator, pr-comment-responder, independent-thinker, high-level-advisor

Key Governance & Consistency Requirements The repository enforces strict consistency across platforms while allowing platform-specific syntax:

Must Be Consistent Across All Three Platforms:

  • Core agent identity and mission statement
  • Key responsibilities (numbered list)
  • Handoff protocol targets and conditions
  • Memory entity naming conventions (Feature-[Name], ADR-[Number], Skill-[Category]-[Number])
  • Output directory structure (.agents/ subdirectories)
  • Constraints and "DO NOT" rules
  • Skill citation protocol format
  • Atomicity scoring thresholds (for skillbook/retrospective agents)

Platform-Specific Variations (Expected & Acceptable):

  • Frontmatter fields: VS Code/Copilot CLI use full YAML; Claude uses minimal YAML
  • Tool names: execute (VS Code), shell (Copilot CLI), Bash (Claude)
  • Invocation syntax: @agent-name (VS Code), copilot --agent (Copilot CLI), Task() (Claude)
  • File extensions: .agent.md (VS Code/Copilot CLI) vs .md (Claude)

Agent Output Structure

All agents save artifacts to a standardized .agents/ directory with subdirectories:

  • .agents/analysis/ - Research findings (by analyst)
  • .agents/architecture/ - ADRs (by architect)
  • .agents/planning/ - Implementation plans (by planner)
  • .agents/critique/ - Plan validations (by critic)
  • .agents/qa/ - Test reports (by qa)
  • .agents/retrospective/ - Learning extractions (by retrospective)

File naming conventions:

  • ADRs: ADR-NNN-[decision-title].md
  • Plans: NNN-[feature-name]-plan.md
  • Analyses: NNN-[topic]-analysis.md
  • Retrospectives: YYYY-MM-DD-[topic].md

Drift Detection Protocol The repository uses .github/copilot-code-review.md as the authoritative drift detection guide. When agents are modified, code reviewers verify consistency against nine key elements, with clear guidance on acceptable platform-specific differences versus required behavioral consistency.


The context gathered from DeepWiki provides comprehensive understanding of the agent system's architecture, governance requirements, and consistency enforcement mechanisms—all crucial for effectively reviewing a PR that implements Phase 2 of the CWE-78 Incident Remediation with new operational capabilities for the 18-agent system.

🔇 Additional comments (1)
.markdownlint-cli2.yaml (1)

56-56: LGTM.

The exclusion pattern is correct and consistent with the existing glob patterns.

Comment thread CLAUDE.md Outdated
Comment thread CLAUDE.md Outdated
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment