feat: Reorganize agents, instructions, prompts, and skills into collection-based subdirectories

[agreaves-ms]

Summary

Reorganize all AI artifacts (agents, instructions, prompts, skills) from their current flat directory layout into collection-based subdirectories. Each artifact type directory gains subfolders named after the collections defined in collections/*.collection.yml. Artifacts shared across multiple collections are placed in a shared/ subfolder. VS Code settings, the hve-core-installer, collection manifests, and contributing documentation are updated to reflect the new structure.

Motivation

The current flat layout under .github/agents/, .github/prompts/, .github/instructions/, and .github/skills/ does not communicate which collection an artifact belongs to. As the artifact count grows, discoverability and maintainability degrade. Organizing artifacts into collection-aligned subdirectories makes ownership, packaging boundaries, and contribution targets immediately clear from the file system.

Current State

All artifacts live in flat directories:

.github/
├── agents/
│   ├── ado-prd-to-wit.agent.md
│   ├── github-backlog-manager.agent.md
│   ├── rpi-agent.agent.md
│   ├── ...
│   └── subagents/
├── instructions/
│   ├── ado-create-pull-request.instructions.md
│   ├── github-backlog-discovery.instructions.md
│   ├── markdown.instructions.md
│   └── ...
├── prompts/
│   ├── ado-create-pull-request.prompt.md
│   ├── github-add-issue.prompt.md
│   ├── rpi.prompt.md
│   └── ...
└── skills/
    └── video-to-gif/

Collections in collections/*.collection.yml define which artifacts belong to which bundle, but this grouping has no corresponding folder structure.

Target State

Artifacts move into subdirectories named after their owning collection. Artifacts referenced by multiple collections live in a shared/ directory. Subagents follow their parent agent's collection.

.github/
├── agents/
│   ├── ado/
│   │   └── ado-prd-to-wit.agent.md
│   ├── github/
│   │   └── github-backlog-manager.agent.md
│   │   └── github-issue-manager.agent.md
│   ├── rpi/
│   │   └── rpi-agent.agent.md
│   │   └── task-researcher.agent.md
│   │   └── task-planner.agent.md
│   │   └── task-implementor.agent.md
│   │   └── task-reviewer.agent.md
│   ├── data-science/
│   │   └── gen-data-spec.agent.md
│   │   └── gen-jupyter-notebook.agent.md
│   │   └── gen-streamlit-dashboard.agent.md
│   │   └── test-streamlit-dashboard.agent.md
│   ├── project-planning/
│   │   └── adr-creation.agent.md
│   │   └── brd-builder.agent.md
│   │   └── prd-builder.agent.md
│   │   └── arch-diagram-builder.agent.md
│   ├── prompt-engineering/
│   │   └── prompt-builder.agent.md
│   ├── security-planning/
│   │   └── security-plan-creator.agent.md
│   ├── shared/
│   │   └── memory.agent.md
│   │   └── pr-review.agent.md
│   │   └── doc-ops.agent.md
│   │   └── hve-core-installer.agent.md
│   │   └── subagents/
│   │       └── rpi-validator.agent.md
│   │       └── implementation-validator.agent.md
│   │       └── ...
│   └── ...
├── instructions/
│   ├── ado/
│   │   └── ado-create-pull-request.instructions.md
│   │   └── ...
│   ├── github/
│   │   └── github-backlog-discovery.instructions.md
│   │   └── ...
│   ├── coding-standards/
│   │   └── bash/
│   │   └── csharp/
│   │   └── bicep/
│   │   └── terraform/
│   │   └── python-script.instructions.md
│   │   └── uv-projects.instructions.md
│   ├── shared/
│   │   └── writing-style.instructions.md
│   │   └── markdown.instructions.md
│   │   └── commit-message.instructions.md
│   │   └── git-merge.instructions.md
│   │   └── prompt-builder.instructions.md
│   │   └── hve-core-location.instructions.md
│   └── hve-core/
│       └── workflows.instructions.md
├── prompts/
│   ├── ado/
│   │   └── ado-create-pull-request.prompt.md
│   │   └── ...
│   ├── github/
│   │   └── github-add-issue.prompt.md
│   │   └── ...
│   ├── rpi/
│   │   └── rpi.prompt.md
│   │   └── task-research.prompt.md
│   │   └── ...
│   ├── shared/
│   │   └── git-commit-message.prompt.md
│   │   └── git-commit.prompt.md
│   │   └── git-merge.prompt.md
│   │   └── git-setup.prompt.md
│   │   └── pull-request.prompt.md
│   │   └── checkpoint.prompt.md
│   │   └── prompt-analyze.prompt.md
│   │   └── prompt-build.prompt.md
│   │   └── prompt-refactor.prompt.md
│   └── ...
└── skills/
    └── video-to-gif/

Note: The exact folder assignments per artifact must be derived from the collections/*.collection.yml manifests during implementation. Artifacts appearing in only one collection go in that collection's folder. Artifacts appearing in multiple collections (e.g., memory.agent.md, writing-style.instructions.md) go in shared/. The tree above is illustrative.

Acceptance Criteria

1. Categorize artifacts by collection

• Parse all collections/*.collection.yml files to build an artifact-to-collection mapping
• Identify artifacts that appear in a single collection (placed in that collection's subfolder)
• Identify artifacts that appear in multiple collections (placed in shared/)
• Identify artifacts in hve-core-all.collection.yml only — these are candidates for shared/ or need collection assignment
• Document the final mapping before moving files

2. Move artifacts into collection subdirectories

• Create subdirectories under .github/agents/, .github/instructions/, .github/prompts/, .github/skills/ for each collection name (using the collection id as the folder name — e.g., ado, rpi, github, data-science, coding-standards, project-planning, prompt-engineering, security-planning)
• Create a shared/ subdirectory under each artifact type for cross-collection artifacts
• Move each artifact file to its determined subdirectory
• Preserve the existing subagents/ grouping within the appropriate collection or shared/ folder
• Preserve the existing hve-core/ subdirectory under instructions/ (repo-specific, excluded from collections)

3. Update VS Code settings

• Update .vscode/settings.json chat.agentFilesLocations to include all new agent subdirectories
• Update .vscode/settings.json chat.promptFilesLocations to include all new prompt subdirectories
• Update .vscode/settings.json chat.instructionsFilesLocations to include all new instruction subdirectories
• Update .vscode/settings.json chat.agentSkillsLocations to include all new skill subdirectories (if not already using a glob pattern that covers them)
• Verify VS Code discovers all agents, prompts, instructions, and skills after the move

4. Update hve-core-installer

• Update the hve-core-installer agent (or skill, if feat: Convert hve-core-installer agent into a Skill #635 completes first) to correctly configure VS Code chat.*FilesLocations settings when pointing to a cloned microsoft/hve-core repository
• Ensure all installation methods (peer clone, git-ignored, mounted, codespaces, multi-root workspace, submodule) generate correct paths to the new subdirectories
• Update any hardcoded path references in the installer's environment detection and validation scripts

5. Update collection YAML manifests

• Update every collections/*.collection.yml file to reference the new subdirectory paths for all items
• Run npm run plugin:generate to regenerate plugin outputs
• Run npm run plugin:validate to confirm collection metadata is correct
• Verify npm run lint:yaml passes

6. Update documentation

• Update docs/contributing/ai-artifacts-common.md with the new directory conventions — artifacts go under .github/{type}/{collection-name}/
• Update docs/contributing/ guides for agents, prompts, instructions, and skills to document the collection subdirectory requirement
• Update docs/templates/ if any templates reference the old flat paths
• Update .github/copilot-instructions.md Project Structure section to reflect the new layout
• Update any README files under .github/agents/, .github/prompts/, .github/instructions/ that reference the flat structure
• Add a section explaining that new artifacts must be placed under the subdirectory matching their collection id, and artifacts used across multiple collections go in shared/

7. Validation

• npm run lint:all passes
• npm run plugin:generate succeeds
• npm run plugin:validate passes
• All collection YAML paths resolve to existing files
• No broken applyTo patterns in instruction frontmatter
• No broken agent agents: glob paths for subagent resolution

Implementation Notes

• Use git mv for all file moves to preserve history
• The hve-core/ subdirectory under .github/instructions/ is repo-specific and excluded from collection manifests — it stays in place
• Instruction files with applyTo frontmatter patterns should be reviewed — the patterns target source files (e.g., **/*.cs) not instruction paths, so they should not need changes
• Agent files with agents: frontmatter using glob paths (e.g., .github/agents/**/codebase-researcher.agent.md) must be updated if the subagent moves to a different relative location
• The collections/hve-core-all.collection.yml includes every artifact — verify exhaustive coverage after the move
• If feat: Convert hve-core-installer agent into a Skill #635 (convert installer to skill) has merged, update the skill location instead of the agent file

