feat: Collaboration & Refinement Improvements

[Jeymz]

Summary

This PR expands and standardizes the repository’s Copilot security “library” content by:

• Adding library-maintenance agents, prompts, and authoring instructions under .github/.
• Improving the primary docs and catalogues (root README + agents/skills READMEs) for discoverability.
• Normalizing prompt metadata (YAML frontmatter) and tightening prompt output formats to be more tool/environment friendly.

What changed

New library-management content (under .github/)

• Added new agent profiles to help maintain and evolve this library:
  • .github/agents/appsec-library-maintainer.agent.md
  • .github/agents/security-prompt-engineer.agent.md (later updated to include additional tool capabilities)
  • .github/agents/markdown-customizations.agent.md
• Added authoring/quality bar instructions for customization + security library items:
  • .github/instructions/copilot-customization-files.instructions.md
  • .github/instructions/security-library-authoring.instructions.md
• Added internal maintenance prompts for auditing/syncing/improving the library:
  • .github/prompts/audit-library.prompt.md
  • .github/prompts/sync-readme-catalogue.prompt.md
  • .github/prompts/improve-library-item.prompt.md
  • .github/prompts/add-new-security-prompt.prompt.md
  • .github/prompts/create-skill.prompt.md
  • .github/prompts/review-prompt-fontmatter.prompt.md (expanded guidance for required YAML frontmatter and reporting format)
• Added a skill for markdown customization authoring:
  • .github/skills/markdown-customizations/SKILL.md
• Added repo-scoped Copilot instructions under:
  • .github/copilot-instructions.md

Root documentation and catalog improvements

• Updated the root README to improve usability and navigation:
  • Expanded/clarified the prompt catalogue and contributor guidance, and added agent/skill overview tables in later commits: README.md
• Improved internal agent catalogue linking:
  • Converted the agent list to clickable links: agents/README.md
• Clarified skill catalogue linking and usage notes:
  • Converted skill list to clickable links and kept naming guidance: skills/README.md

New/expanded “orchestrator” entrypoint agent

• Added an “application-security-orchestrator” agent to standardize intake and route to specialist agents (Analyst/Architect/Engineer):
  • agents/application-security-orchestrator.agent.md
• Updated docs to recommend starting with the orchestrator for typical workflows:
  • README.md, agents/README.md

Prompt metadata normalization (YAML frontmatter)

• Added required YAML frontmatter (agent, name, description) across all root-level security prompts to improve clarity and compliance:
  • prompts/assess-logging.prompt.md
  • prompts/business-logic-review.prompt.md
  • prompts/check-access-controls.prompt.md
  • prompts/check-for-secrets.prompt.md
  • prompts/check-for-unvalidated-genai-acceptances.prompt.md
  • prompts/dependency-cve-triage.prompt.md
  • prompts/review-auth-flows.prompt.md
  • prompts/scan-for-insecure-apis.prompt.md
  • prompts/secure-code-review.prompt.md
  • prompts/threat-model.prompt.md
  • prompts/validate-input-handling.prompt.md

Prompt content improvements + output format hardening

• Strengthened multiple prompts to be more evidence-first and more consistent in reporting structure (summary, findings, evidence, recommendation, verification):
  • Examples: prompts/assess-logging.prompt.md, prompts/check-for-secrets.prompt.md
• Refactored longer prompts to remove redundant sections and provide clearer step-by-step procedures (notably business logic review and threat model):
  • prompts/business-logic-review.prompt.md
  • prompts/threat-model.prompt.md
• Adjusted “output format” language to be environment-compatible:
  • Instead of requiring file creation only, prompts now instruct: return Markdown in chat, and “also write the file if the environment supports it”:
    • prompts/business-logic-review.prompt.md
    • prompts/secure-code-review.prompt.md
    • prompts/threat-model.prompt.md
• Updated secure code review prompt guidance around logging/redaction concerns to be more concrete and broadly applicable:
  • prompts/secure-code-review.prompt.md

Skills expansion and enrichment

• Added multiple skill workflows to guide repeatable security work (authz, CVE triage, GenAI acceptance, validation, logging hygiene, threat modeling, fix validation):
  • skills/authn-authz-review/SKILL.md
  • skills/dependency-cve-triage/SKILL.md
  • skills/genai-acceptance-review/SKILL.md
  • skills/input-validation-hardening/SKILL.md
  • skills/secrets-and-logging-hygiene/SKILL.md
  • skills/secure-fix-validation/SKILL.md
  • skills/threat-model-lite/SKILL.md
• Enhanced skill content with “when to use”, inputs, output format, and examples (e.g., secure fix validation):
  • skills/secure-fix-validation/SKILL.md

Minor config/housekeeping

• Updated the example env key name for SSL PFX passphrase to be consistent with dot-separated config conventions:
  • .env.example
• Removed a root package-lock file:
  • package-lock.json

Notes / Compatibility

• These changes are primarily documentation, agent/prompt templates, and instructions. No runtime behavior changes are introduced to the Node/Express code paths in src/ as part of these commits.

Testing

• Not run (documentation/template-only changes).
• Optional sanity checks:
  • Ensure markdown renders correctly in GitHub.
  • Validate prompts conform to the required YAML frontmatter conventions described in .github/prompts/review-prompt-fontmatter.prompt.md.

[Copilot]

Pull request overview

