This PR decomposed the pull request generation system from a single monolithic prompt into a layered architecture of instruction files and a lightweight prompt orchestrator. The pull-request.prompt.md file shrank from ~342 lines to ~25 lines, with all workflow logic, template mapping, change-type detection, security analysis, and formatting rules extracted into two new instruction files. The prompt now serves as a thin entry point that declares inputs and delegates to the shared instruction file, while a repo-specific conventions file layers hve-core-specific template mapping on top.

The restructuring introduced parallel subagent review for diff analysis, explicit opt-in PR creation via MCP tools, and a consolidated checkbox reference table as the single authoritative source for all checkbox handling rules.

Description

Pull Request Workflow Architecture

The core of this PR established a two-tier instruction architecture for PR generation.

• Added shared pull request instructions at .github/instructions/hve-core/pull-request.instructions.md (438 lines) defining an 8-step workflow: template resolution, PR reference generation, parallel subagent review, findings merge and verification, PR description generation, PR readiness validation, optional MCP-based PR creation, and cleanup
  • Introduced canonical fallback rules referenced by name throughout the workflow to reduce duplication of error-handling logic
  • Defined the subagent review protocol with structured fan-out/fan-in for chunk-based diff analysis and output file templates
  • Codified PR writing standards including bold emphasis for key terms (overriding general writing-style restrictions for PR descriptions), italics for file names, blockquotes for motivation, and sub-heading organization for multi-area PRs
  • Added issue reference extraction patterns for commits and branch names with deduplication
• Added repo-specific PR conventions at .github/instructions/pull-request.instructions.md (176 lines) for hve-core template integration
  • Defined manual-only sections that agents must never modify (AI artifact contribution verification, prompt-builder review attestation, free-form other type)
  • Created a checkbox reference table consolidating all checkbox handling rules with template location, purpose, handling type, step, and rule summary columns
  • Specified section fill guidance for Sample Prompts (User Request, Execution Flow, Output Artifacts, Success Indicators sub-sections) and Testing
  • Included change type detection patterns mapping file patterns, branch patterns, and commit patterns to PR template checkbox labels
  • Added GHCP maturity detection logic with output formatting for experimental, preview, and deprecated artifacts

Prompt Refactoring

The prompt file retained only the orchestration interface, with all domain logic moved to instruction files.

• Replaced the 342-line monolithic prompt in pull-request.prompt.md with a 25-line delegating prompt that declares three inputs (branch, createPullRequest, excludeMarkdown) with defaults
  • Added createPullRequest input defaulting to false for explicit opt-in PR creation via MCP tools
  • Added argument-hint frontmatter field showing usage syntax
  • Updated description branding from edge-ai to hve-core

Agent and Documentation Updates

• Added a Compact handoff to prompt-builder.agent.md with a /compact prompt that preserves .copilot-tracking state, tracking artifact file paths, analysis logs, follow-up items, and user requirements during summarization
• Expanded the instructions README "Git and Workflow" table with entries for both new PR instruction files, including their applyTo patterns
• Updated docs/contributing/skills.md portability examples to use generic placeholders (<script-name>.sh, <reference-name>.md) instead of hardcoded filenames

Collection Manifest Registration

• Registered the shared instruction file in both hve-core.collection.yml and hve-core-all.collection.yml, maintaining alphabetical ordering within instruction blocks

Related Issue(s)

None

Type of Change

Select all that apply:

Code & Documentation:

• Bug fix (non-breaking change fixing an issue)
• New feature (non-breaking change adding functionality)
• Breaking change (fix or feature causing existing functionality to change)
• Documentation update

Infrastructure & Configuration:

• GitHub Actions workflow
• Linting configuration (markdown, PowerShell, etc.)
• Security configuration
• DevContainer configuration
• Dependency update

AI Artifacts:

• Reviewed contribution with prompt-builder agent and addressed all feedback
• Copilot instructions (.github/instructions/*.instructions.md)
• Copilot prompt (.github/prompts/*.prompt.md)
• Copilot agent (.github/agents/*.agent.md)
• Copilot skill (.github/skills/*/SKILL.md)

