Description

Reorganized the AI Artifacts Common contribution guide to accurately reflect the plugin and collection system currently in production. The restructured documentation corrects outdated dependency declarations, adds comprehensive plugin generation guidance, and expands repo-specific exclusion enforcement details.

• docs(ai-artifacts): restructured the Collections section for improved learning flow, renaming "Collection Manifests" to "Collections" and reordering subsections to follow a logical progression from collections through extension packaging to plugin generation

• docs(ai-artifacts): added comprehensive Plugin Generation section documenting the full contributor workflow, including generation commands, plugin directory structure, critical rules against direct edits, regeneration triggers, and validation checks

• docs(ai-artifacts): replaced the incorrect Dependency Declarations section with Extension Packaging documentation that accurately describes agent handoff dependency resolution via BFS traversal in Prepare-Extension.ps1, removing references to a non-existent requires field in collection manifests

• docs(ai-artifacts): expanded repo-specific exclusion guidance with validation enforcement details, a placement guidelines table, and explicit documentation of how plugin generation and collection validation actively enforce the .github/**/hve-core/ exclusion

• docs(ai-artifacts): added npm run plugin:validate and npm run plugin:generate steps to the contribution workflow, with enumerated validation checks covering YAML syntax, required fields, path references, kind/maturity values, duplicate detection, and hve-core exclusions

Related Issue(s)

Closes #621

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):

Testing

Validated documentation changes against the actual scripts and collection files referenced in the guide. Confirmed accuracy of npm run plugin:validate and npm run plugin:generate command documentation against scripts/plugins/Validate-Collections.ps1 and scripts/plugins/Generate-Plugins.ps1.

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)

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
• Link validation: npm run lint:md-links
• PowerShell analysis: npm run lint:ps

Security Considerations

• This PR does not contain any sensitive or NDA information
• Any new dependencies have been reviewed for security issues
• Security-related scripts follow the principle of least privilege

Additional Notes

This PR addresses documentation drift where the contribution guide described a requires dependency field on collection manifest items that does not exist in production. The corrected documentation now accurately reflects that dependencies are resolved through agent frontmatter handoffs declarations during extension packaging, not through collection manifest fields.

📝 - Generated by Copilot