@niksacdev - moved this over to a discussion for now given that we're weighing claude code integration and a shim layer to make that work with the existing migration to skills. I'll have an update on this shortly and I'm going to start laying out how we plan to do persona-based distribution of hve-core components so that we can provide different users different prompt suites. One of the issues I have with SpecKit and Awesome copilot is they have turned into a bit of a grab bag ... and it's hard to sort the cruft from the gold.

Love the phased approach and the per-standard modularity — Phase 1 makes total sense as
a starting point. I'd like to propose a slightly different packaging though: skills
instead of instruction files for the security standards.

Why not .instructions.md?

The core issue is that .instructions.md files are architecturally file-centric — they
answer "when editing file type X, what rules apply?" via applyTo glob patterns. Security
standards don't have a natural file type to target:

• No applyTo → non-deterministic loading (relies on description matching, which is
  best-effort)
• applyTo: '**' → 16 standards × ~80 lines = ~1,280 lines injected into every
  single request, regardless of relevance
• Synthetic paths (e.g., .copilot-tracking/security/) → misleading activation that
  depends on file operations happening in the right order

Instructions also lack progressive disclosure — the full body loads on any match — and
they're VS Code/GitHub.com only. Not portable to Copilot CLI, Claude Code, or other
tools supporting the Agent Skills standard.

The alternative: SKILL.md packages

Each security standard becomes a skill directory under .github/skills/:

.github/skills/
├── owasp-top-10/
│   ├── SKILL.md              # ~80 lines: overview + checklist
│   └── references/
│       ├── REFERENCE.md      # Detailed vulnerability descriptions
│       └── checklist.md      # Assessment template
├── stride-methodology/
│   ├── SKILL.md
│   └── references/
│       └── REFERENCE.md
├── rai-principles/
│   ├── SKILL.md
│   └── references/
│       └── REFERENCE.md
├── owasp-llm/
│   └── SKILL.md
├── owasp-agentic/
│   └── SKILL.md
├── ... (remaining standards)

.github/agents/
├── security-reviewer.agent.md
└── subagents/
    └── security-standard-analyst.agent.md

Skills give us three things instructions can't:

1. Progressive disclosure — only name + description (~100 tokens per skill) load
   at startup. The full body loads only when the task is relevant. 16 standards cost
   ~1,600 tokens baseline vs 25,600 for always-on instructions.
2. Intent-based discovery — the model discovers relevant standards from descriptions
   automatically. No applyTo needed, no #file: wiring.
3. Resource packaging — checklists, scoring matrices, templates, and reference docs
   bundle alongside the skill in references/ and assets/.

Background knowledge skills use user-invokable: false so they're discoverable by the
model but don't clutter the user's slash command menu.

Composition: agent → subagent (not agent → skill)

Rather than having the agent "call" skills directly, the agent orchestrates via subagents
that read skill files as domain knowledge — the same file-reading pattern any research
subagent uses:

graph TD
    A["👤 User: Review security"] --> B["🔍 security-reviewer.agent.md<br/><i>Parent Agent</i>"]

    B --> C["📋 Classify Codebase"]
    C --> D{"Codebase Type?"}

    D -->|"Web / API"| E["📦 owasp-top-10<br/>📦 stride<br/>📦 zero-trust"]
    D -->|"AI / LLM"| F["📦 owasp-llm<br/>📦 owasp-agentic<br/>📦 rai-principles<br/>📦 mitre-atlas"]
    D -->|"DevOps / Infra"| G["📦 owasp-cicd<br/>📦 zero-trust<br/>📦 owasp-docker"]

    E --> H["⚡ Run Parallel Subagents"]
    F --> H
    G --> H

    subgraph "Per-Standard Subagent Execution"
        H -->|"For each standard"| I["🤖 security-standard-analyst<br/><i>Subagent</i>"]
        I -->|"1. Read"| J["📄 SKILL.md + references/"]
        I -->|"2. Analyze"| K["🔎 Codebase Files"]
        I -->|"3. Write"| L["📝 Standard Findings"]
    end

    L --> M["📊 Consolidate Findings"]
    M --> N["📋 Security Review Report<br/><i>Severity • Evidence • Fixes</i>"]

The security-reviewer.agent.md parent agent:

1. Classifies the codebase (web, API, AI/LLM, DevOps, mobile, etc.)
2. Selects 2-4 relevant standard skills based on classification
3. Runs parallel security-standard-analyst subagents — each reads the assigned
   skill's SKILL.md and references/ for domain knowledge, then applies it against
   the codebase
4. Consolidates subagent findings into a unified security review report with severity,
   evidence, and specific code fixes

The subagent doesn't "call" the skill — it reads the skill's files as context, the same
way researcher-subagent reads any codebase file. This keeps the composition boundary
clean: agents orchestrate subagents, subagents consume files.

Token budget comparison

Skills add ~1,600 tokens baseline for discovery awareness (the model knows all 16
standards exist) while keeping any single review well within context limits.

Cross-platform portability

SKILL.md follows the open Agent Skills standard, supported
by VS Code, Copilot CLI, Claude Code, and 15+ other AI tools. Instructions are VS Code
and GitHub.com only. For a distributable artifact like this, skills reach the broadest
audience.