Note for AI Artifact Contributors:

• Agents: Research, indexing/referencing other project (using standard VS Code GitHub Copilot/MCP tools), planning, and general implementation agents likely already exist. Review .github/agents/ before creating new ones.
• Skills: Must include both bash and PowerShell scripts. See Skills.
• Model Versions: Only contributions targeting the latest Anthropic and OpenAI models will be accepted. Older model versions (e.g., GPT-3.5, Claude 3) will be rejected.
• See Agents Not Accepted and Model Version Requirements.

Other:

• Script/automation (.ps1, .sh, .py)
• Other (please describe):

Sample Prompts (for AI Artifact Contributions)

User Request:

Invoke the pull request prompt to generate a PR description from branch diffs:

/pull-request branch=origin/main createPullRequest=true

Execution Flow:

1. Resolves the PR template from .github/PULL_REQUEST_TEMPLATE.md
2. Generates a PR reference XML file using the pr-reference skill
3. Launches parallel subagents (one per chunk) to analyze diff content
4. Merges subagent findings into a unified pr-reference-log.md
5. Generates pr.md from the analysis, mapping findings to the repository PR template
6. Runs required automated checks and triages failures
7. Creates a pull request via MCP tools when createPullRequest=true
8. Cleans up temporary artifacts (XML, subagent files)

Output Artifacts:

• .copilot-tracking/pr/pr.md — Final PR description with title and body
• .copilot-tracking/pr/pr-reference-log.md — Verified analysis log (persists)
• .copilot-tracking/pr/subagents/NN-pr-reference-log.md — Per-chunk review logs (temporary)

Success Indicators:

• pr.md preserves all PR template sections and accurately reflects diff analysis
• Change type checkboxes match detected file patterns
• Required automated checks pass (lint, frontmatter, skills validation)
• PR is created on GitHub when explicitly requested

Testing

Automated Validation

Security Analysis

• No sensitive data, API keys, or credentials detected in changes
• No new dependencies introduced
• No privilege escalation patterns identified
• No security scripts modified

Diff-Based Assessment

• All changes are additive or refactoring; no public API surfaces were removed
• Changed files follow existing naming conventions
• Documentation updates accompany the instructional changes

Checklist

Required Checks

• Documentation is updated (if applicable)
• Files follow existing naming conventions
• Changes are backwards compatible (if applicable)
• Tests added for new functionality (if applicable) (N/A — instruction and prompt files do not have associated test suites)

AI Artifact Contributions

• Used /prompt-analyze to review contribution
• Addressed all feedback from prompt-builder review
• Verified contribution follows common standards and type-specific requirements

Required Automated Checks

The following validation commands must pass before merging:

• Markdown linting: npm run lint:md
• Spell checking: npm run spell-check
• Frontmatter validation: npm run lint:frontmatter
• Skill structure validation: npm run validate:skills
• Link validation: npm run lint:md-links
• PowerShell analysis: npm run lint:ps

PR Generation Validation

• PR description preserves all template sections
• pr-reference-log.md analysis is accurately reflected in the description
• Description uses past tense and follows writing-style conventions
• All significant changes from the diff are included
• Referenced files are accurate and exist in the repository
• Follow-up tasks are actionable and tied to specific code, files, or components

GHCP Artifact Maturity

Security Considerations

• This PR does not contain any sensitive or NDA information
• Any new dependencies have been reviewed for security issues (N/A — no new dependencies introduced)
• Security-related scripts follow the principle of least privilege (N/A — no security scripts modified)

Additional Notes

• The repo-specific conventions file at .github/instructions/pull-request.instructions.md is positioned at the instructions root (not under hve-core/) and is correctly excluded from collection manifests per project structure rules.
• All 10 commits follow conventional commit format with feat type, reflecting iterative refinement of the same set of files.
• The createPullRequest input defaults to false, preserving existing behavior where the prompt generates a description without creating a PR unless explicitly requested.