Related Issues

• feat: Convert hve-core-installer agent into a Skill #635 — Convert hve-core-installer agent into a Skill (touches installer and collection config)
• chore(build): Create design-thinking.collection.yml manifest #612 — Create design-thinking.collection.yml (new collection that would follow this pattern)
• docs(docs): Create design-thinking.collection.md documentation #613 — Create design-thinking.collection.md

Files to Modify

Area	Files
Artifacts	All files under .github/agents/, .github/prompts/, .github/instructions/, .github/skills/
VS Code Settings	.vscode/settings.json
Installer	.github/agents/hve-core-installer.agent.md (or skill equivalent)
Collection Manifests	All collections/*.collection.yml files
Documentation	docs/contributing/ai-artifacts-common.md, contributing guides, .github/copilot-instructions.md, README files
Plugin Outputs	plugins/ (regenerated via npm run plugin:generate)

RPI Starter Prompts

Research Phase

Research the current artifact-to-collection mapping in hve-core. Parse all collections/*.collection.yml files to build a complete map of which artifacts belong to which collections. Identify single-collection artifacts (move to that collection's folder) versus multi-collection artifacts (move to shared/). Document the current .vscode/settings.json chat.*FilesLocations patterns and how the hve-core-installer configures them. List all applyTo patterns in instruction frontmatter and agents: glob paths in agent frontmatter that reference .github/ paths.

Plan Phase

Plan the reorganization of all AI artifacts into collection-based subdirectories. Using the research output: (1) finalize the artifact-to-folder mapping, (2) list every git mv operation needed, (3) define the updated .vscode/settings.json entries, (4) produce updated path entries for each collections/*.collection.yml, (5) list documentation files requiring path updates, (6) identify frontmatter patterns and agent glob paths that need adjustment. Include rollback instructions.

Implement Phase

Implement the collection-based directory reorganization. Execute git mv operations per the plan. Update .vscode/settings.json chat.*FilesLocations. Update all collections/*.collection.yml paths. Update the hve-core-installer's VS Code settings configuration templates. Update contributing docs with the new directory conventions. Run npm run plugin:generate, npm run plugin:validate, and npm run lint:all to validate.

Review Phase

Review the collection-based directory reorganization. Verify: (1) every artifact in every collections/*.collection.yml resolves to an existing file, (2) .vscode/settings.json patterns discover all artifacts, (3) hve-core-installer generates correct settings for all installation methods, (4) npm run plugin:generate and npm run plugin:validate succeed, (5) npm run lint:all passes, (6) documentation correctly describes the new directory conventions, (7) no broken applyTo patterns or agents: glob paths, (8) git log --follow confirms history preservation for moved files.