Overview

HVE Core has 85 unique AI assets (33 agents, 27 prompts, 24 instructions, 1 skill) organized across 9 collections — but the user-facing documentation only covers 2 of 7 agent groups, targets a single developer persona, and provides no guidance on where tools fit in the broader software development lifecycle.

This issue tracks the creation of ~21 new documentation files that close three critical gaps identified in research:

1. Zero role-specific content (F-03) — docs/README.md covers 4 of 9 target roles with no standalone role guides. Nine detailed journey cards from research have no user-facing representation.
2. No engagement stage documentation (F-05) — The 9 engagement stages (Setup → Operations) have no representation in docs. Users cannot self-identify where they are in the lifecycle or discover which tools support each stage.
3. Single-persona onboarding (F-04) — One tutorial exists (first-workflow.md) targeting developers writing PowerShell. TPMs, security architects, data scientists, BPMs, and SREs have no entry point.

Problem Statement

A TPM joining a project today has no way to discover that HVE Core offers @brd-builder, @prd-builder, @ado-prd-to-wit, and @agile-coach — tools that directly support their daily workflow across requirements gathering, product definition, work breakdown, and sprint planning. The same gap exists for every non-developer role.

Meanwhile, even experienced developers lack visibility into the full engagement lifecycle. An engineer finishing implementation (S6) doesn't know that @task-reviewer and @pr-review exist for review (S7), or that /git-merge and /ado-get-build-info support delivery (S8). Tools are discoverable only by browsing raw agent/prompt files or reading internal research artifacts.

This documentation effort transforms internal research findings into user-facing, role-indexed, stage-organized guides that let any persona find their tools in under 60 seconds.

Research Foundation

This work is backed by three research artifacts totaling ~3,000 lines of analysis:

Key findings driving this work:

• F-01: A gold-standard 10-section page template exists in RPI and GitHub Backlog docs — all new role guides will follow it
• F-06: 85 assets across the ecosystem, but only 19 have user-facing documentation
• F-07: Coverage heat map shows S6 Implementation at 30 assets (highest) vs S8 Delivery at 0 (none)
• F-08: Role asset distribution ranges from TPM (32+ dedicated assets) to Security Architect (9 assets, narrowest)
• F-09: Consistent documentation conventions already established (frontmatter schema, ATX headings, Mermaid diagrams, GitHub-flavored alerts)

Proposed Architecture

docs/
├── README.md                          ← UPDATE: expand audience table 4→9 roles
├── engagement-process/                ← NEW DIRECTORY
│   ├── README.md                      Hub: stage overview table, Mermaid flow, navigator
│   ├── setup.md                       S1: environment setup, @hve-core-installer
│   ├── discovery.md                   S2: research, BRD, security plans, ADRs
│   ├── product-definition.md          S3: PRD creation, product scoping
│   ├── decomposition.md              S4: work item breakdown from PRDs
│   ├── sprint-planning.md            S5: backlog management, sprint planning
│   ├── implementation.md             S6: code implementation (30 assets)
│   ├── review.md                      S7: code review, quality assurance
│   ├── delivery.md                    S8: merge, build verification, deployment
│   └── operations.md                  S9: monitoring, documentation maintenance
├── roles/                             ← NEW DIRECTORY
│   ├── README.md                      Hub: role overview table, collection quick ref
│   ├── engineer.md                    rpi + coding-standards collections
│   ├── tpm.md                         project-planning + ado + github collections
│   ├── tech-lead.md                   rpi + project-planning + coding-standards + prompt-engineering
│   ├── security-architect.md          security-planning collection
│   ├── data-scientist.md             data-science collection
│   ├── sre-operations.md             coding-standards + security-planning collections
│   ├── business-program-manager.md   project-planning + ado (beta coverage)
│   ├── new-contributor.md            Guided onboarding with progression model
│   └── utility.md                     Cross-role reference: session, git, docs, media

Coverage Heat Map

The engagement process guides make tooling coverage transparent at every stage:

Role → Collection Quick Reference

Each role guide will include recommended collection installs:

Deliverables Checklist

Phase 0: Project Tracking

• Create tracking issue (this issue)

Phase 1: Engagement Process Guides (docs/engagement-process/)

• README.md — Hub with stage overview table, "Where Are You?" navigator, Mermaid flow diagram with 12 transition rules
• setup.md — S1: Environment setup and configuration
• discovery.md — S2: Research, requirements gathering, architecture decisions
• product-definition.md — S3: PRD creation and product scoping
• decomposition.md — S4: Work item breakdown from PRDs
• sprint-planning.md — S5: Backlog management and sprint planning
• implementation.md — S6: Code implementation with AI assistance (highest asset density)
• review.md — S7: Code review and quality assurance
• delivery.md — S8: Merge, build verification, deployment (zero agents — prompts only)
• operations.md — S9: Operational monitoring and documentation maintenance

Phase 2: Role Guides (docs/roles/)

• README.md — Hub with role overview table, "Find Your Role" navigator, collection quick reference
• engineer.md — Software Engineer (28+ assets, deepest tooling)
• tpm.md — Technical Program Manager (32+ assets, widest surface)
• tech-lead.md — Tech Lead / Architect (25+ assets, broad coverage)
• security-architect.md — Security Architect (9 assets, narrowest — gap in S4-S8)
• data-scientist.md — Data Scientist (6 assets, narrow but focused)
• sre-operations.md — SRE / Operations Engineer (8 assets, focused)
• business-program-manager.md — Business Program Manager (beta — derived from TPM + project-planning overlap)
• new-contributor.md — New Contributor onboarding with 4-phase progression model
• utility.md — Cross-role utility reference (session management, source control, docs, media)

Phase 3: Navigation Integration

• Update docs/README.md — Expand audience table from 4 to 9 roles, add Role Guides and Engagement Process navigation sections
• Add cross-references to existing RPI, getting-started, and agent documentation

Phase 4: Validation

• All files pass npm run lint:md
• All files pass npm run lint:frontmatter
• Fix any validation issues

Known Gaps and Design Decisions

Implementation Notes

• Parallelization: Phases 1 and 2 are independent and can execute simultaneously. Phases 3 and 4 depend on 1+2 completion.
• Template: All role guides follow the 10-section gold-standard template established in docs/rpi/task-researcher.md
• Frontmatter: Uses established ms.topic values — concept for hub READMEs, how-to for role guides, tutorial for new-contributor, reference for utility
• Conventions: No H1 headings when frontmatter has title, ATX-style headings, * for unordered lists, GitHub-flavored alerts for callouts

Acceptance Criteria

1. 9 role guide files exist under docs/roles/ with complete frontmatter and 10-section content
2. 9 engagement stage files exist under docs/engagement-process/ with tool mappings, role guidance, and starter prompts
3. Hub READMEs for both sections provide "find your path" navigation with overview tables
4. docs/README.md audience table expanded to 9 roles with links to role guides
5. All new files pass npm run lint:md and npm run lint:frontmatter
6. Role guides contain starter prompts, collection recommendations, and stage walkthroughs
7. Engagement stage guides show available tools per stage with role-specific notes and transition rules

Planning Artifacts

• Plan: .copilot-tracking/plans/2026-02-18/role-based-docs-plan.instructions.md
• Details: .copilot-tracking/details/2026-02-18/role-based-docs-details.md
• Research: .copilot-tracking/research/2026-02-18/role-based-docs-research.md
• Planning Log: .copilot-tracking/plans/logs/2026-02-18/role-based-docs-log.md