On Claude Code specifically, the subagent equivalent can declare skills: [owasp-top-10]
in its frontmatter, which preloads the full skill content at startup — the runtime injects
the domain knowledge automatically.

Phasing (same as proposed, different packaging)

1. Phase 1: OWASP Top 10 + STRIDE + RAI as skills, plus the security reviewer agent
   with subagent composition
2. Phase 2: LLM + Agentic + MCP + ML + MITRE ATLAS skills
3. Phase 3: CI/CD + Docker + Infrastructure + Zero Trust skills
4. Phase 4: Mobile + OSS + Serverless + NIST AI RMF + remaining standards

Same phasing, same per-standard modularity, same token-efficient selective loading —
just packaged as skills rather than instructions for better discovery, portability, and
progressive disclosure.

Tagging @agreaves-ms for insights into SKILLs usage and experience.
And @obrocki for joining with his initial work on a Security champion agent and skills.

Thoughts?

Had a sync with @katriendg and @JasonTheDeveloper this week. We converged on OWASP Web/API as the MVP — start narrow, deliver value, iterate. Security is a minefield and trying to land all 16 standards at once will stall us.

Where PR #408 fits:
PR #408 was my initial cut at a security champion agent with SDL + OWASP. After reviewing @katriendg's architectural direction in this discussion — skills over instructions, subagent composition, per-standard granularity — it's clear #408 needs to be reshaped to align with the composition model.

@katriendg's analysis identified the key gaps: the monolithic skill needs splitting into per-standard packages, the agent needs subagent delegation, we need pre-built prompts for domain-specific reviews, and hardcoded paths should give way to semantic discovery. All agreed.

Proposed MVP (Phase 1) scope:
Building on @katriendg's proposed structure, I'd suggest Phase 1 be scoped to OWASP Top 10 (Web) only, plus the foundational agent/subagent/prompt skeleton:

.github/
├── agents/security-planning/
│   ├── security-reviewer.agent.md              # Parent orchestrator
│   └── subagents/
│       └── security-standard-analyst.agent.md  # Reusable per-standard subagent
├── prompts/security-planning/
│   ├── security-review.prompt.md               # General (agent auto-selects)
│   └── security-review-web.prompt.md           # Web-focused
└── skills/security-planning/
    └── owasp-top-10/                           # MVP: Web only
        ├── SKILL.md
        └── references/

STRIDE, RAI, Secure by Design and the remaining OWASP frameworks slot into Phase 2+ once the skeleton is proven. The foundation matters more than completeness — tooling will evolve anyway, so the value is in the composition pattern, not coverage breadth.

Next steps:
I'll rework #408 to align with this architecture
We should create tracking issues for the MVP deliverables
@JasonTheDeveloper's owasp-skills reference content can feed directly into the owasp-top-10/ skill
Happy to pick up the MVP implementation once we agree on scope.

Here's our current thinking for MVP @JasonTheDeveloper @obrocki - we start planning this in the backlog.

Security Reviewer — MVP Scope & Phased Approach

Based on our discussion consensus, here's the proposed MVP and phased roadmap.

Key Approach

Skills-first, agent-thin. OWASP domain knowledge lives entirely in self-contained skills (SKILL.md + reference files). A single thin orchestrator agent classifies the codebase, selects relevant skills, and delegates per-skill reviews via inline subagent prompts — adopting @JasonTheDeveloper's proven vulnerability-scanner pattern from owasp-skills. No OWASP knowledge lives in the agent body itself.

Output is structured and consistent: a two-layer taxonomy (assessment status: PASS/FAIL/PARTIAL/NOT_ASSESSED × severity: CRITICAL/HIGH/MEDIUM/LOW) with findings written to .copilot-tracking/security/ as ephemeral tracking files.

MVP (Phase 1)

The 3 skills were chosen because Web covers the most common case, and LLM + Agentic directly align with the team's daily work building AI-integrated systems.

Taking this approach in MVP form with a limited set allows for testing in experimental mode, collecting value and adatping before iterating for all other skills.

Depending on success rates, subagents may be created in addition to skills. Testing feedback and evolution of tooling will play a role.

Phase 2: AI + Methodology Skills

• Port MCP, ML, MITRE ATLAS skills from owasp-skills
• Author STRIDE methodology skill
• Author RAI principles skill (needs RAI champion input)
• Design full shared specification with multi-layer taxonomy (confidence, priority, remediation status)
• Domain-specific AI prompt + lifecycle prompts (plan, progress tracking)

Phase 3: DevOps + Infrastructure

• Port CI/CD, Docker, Infrastructure, Zero Trust skills
• DevOps and compliance-focused prompts

Phase 4: Remaining Standards + Evaluation

• Mobile, OSS, Serverless, NIST AI RMF skills
• Evaluation framework with golden datasets

Implementation Order

Issues 2–4 (skills) can run in parallel after the collection rename (1). The agent (5) can start in parallel with skills (references skill paths, content can be stubbed). Prompts (6) depend on the agent. 7 and 8 are final integration steps.

Full research document with detailed agent frontmatter, skill adaptation tables, output format templates, and subagent prompt templates is available for reference internally.