This PR expands and standardizes the repository's Copilot security "library" content by introducing library-maintenance tooling, improving documentation and catalogues, and normalizing prompt metadata and output formats for better tool/environment compatibility.

Changes:

• Added library-management agents, prompts, instructions, and skills under .github/ to help maintain and evolve the security library
• Improved root documentation (README, agents/README, skills/README) with clickable catalogue tables and usage guidance
• Added YAML frontmatter (agent, name, description) to all root-level security prompts for consistency and discoverability
• Strengthened prompt content with evidence-first procedures, deterministic output formats, and quality checks
• Expanded skills with "when to use", inputs, output format, and examples sections
• Added an orchestrator agent as the recommended entry point for AppSec workflows

Reviewed changes

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

Show a summary per file

File	Description
skills/threat-model-lite/SKILL.md	Added standard skill sections (when to use, inputs, output format, examples)
skills/secure-fix-validation/SKILL.md	Added standard skill sections (when to use, inputs, output format, examples)
skills/secure-code-review/SKILL.md	Added "when to use" section header
skills/secrets-and-logging-hygiene/SKILL.md	Added standard skill sections (when to use, inputs, output format, examples)
skills/input-validation-hardening/SKILL.md	Added standard skill sections (when to use, inputs, output format, examples)
skills/genai-acceptance-review/SKILL.md	Added standard skill sections (when to use, inputs, output format, examples)
skills/dependency-cve-triage/SKILL.md	Added standard skill sections (when to use, inputs, output format, examples)
skills/authn-authz-review/SKILL.md	Added standard skill sections (when to use, inputs, output format, examples)
skills/README.md	Converted skill list to clickable links
prompts/validate-input-handling.prompt.md	Added YAML frontmatter and restructured into evidence-first format
prompts/threat-model.prompt.md	Drastically simplified from 366 lines to 91 lines; added frontmatter and focused on 4Q core procedure
prompts/secure-code-review.prompt.md	Added frontmatter, restructured procedure, clarified logging/redaction guidance
prompts/scan-for-insecure-apis.prompt.md	Added frontmatter and evidence-first structure
prompts/review-auth-flows.prompt.md	Added frontmatter and evidence-first structure
prompts/dependency-cve-triage.prompt.md	Added frontmatter and evidence-first structure with explicit input variables
prompts/check-for-unvalidated-genai-acceptances.prompt.md	Added frontmatter and evidence-first structure
prompts/check-for-secrets.prompt.md	Added frontmatter and evidence-first structure
prompts/check-access-controls.prompt.md	Added frontmatter and evidence-first structure
prompts/business-logic-review.prompt.md	Added frontmatter and restructured for clarity
prompts/assess-logging.prompt.md	Added frontmatter and evidence-first structure
copilot-instructions.md	Added Python support, clarified XSS/sanitization guidance, updated secrets handling guidance
agents/application-security-orchestrator.agent.md	New orchestrator agent for routing AppSec workflows
agents/application-security-engineer.agent.md	Added "handling missing information" section
agents/application-security-architect.agent.md	Added "handling missing information" section
agents/README.md	Converted agent list to clickable links and added orchestrator recommendation
README.md	Expanded prompt catalogue, added agent/skill overview tables, recommended orchestrator workflow
.github/skills/markdown-customizations/SKILL.md	New skill for authoring Copilot customization files
.github/prompts/sync-readme-catalogue.prompt.md	New maintenance prompt for README catalogue syncing
.github/prompts/review-prompt-fontmatter.prompt.md	New prompt for auditing YAML frontmatter compliance
.github/prompts/improve-library-item.prompt.md	New prompt for refactoring library items
.github/prompts/create-skill.prompt.md	New prompt for generating new skills
.github/prompts/audit-library.prompt.md	New prompt for comprehensive library auditing
.github/prompts/add-new-security-prompt.prompt.md	New prompt for creating new security prompts
.github/instructions/security-library-authoring.instructions.md	New authoring rules for library content
.github/instructions/copilot-customization-files.instructions.md	New authoring rules for customization files
.github/copilot-instructions.md	New repo-scoped Copilot instructions
.github/agents/security-prompt-engineer.agent.md	New agent for designing security prompts/skills
.github/agents/markdown-customizations.agent.md	New agent for maintaining customization files
.github/agents/appsec-library-maintainer.agent.md	New agent for library maintenance
.env.example	Updated SSL PFX passphrase key name to dot-separated format

---

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

[Jeymz]

✅ PR Review Summary (PR Compass - Holistic Pull Request Reviewer)

This is a strong, high-signal PR that significantly improves the clarity, consistency, and safety of this repository as a Copilot security content library.

Key wins:

• Establishes a clear separation between consumer-facing security library content and contributor/maintenance helpers, which will scale well over time.
• Introduces a well-designed Application Security Orchestrator that standardizes intake, enforces evidence-first outputs, and routes work to the right specialist without overreach.
• Normalizes prompt and skill structure across the repo (context → procedure → deterministic output → quality checks), dramatically reducing ambiguity and hallucination risk.
• Reinforces secure authoring practices throughout: no insecure shortcuts, explicit assumptions, concrete evidence, and verification steps.
• Improves documentation and discoverability (README, agent/skill catalogues) without unnecessary churn.

The changes are thoughtful, cohesive, and aligned with real-world AppSec workflows. Aside from a few minor nits (typos, newline, and optional clarifications), this PR is ready to merge and sets a solid foundation for future additions to the library.