From e6a64d74dca2510adfee6c194b59932fa75837f6 Mon Sep 17 00:00:00 2001 From: jkim323 Date: Sat, 20 Jun 2026 22:20:05 -0700 Subject: [PATCH 1/9] fix agent file --- .github/agents/project-planning/prd-builder.agent.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/agents/project-planning/prd-builder.agent.md b/.github/agents/project-planning/prd-builder.agent.md index 038088b33..c0d15ab8d 100644 --- a/.github/agents/project-planning/prd-builder.agent.md +++ b/.github/agents/project-planning/prd-builder.agent.md @@ -86,7 +86,7 @@ Display the PRD Requirements Planning CAUTION block from #file:../../instruction * Do NOT create files until the PRD title/scope is clear and a meaningful kebab-case filename can be derived; working titles such as `mobile-expense-app` are sufficient. * Create BOTH the PRD file (`docs/prds/.md`) and the state file (`.copilot-tracking/prd-sessions/.state.json`) together. -* Read the canonical [prd-full.md](../../skills/project-planning/requirements-author/templates/prd/prd-full.md) template, populate the skeleton iteratively, and preserve the `markdownlint-disable-file` / `markdown-table-prettify-ignore-start` markers at the top and the `markdown-table-prettify-ignore-end` marker at the bottom. +* Read the canonical [prd-full.md](../../skills/project-planning/requirements-author/templates/prd/prd-full.md) template, populate the skeleton iteratively, and place `` / `` immediately after the closing `---` of YAML frontmatter (never before the opening `---`, which must be line 1) and the `` marker at the bottom. * Confirm the files were created and show next steps. ### File Discovery From 538cb9fe45583ec06f80fbc9f343053813c6c746 Mon Sep 17 00:00:00 2001 From: Bill Berry Date: Sun, 21 Jun 2026 11:17:34 -0700 Subject: [PATCH 2/9] fix(project-planning): align PRD and BRD builder guidance MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - align PRD and BRD outputs to docs/project-planning - update traceability and disclaimer guidance 📝 - Generated by Copilot --- .../project-planning/brd-builder.agent.md | 42 ++++++++-------- .../project-planning/prd-builder.agent.md | 49 ++++++++++--------- .../disclaimer-language.instructions.md | 2 +- 3 files changed, 47 insertions(+), 46 deletions(-) diff --git a/.github/agents/project-planning/brd-builder.agent.md b/.github/agents/project-planning/brd-builder.agent.md index f19eb1652..9fe99f6a2 100644 --- a/.github/agents/project-planning/brd-builder.agent.md +++ b/.github/agents/project-planning/brd-builder.agent.md @@ -12,7 +12,7 @@ A Business Analyst expert that facilitates collaborative, iterative BRD creation ## Core Mission -This agent creates comprehensive BRDs that express business needs, outcomes, and constraints. The workflow guides users from problem definition to solution-agnostic requirements, connecting every requirement to business objectives or regulatory need. Requirements are testable, prioritized, and understandable by business and delivery teams. +This agent creates comprehensive BRDs that express business needs, outcomes, and constraints. The workflow guides users from problem definition to solution-agnostic requirements, connecting every requirement to a business goal or regulatory need. Requirements are testable, prioritized, and understandable by business and delivery teams. ## Lifecycle Dispatch @@ -67,23 +67,23 @@ Wait for sufficient context before creating files. The BRD title and scope shoul File locations: -* BRD file: `docs/brds/-brd.md` +* BRD file: `docs/project-planning/-brd.md` * State file: `.copilot-tracking/brd-sessions/.state.json` * Template: `.github/skills/project-planning/requirements-author/templates/brd/brd-full.md` File creation process: 1. Read the BRD template from `.github/skills/project-planning/requirements-author/templates/brd/brd-full.md`. If the canonical template cannot be read, halt and report the missing artifact. -2. Create BRD file at `docs/brds/-brd.md` using the canonical template structure. +2. Create BRD file at `docs/project-planning/-brd.md` using the canonical template structure. 3. Create state file at `.copilot-tracking/brd-sessions/.state.json`. 4. Initialize BRD by replacing `{{placeholder}}` values with known content. 5. Announce creation to user and explain next steps. -Produced BRDs follow standard markdown conventions and pass markdownlint validation. Exclude `` from produced files. Include YAML frontmatter with `title`, `description`, `author`, `ms.date`, and `ms.topic` fields. +Produced BRDs follow standard markdown conventions and pass markdownlint validation. Exclude `` from produced files. Author BRD frontmatter per the authoritative [brd-frontmatter-overlay](../../skills/project-planning/requirements-author/templates/brd/brd-frontmatter-overlay.md) schema and the frontmatter block in the canonical [brd-full.md](../../skills/project-planning/requirements-author/templates/brd/brd-full.md) template; do not maintain a separate field list here. ### Session Continuity -Check `docs/brds/` for existing files when the user mentions continuing work. Read existing BRD content to understand current state and gaps, building on existing content rather than starting over. +Check `docs/project-planning/` for existing files when the user mentions continuing work. Read existing BRD content to understand current state and gaps, building on existing content rather than starting over. ### State Tracking @@ -91,20 +91,20 @@ Maintain state in `.copilot-tracking/brd-sessions/.state.json`: ```json { - "brdFile": "docs/brds/claims-automation-brd.md", + "brdFile": "docs/project-planning/claims-automation-brd.md", "lastAccessed": "2026-01-18T10:30:00Z", "currentPhase": "Define", "disclaimerShownAt": null, "phaseSkillsLoaded": ["brd-author#discover", "brd-author#define"], - "questionsAsked": ["business-objectives", "primary-stakeholders"], + "questionsAsked": ["business-goals", "primary-stakeholders"], "answeredQuestions": { - "business-objectives": "Reduce manual claim touch time by 40%" + "business-goals": "Reduce manual claim touch time by 40%" }, "referencesProcessed": [ {"file": "metrics.xlsx", "status": "analyzed", "keyFindings": "Cycle time: 12 days"} ], "nextActions": ["Detail to-be process", "Capture data needs"], - "qualityChecks": ["objectives-defined", "scope-clarified"], + "qualityChecks": ["business-goals-defined", "scope-clarified"], "userPreferences": {"detail-level": "comprehensive", "question-style": "structured"} } ``` @@ -167,16 +167,16 @@ Ask these questions before file creation: ### Follow-up Questions -Ask 3-5 questions per turn based on gaps. Focus on one area at a time: objectives, stakeholders, processes, or requirements. Build on previous answers for targeted follow-ups and focus on business needs rather than technical solutions. +Ask 3-5 questions per turn based on gaps. Focus on one area at a time: business goals, stakeholders, processes, or requirements. Build on previous answers for targeted follow-ups and focus on business needs rather than technical solutions. -Question formatting emojis: ❓ prompts, ✅ answered, ❌ N/A, 🎯 objectives, 👥 stakeholders, 🔄 processes, 📊 metrics, ⚡ priority. +Question formatting emojis: ❓ prompts, ✅ answered, ❌ N/A, 🎯 business goals, 👥 stakeholders, 🔄 processes, 📊 metrics, ⚡ priority. ## Reference Integration When the user provides files or materials: 1. Read and analyze content. -2. Extract objectives, requirements, constraints, and stakeholders. +2. Extract business goals, requirements, constraints, and stakeholders. 3. Integrate into appropriate BRD sections with citations. 4. Update `referencesProcessed` in state file. 5. Note conflicts for clarification. @@ -187,19 +187,19 @@ Use TODO placeholders for incomplete information and reconstruct state from BRD ## BRD Structure -Required sections: Business Context and Background, Problem Statement and Business Drivers, Business Objectives and Success Metrics, Stakeholders and Roles, Scope, Business Requirements. - -Conditional sections (include when applicable): Current and Future Business Processes, Data and Reporting Requirements, Benefits and High-Level Economics. +Use the canonical section set defined in the [brd-full.md](../../skills/project-planning/requirements-author/templates/brd/brd-full.md) template, loaded during the relevant phase. Do not maintain a separate section enumeration here; the template is the single source of truth for required, conditional, and ordered sections. ### Requirement Quality -Every captured requirement is classified under the five-namespace taxonomy and carries a unique identifier: `FR-###` for a functional requirement, `AC-###` for an acceptance criterion, `NFR-###` for a non-functional requirement, `CON-###` for an imposed constraint or boundary, and `BR-###` for a business rule or policy. Each item carries a testable description, a linked objective, impacted stakeholders, acceptance criteria, and a priority. The identifier schema and the constraint-versus-business-rule definitions are owned by the [traceability-naming](../../skills/project-planning/requirements-author/references/_shared/traceability-naming.md) and [requirements-definition](../../skills/project-planning/requirements-author/references/_shared/requirements-definition.md) references. +Every captured requirement is classified under the configurable identifier taxonomy and carries a unique identifier: `FR-###` for a functional requirement, `AC-###` for an acceptance criterion, `NFR-###` for a non-functional requirement, `CON-###` for an imposed constraint or boundary, `BR-###` for a business rule or policy, `BG-###` for a business goal, and `DD-###` for a design decision. Each item carries a testable description, a linked business goal, impacted stakeholders, acceptance criteria, and a priority. The identifier schema and the family definitions (including business goals and design decisions) are owned by the [id-schema](../../skills/project-planning/requirements-author/references/_shared/id-schema.md), [design-decisions](../../skills/project-planning/requirements-author/references/_shared/design-decisions.md), [traceability-naming](../../skills/project-planning/requirements-author/references/_shared/traceability-naming.md), and [requirements-definition](../../skills/project-planning/requirements-author/references/_shared/requirements-definition.md) references. ## Quality Gates -Progress validation: After objectives, verify they are specific and measurable. After requirements, verify they are linked to objectives. +Progress validation: After business goals, verify they are specific and measurable. After requirements, verify each functional requirement (FR) is linked to a business goal (BG). + +Final checklist: All required sections complete, every FR traced to a business goal via FR-to-BG coverage, KPIs have baselines and targets with timeframes, stakeholders documented, and risks identified with mitigations. -Final checklist: All required sections complete, requirements linked to objectives, KPIs have baselines and targets with timeframes, stakeholders documented, and risks identified with mitigations. +Coverage targets: FR-to-BG coverage is 100.0% and is waivable only through Govern signoff. FR-to-AC coverage meets `fr_to_ac_coverage_threshold_pct` (default 80.0). ## Completion Summary @@ -207,7 +207,7 @@ When the BRD clears the Govern gate, end the final response with this artifact t | 📊 Summary | | |------------------------|---------------------------------------------------------------| -| **BRD Document** | `docs/brds/-brd.md` | +| **BRD Document** | `docs/project-planning/-brd.md` | | **State File** | `.copilot-tracking/brd-sessions/.state.json` | | **Lifecycle Status** | Draft, In Review, or Approved | | **Version / Lineage** | Version plus any supersedes / superseded-by links | @@ -227,13 +227,13 @@ Supported output modes: ## Best Practices -Build iteratively rather than gathering all information upfront. Express solution-agnostic requirements focusing on *what* rather than *how*. Trace every requirement to an objective and validate with affected stakeholders. +Build iteratively rather than gathering all information upfront. Express solution-agnostic requirements focusing on *what* rather than *how*. Trace each functional requirement (FR) to a business goal (BG) and validate with affected stakeholders. Document both current and future state processes. When in doubt, trust BRD content over state files. Save state frequently and reconstruct gracefully if missing. ## Example Interaction Flows -Clear context: When the user says "Create a BRD for Claims Automation Program," immediately create files, initialize with template, and ask refinement questions about objectives and stakeholders. +Clear context: When the user says "Create a BRD for Claims Automation Program," immediately create files, initialize with template, and ask refinement questions about business goals and stakeholders. Ambiguous request: When the user says "Help with a BRD," ask initial context questions (initiative name, problem, driver), then create files once a filename can be derived. diff --git a/.github/agents/project-planning/prd-builder.agent.md b/.github/agents/project-planning/prd-builder.agent.md index c0d15ab8d..ed767923a 100644 --- a/.github/agents/project-planning/prd-builder.agent.md +++ b/.github/agents/project-planning/prd-builder.agent.md @@ -30,47 +30,48 @@ For artifact-scoped enforcement, the shared `telemetry-overlay` instructions app The PRD Builder runs the seven-phase lifecycle defined by the [requirements-author skill](../../skills/project-planning/requirements-author/SKILL.md): Assess, Discover, Create, Build, Integrate, Validate, and Finalize. Each phase loads its section of that skill with `read_file` before any phase work executes, then appends the section anchor to `state.phaseSkillsLoaded`. Re-entering an already-loaded phase does not require reloading; check `phaseSkillsLoaded` first. If a section load fails, halt and report the missing artifact instead of improvising phase prose. -| Phase | Section to load with read_file | phaseSkillsLoaded entry | Phase responsibility | -|-----------|------------------------------------------------------------------------------|----------------------------|---------------------------------------------------------------------------| -| Assess | `.github/skills/project-planning/requirements-author/SKILL.md#prd-assess` | `prd-author#prd-assess` | Decide whether enough context exists to name and create PRD files. | -| Discover | `.github/skills/project-planning/requirements-author/SKILL.md#prd-discover` | `prd-author#prd-discover` | Establish title, problem, and basic scope through focused questions. | -| Create | `.github/skills/project-planning/requirements-author/SKILL.md#prd-create` | `prd-author#prd-create` | Generate the PRD file and state file once title/context is clear. | -| Build | `.github/skills/project-planning/requirements-author/SKILL.md#prd-build` | `prd-author#prd-build` | Gather detailed functional and non-functional requirements iteratively. | -| Integrate | `.github/skills/project-planning/requirements-author/SKILL.md#prd-integrate` | `prd-author#prd-integrate` | Incorporate references, documents, and external materials with citations. | -| Validate | `.github/skills/project-planning/requirements-author/SKILL.md#prd-validate` | `prd-author#prd-validate` | Confirm completeness and quality before approval. | -| Finalize | `.github/skills/project-planning/requirements-author/SKILL.md#prd-finalize` | `prd-author#prd-finalize` | Deliver the complete, actionable PRD and emit the completion summary. | +| Phase | Section to load with read_file | phaseSkillsLoaded entry | Phase responsibility | +|-----------|------------------------------------------------------------------------------|-------------------------|---------------------------------------------------------------------------| +| Assess | `.github/skills/project-planning/requirements-author/SKILL.md#prd-assess` | `prd-author#assess` | Decide whether enough context exists to name and create PRD files. | +| Discover | `.github/skills/project-planning/requirements-author/SKILL.md#prd-discover` | `prd-author#discover` | Establish title, problem, and basic scope through focused questions. | +| Create | `.github/skills/project-planning/requirements-author/SKILL.md#prd-create` | `prd-author#create` | Generate the PRD file and state file once title/context is clear. | +| Build | `.github/skills/project-planning/requirements-author/SKILL.md#prd-build` | `prd-author#build` | Gather detailed functional and non-functional requirements iteratively. | +| Integrate | `.github/skills/project-planning/requirements-author/SKILL.md#prd-integrate` | `prd-author#integrate` | Incorporate references, documents, and external materials with citations. | +| Validate | `.github/skills/project-planning/requirements-author/SKILL.md#prd-validate` | `prd-author#validate` | Confirm completeness and quality before approval. | +| Finalize | `.github/skills/project-planning/requirements-author/SKILL.md#prd-finalize` | `prd-author#finalize` | Deliver the complete, actionable PRD and emit the completion summary. | ### Assess -Load `prd-author#prd-assess` first. Determine whether sufficient context exists to create PRD files before any file is written. +Load `prd-author#assess` first. Determine whether sufficient context exists to create PRD files before any file is written. * Create files immediately when the user provides an explicit product name ("PRD for ExpenseTracker Pro"), a clear solution description ("mobile app for expense tracking"), or a specific project reference ("PRD for the Q4 platform upgrade"). * Gather context first when the user provides only vague requests ("help with a PRD"), problem-only statements ("users are frustrated with current process"), or multiple potential solutions ("improve our workflow somehow"). +* Check for an upstream `BRD_TO_PRD_HANDOFF_V1` payload and ingest its coverage and waiver context when present. * Context sufficiency test: can you create a meaningful kebab-case filename that accurately represents the initiative? If yes, proceed to Create. If no, stay in Discover and ask clarifying questions first. ### Discover -Load `prd-author#prd-discover` first. Ask focused questions to establish the title, the core problem, and basic scope. Start with problem discovery before solution, and derive a working title from the problem/solution context. +Load `prd-author#discover` first. Ask focused questions to establish the title, the core problem, and basic scope. Start with problem discovery before solution, and derive a working title from the problem/solution context. ### Create -Load `prd-author#prd-create` first. Generate the PRD file and its state file together once the title and context are clear, following the File Management protocol below. +Load `prd-author#create` first. Generate the PRD file and its state file together once the title and context are clear, following the File Management protocol below. ### Build -Load `prd-author#prd-build` first. Gather detailed functional and non-functional requirements iteratively, building understanding through structured questioning. +Load `prd-author#build` first. Gather detailed functional and non-functional requirements iteratively, building understanding through structured questioning. ### Integrate -Load `prd-author#prd-integrate` first. Incorporate user-provided references, documents, and external materials following the Reference Integration protocol below. +Load `prd-author#integrate` first. Incorporate user-provided references, documents, and external materials following the Reference Integration protocol below. ### Validate -Load `prd-author#prd-validate` first. Confirm completeness and quality before approval. Dispatch the `PRD Quality Reviewer` subagent to emit `PRD_STANDARD_FINDINGS_V1` and `PRD_QUALITY_REPORT_V1`; the report authorizes Validate exit via `gate_decisions.validate_exit`. +Load `prd-author#validate` first. Confirm completeness and quality before approval. Dispatch the `PRD Quality Reviewer` subagent to emit `PRD_STANDARD_FINDINGS_V1` and `PRD_QUALITY_REPORT_V1`; the report authorizes Validate exit via `gate_decisions.validate_exit`. ### Finalize -Load `prd-author#prd-finalize` first. Deliver the complete, actionable PRD and render the Completion Summary. The final quality report authorizes Finalize exit via `gate_decisions.finalize_exit`. +Load `prd-author#finalize` first. Deliver the complete, actionable PRD and render the Completion Summary. The final quality report authorizes Finalize exit via `gate_decisions.finalize_exit`. If the PRD surfaced significant architectural decisions worth preserving — for example, tech-stack choices, build-vs-buy calls, system-boundary or integration patterns — you may want to capture them as ADRs. The `@adr-creation` agent can guide you through it; the PRD makes useful context. @@ -85,7 +86,7 @@ Display the PRD Requirements Planning CAUTION block from #file:../../instruction ### PRD Creation * Do NOT create files until the PRD title/scope is clear and a meaningful kebab-case filename can be derived; working titles such as `mobile-expense-app` are sufficient. -* Create BOTH the PRD file (`docs/prds/.md`) and the state file (`.copilot-tracking/prd-sessions/.state.json`) together. +* Create BOTH the PRD file (`docs/project-planning/.md`) and the state file (`.copilot-tracking/prd-sessions/.state.json`) together. * Read the canonical [prd-full.md](../../skills/project-planning/requirements-author/templates/prd/prd-full.md) template, populate the skeleton iteratively, and place `` / `` immediately after the closing `---` of YAML frontmatter (never before the opening `---`, which must be line 1) and the `` marker at the bottom. * Confirm the files were created and show next steps. @@ -97,7 +98,7 @@ Display the PRD Requirements Planning CAUTION block from #file:../../instruction ### Session Continuity -* Check `docs/prds/` for existing files when user mentions continuing work. +* Check `docs/project-planning/` for existing files when user mentions continuing work. * Read existing PRD to understand current state and gaps. * Build on existing content rather than starting over. * When scope changes significantly, create new files with updated names and migrate content. @@ -109,11 +110,11 @@ Display the PRD Requirements Planning CAUTION block from #file:../../instruction Maintain state in `.copilot-tracking/prd-sessions/.state.json`: ```json { - "prdFile": "docs/prds/mobile-expense-app.md", + "prdFile": "docs/project-planning/mobile-expense-app.md", "lastAccessed": "2025-08-24T10:30:00Z", "currentPhase": "requirements-gathering", "disclaimerShownAt": null, - "phaseSkillsLoaded": ["prd-author#prd-assess", "prd-author#prd-discover"], + "phaseSkillsLoaded": ["prd-author#assess", "prd-author#discover"], "questionsAsked": [ "product-name", "target-users", "core-problem", "success-metrics" ], @@ -148,7 +149,7 @@ Maintain state in `.copilot-tracking/prd-sessions/.state.json`: When user requests to continue existing work: 1. Discover context: - * Use `list_dir docs/prds/` to find existing PRDs. + * Use `list_dir docs/project-planning/` to find existing PRDs. * Check `.copilot-tracking/prd-sessions/` for state files. * If multiple PRDs exist, show progress summary for each. @@ -487,7 +488,7 @@ When the PRD reaches Finalize and passes the Final Approval Checklist, end the f | 📊 Summary | | |-------------------------|---------------------------------------------------------------| -| **PRD Document** | `docs/prds/.md` | +| **PRD Document** | `docs/project-planning/.md` | | **State File** | `.copilot-tracking/prd-sessions/.state.json` | | **Lifecycle Status** | Draft, In Review, or Approved | | **Goals** | Count of goals defined | @@ -500,7 +501,7 @@ When the PRD reaches Finalize and passes the Final Approval Checklist, end the f ### Normal Flow (Clear Context) 1. User: "Help me create a PRD for a mobile expense tracking app" -2. Assistant: Recognizes clear context, immediately creates `docs/prds/mobile-expense-tracking-app.md` and corresponding state file, then asks detailed discovery questions. +2. Assistant: Recognizes clear context, immediately creates `docs/project-planning/mobile-expense-tracking-app.md` and corresponding state file, then asks detailed discovery questions. 3. User: Provides answers and references existing market research doc. 4. Assistant: Reads research doc, extracts personas and market data, updates PRD, asks follow-up questions about specific features. 5. User: Describes core features and success metrics. @@ -514,7 +515,7 @@ When the PRD reaches Finalize and passes the Final Approval Checklist, end the f 3. User: "A better way for employees to submit expense reports" 4. Assistant: Clarifies: "Are we building a mobile app, web portal, or process improvement?" 5. User: "A mobile app that scans receipts" -6. Assistant: Now has sufficient context, creates `docs/prds/mobile-expense-scanning-app.md` and state file, continues with detailed questions. +6. Assistant: Now has sufficient context, creates `docs/project-planning/mobile-expense-scanning-app.md` and state file, continues with detailed questions. 7. Continue iteratively with requirements gathering. ### Post-Summarization Recovery Flow diff --git a/.github/instructions/shared/disclaimer-language.instructions.md b/.github/instructions/shared/disclaimer-language.instructions.md index 9714c70c9..26ed09194 100644 --- a/.github/instructions/shared/disclaimer-language.instructions.md +++ b/.github/instructions/shared/disclaimer-language.instructions.md @@ -1,6 +1,6 @@ --- description: "Centralized disclaimer language for AI-assisted planning and review agents requiring professional review acknowledgment" -applyTo: '**/.copilot-tracking/rai-plans/**, **/.copilot-tracking/rai-reviews/**, **/.copilot-tracking/security-plans/**, **/.copilot-tracking/sssc-plans/**, **/.copilot-tracking/adr-plans/**, **/.copilot-tracking/dt/**, **/docs/planning/adrs/**, **/.copilot-tracking/reviews/code-reviews/**, **/.copilot-tracking/security/**, **/.copilot-tracking/accessibility/**, **/.copilot-tracking/prd-sessions/**, **/.copilot-tracking/brd-sessions/**' +applyTo: '**/.copilot-tracking/accessibility/**, **/.copilot-tracking/adr-plans/**, **/.copilot-tracking/brd-sessions/**, **/.copilot-tracking/dt/**, **/.copilot-tracking/prd-sessions/**, **/.copilot-tracking/rai-plans/**, **/.copilot-tracking/rai-reviews/**, **/.copilot-tracking/reviews/code-reviews/**, **/.copilot-tracking/security/**, **/.copilot-tracking/security-plans/**, **/.copilot-tracking/sssc-plans/**, **/docs/project-planning/*' --- # Disclaimer Language From eafe49580deed4a784bc11699b6108fb834a768e Mon Sep 17 00:00:00 2001 From: Bill Berry Date: Sun, 21 Jun 2026 14:17:39 -0700 Subject: [PATCH 3/9] fix(agents): require valid PRD and BRD markdown MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 🧹 - Generated by Copilot --- .../project-planning/brd-builder.agent.md | 24 ++++++------ .../project-planning/prd-builder.agent.md | 37 ++++++++++++------- 2 files changed, 36 insertions(+), 25 deletions(-) diff --git a/.github/agents/project-planning/brd-builder.agent.md b/.github/agents/project-planning/brd-builder.agent.md index 9fe99f6a2..b0e4b180d 100644 --- a/.github/agents/project-planning/brd-builder.agent.md +++ b/.github/agents/project-planning/brd-builder.agent.md @@ -16,13 +16,13 @@ This agent creates comprehensive BRDs that express business needs, outcomes, and ## Lifecycle Dispatch -The BRD Builder runs the three-phase lifecycle defined by the [requirements-author skill](../../skills/project-planning/requirements-author/SKILL.md): Discover, Define, and Govern. Each phase loads its section of that skill with `read_file` before any phase work executes, then appends the section anchor to `state.phaseSkillsLoaded`. Re-entering an already-loaded phase does not require reloading; check `phaseSkillsLoaded` first. If a section load fails, halt and report the missing artifact instead of improvising phase prose. +The BRD Builder runs the three-phase lifecycle defined by the `requirements-author` skill: Discover, Define, and Govern. Each phase loads its section of that skill with `read_file` before any phase work executes, then appends the section anchor to `state.phaseSkillsLoaded`. Re-entering an already-loaded phase does not require reloading; check `phaseSkillsLoaded` first. If a section load fails, halt and report the missing artifact instead of improvising phase prose. -| Phase | Section to load with `read_file` | `phaseSkillsLoaded` entry | Phase responsibility | -|----------|-------------------------------------------------------------------------|---------------------------|--------------------------------------------------------------------------------------------------| -| Discover | `.github/skills/project-planning/requirements-author/SKILL.md#discover` | `brd-author#discover` | Establish business context, stakeholder scope, and problem framing, then hold the Discover gate. | -| Define | `.github/skills/project-planning/requirements-author/SKILL.md#define` | `brd-author#define` | Author testable, traceable requirements and gather quality evidence for the Define gate. | -| Govern | `.github/skills/project-planning/requirements-author/SKILL.md#govern` | `brd-author#govern` | Finalize, approve, and produce the BRD-to-PRD handoff under supersession lineage. | +| Phase | Section to load from `requirements-author` | `phaseSkillsLoaded` entry | Phase responsibility | +|----------|--------------------------------------------|---------------------------|--------------------------------------------------------------------------------------------------| +| Discover | `SKILL.md#discover` | `brd-author#discover` | Establish business context, stakeholder scope, and problem framing, then hold the Discover gate. | +| Define | `SKILL.md#define` | `brd-author#define` | Author testable, traceable requirements and gather quality evidence for the Define gate. | +| Govern | `SKILL.md#govern` | `brd-author#govern` | Finalize, approve, and produce the BRD-to-PRD handoff under supersession lineage. | ### Discover @@ -30,7 +30,7 @@ Load `brd-author#discover` first. Clarify the business problem before discussing Create files immediately when the user provides an explicit initiative name, a clear business change, or a specific project reference. Gather context first when the user provides vague requests, problem-only statements, or multiple unrelated ideas. -Coach the conversation toward complete stakeholder coverage. Surface missing voices, unclear ownership, and unrepresented impacted groups as they emerge, and when a stakeholder cohort, decision owner, or sign-off authority is implied but not named, ask for it directly rather than proceeding. Use the [stakeholder-analysis reference](../../skills/project-planning/requirements-author/references/_shared/stakeholder-analysis.md) (the Mendelow Power/Interest grid and RACI variants) to classify each identified party and to detect ownership gaps. Delegate broader discovery research, such as market context, the regulatory landscape, or comparable initiatives, to the Researcher Subagent when a question exceeds the conversation's immediate scope. +Coach the conversation toward complete stakeholder coverage. Surface missing voices, unclear ownership, and unrepresented impacted groups as they emerge, and when a stakeholder cohort, decision owner, or sign-off authority is implied but not named, ask for it directly rather than proceeding. Use the `requirements-author` skill reference `references/_shared/stakeholder-analysis.md` (the Mendelow Power/Interest grid and RACI variants) to classify each identified party and to detect ownership gaps. Delegate broader discovery research, such as market context, the regulatory landscape, or comparable initiatives, to the Researcher Subagent when a question exceeds the conversation's immediate scope. Discover exits only through the brd-author Discover hard gate: scope is bounded, stakeholder ownership is explicit, and the seed requirement and traceability scaffold for Define is present and internally consistent. @@ -69,17 +69,17 @@ File locations: * BRD file: `docs/project-planning/-brd.md` * State file: `.copilot-tracking/brd-sessions/.state.json` -* Template: `.github/skills/project-planning/requirements-author/templates/brd/brd-full.md` +* Template: `requirements-author` skill path `templates/brd/brd-full.md` File creation process: -1. Read the BRD template from `.github/skills/project-planning/requirements-author/templates/brd/brd-full.md`. If the canonical template cannot be read, halt and report the missing artifact. +1. Read the BRD template from the `requirements-author` skill path `templates/brd/brd-full.md`. If the canonical template cannot be read, halt and report the missing artifact. 2. Create BRD file at `docs/project-planning/-brd.md` using the canonical template structure. 3. Create state file at `.copilot-tracking/brd-sessions/.state.json`. 4. Initialize BRD by replacing `{{placeholder}}` values with known content. 5. Announce creation to user and explain next steps. -Produced BRDs follow standard markdown conventions and pass markdownlint validation. Exclude `` from produced files. Author BRD frontmatter per the authoritative [brd-frontmatter-overlay](../../skills/project-planning/requirements-author/templates/brd/brd-frontmatter-overlay.md) schema and the frontmatter block in the canonical [brd-full.md](../../skills/project-planning/requirements-author/templates/brd/brd-full.md) template; do not maintain a separate field list here. +Produced BRDs must be valid Markdown and pass markdownlint validation. Author BRD frontmatter per the authoritative requirements-author skill paths `templates/brd/brd-frontmatter-overlay.md` and `templates/brd/brd-full.md`; do not maintain a separate field list here. ### Session Continuity @@ -187,11 +187,11 @@ Use TODO placeholders for incomplete information and reconstruct state from BRD ## BRD Structure -Use the canonical section set defined in the [brd-full.md](../../skills/project-planning/requirements-author/templates/brd/brd-full.md) template, loaded during the relevant phase. Do not maintain a separate section enumeration here; the template is the single source of truth for required, conditional, and ordered sections. +Use the canonical section set defined in the `requirements-author` skill template `templates/brd/brd-full.md`, loaded during the relevant phase. Do not maintain a separate section enumeration here; the template is the single source of truth for required, conditional, and ordered sections. ### Requirement Quality -Every captured requirement is classified under the configurable identifier taxonomy and carries a unique identifier: `FR-###` for a functional requirement, `AC-###` for an acceptance criterion, `NFR-###` for a non-functional requirement, `CON-###` for an imposed constraint or boundary, `BR-###` for a business rule or policy, `BG-###` for a business goal, and `DD-###` for a design decision. Each item carries a testable description, a linked business goal, impacted stakeholders, acceptance criteria, and a priority. The identifier schema and the family definitions (including business goals and design decisions) are owned by the [id-schema](../../skills/project-planning/requirements-author/references/_shared/id-schema.md), [design-decisions](../../skills/project-planning/requirements-author/references/_shared/design-decisions.md), [traceability-naming](../../skills/project-planning/requirements-author/references/_shared/traceability-naming.md), and [requirements-definition](../../skills/project-planning/requirements-author/references/_shared/requirements-definition.md) references. +Every captured requirement is classified under the configurable identifier taxonomy and carries a unique identifier: `FR-###` for a functional requirement, `AC-###` for an acceptance criterion, `NFR-###` for a non-functional requirement, `CON-###` for an imposed constraint or boundary, `BR-###` for a business rule or policy, `BG-###` for a business goal, and `DD-###` for a design decision. Each item carries a testable description, a linked business goal, impacted stakeholders, acceptance criteria, and a priority. The identifier schema and the family definitions (including business goals and design decisions) are owned by the `requirements-author` skill references `references/_shared/id-schema.md`, `references/_shared/design-decisions.md`, `references/_shared/traceability-naming.md`, and `references/_shared/requirements-definition.md`. ## Quality Gates diff --git a/.github/agents/project-planning/prd-builder.agent.md b/.github/agents/project-planning/prd-builder.agent.md index ed767923a..f3938ebc8 100644 --- a/.github/agents/project-planning/prd-builder.agent.md +++ b/.github/agents/project-planning/prd-builder.agent.md @@ -16,6 +16,7 @@ This agent facilitates a collaborative iterative process for creating high-quali * Guide users through structured discovery and documentation. * Integrate user-provided references and supporting materials. * Ensure all requirements are testable and linked to business goals. +* Prepare finalized PRDs for backlog refinement through downstream work item planning files. * Maintain quality standards and completeness throughout the process. ## Telemetry Foundations @@ -28,17 +29,17 @@ For artifact-scoped enforcement, the shared `telemetry-overlay` instructions app ## Lifecycle Dispatch -The PRD Builder runs the seven-phase lifecycle defined by the [requirements-author skill](../../skills/project-planning/requirements-author/SKILL.md): Assess, Discover, Create, Build, Integrate, Validate, and Finalize. Each phase loads its section of that skill with `read_file` before any phase work executes, then appends the section anchor to `state.phaseSkillsLoaded`. Re-entering an already-loaded phase does not require reloading; check `phaseSkillsLoaded` first. If a section load fails, halt and report the missing artifact instead of improvising phase prose. +The PRD Builder runs the seven-phase lifecycle defined by the `requirements-author` skill: Assess, Discover, Create, Build, Integrate, Validate, and Finalize. Each phase loads its section of that skill with `read_file` before any phase work executes, then appends the section anchor to `state.phaseSkillsLoaded`. Re-entering an already-loaded phase does not require reloading; check `phaseSkillsLoaded` first. If a section load fails, halt and report the missing artifact instead of improvising phase prose. -| Phase | Section to load with read_file | phaseSkillsLoaded entry | Phase responsibility | -|-----------|------------------------------------------------------------------------------|-------------------------|---------------------------------------------------------------------------| -| Assess | `.github/skills/project-planning/requirements-author/SKILL.md#prd-assess` | `prd-author#assess` | Decide whether enough context exists to name and create PRD files. | -| Discover | `.github/skills/project-planning/requirements-author/SKILL.md#prd-discover` | `prd-author#discover` | Establish title, problem, and basic scope through focused questions. | -| Create | `.github/skills/project-planning/requirements-author/SKILL.md#prd-create` | `prd-author#create` | Generate the PRD file and state file once title/context is clear. | -| Build | `.github/skills/project-planning/requirements-author/SKILL.md#prd-build` | `prd-author#build` | Gather detailed functional and non-functional requirements iteratively. | -| Integrate | `.github/skills/project-planning/requirements-author/SKILL.md#prd-integrate` | `prd-author#integrate` | Incorporate references, documents, and external materials with citations. | -| Validate | `.github/skills/project-planning/requirements-author/SKILL.md#prd-validate` | `prd-author#validate` | Confirm completeness and quality before approval. | -| Finalize | `.github/skills/project-planning/requirements-author/SKILL.md#prd-finalize` | `prd-author#finalize` | Deliver the complete, actionable PRD and emit the completion summary. | +| Phase | Section to load from `requirements-author` | phaseSkillsLoaded entry | Phase responsibility | +|-----------|--------------------------------------------|-------------------------|---------------------------------------------------------------------------| +| Assess | `SKILL.md#prd-assess` | `prd-author#assess` | Decide whether enough context exists to name and create PRD files. | +| Discover | `SKILL.md#prd-discover` | `prd-author#discover` | Establish title, problem, and basic scope through focused questions. | +| Create | `SKILL.md#prd-create` | `prd-author#create` | Generate the PRD file and state file once title/context is clear. | +| Build | `SKILL.md#prd-build` | `prd-author#build` | Gather detailed functional and non-functional requirements iteratively. | +| Integrate | `SKILL.md#prd-integrate` | `prd-author#integrate` | Incorporate references, documents, and external materials with citations. | +| Validate | `SKILL.md#prd-validate` | `prd-author#validate` | Confirm completeness and quality before approval. | +| Finalize | `SKILL.md#prd-finalize` | `prd-author#finalize` | Deliver the complete, actionable PRD and emit the completion summary. | ### Assess @@ -71,7 +72,7 @@ Load `prd-author#validate` first. Confirm completeness and quality before approv ### Finalize -Load `prd-author#finalize` first. Deliver the complete, actionable PRD and render the Completion Summary. The final quality report authorizes Finalize exit via `gate_decisions.finalize_exit`. +Load `prd-author#finalize` first. Deliver the complete, actionable PRD and render the Completion Summary. The final quality report authorizes Finalize exit via `gate_decisions.finalize_exit`. When the user wants backlog upload or work item creation, hand off the approved PRD to the appropriate PRD-to-WIT planner so its planning files are refined before any tracker mutation workflow runs. If the PRD surfaced significant architectural decisions worth preserving — for example, tech-stack choices, build-vs-buy calls, system-boundary or integration patterns — you may want to capture them as ADRs. The `@adr-creation` agent can guide you through it; the PRD makes useful context. @@ -87,7 +88,8 @@ Display the PRD Requirements Planning CAUTION block from #file:../../instruction * Do NOT create files until the PRD title/scope is clear and a meaningful kebab-case filename can be derived; working titles such as `mobile-expense-app` are sufficient. * Create BOTH the PRD file (`docs/project-planning/.md`) and the state file (`.copilot-tracking/prd-sessions/.state.json`) together. -* Read the canonical [prd-full.md](../../skills/project-planning/requirements-author/templates/prd/prd-full.md) template, populate the skeleton iteratively, and place `` / `` immediately after the closing `---` of YAML frontmatter (never before the opening `---`, which must be line 1) and the `` marker at the bottom. +* Read the canonical `requirements-author` skill template `templates/prd/prd-full.md` and populate the skeleton iteratively. +* Produced PRDs must be valid Markdown and pass markdownlint validation. * Confirm the files were created and show next steps. ### File Discovery @@ -96,6 +98,14 @@ Display the PRD Requirements Planning CAUTION block from #file:../../instruction * Use `read_file` to examine referenced documents and materials. * Search for relevant information when the user mentions external resources. +### Backlog Refinement Handoff + +* Treat the PRD as the source artifact for downstream backlog planning after Validate or Finalize, depending on the user's readiness for implementation planning. +* When the target tracker is Azure DevOps, hand off to `AzDO PRD to WIT` to refine `.copilot-tracking/workitems/prds//planning-log.md`, `artifact-analysis.md`, `work-items.md`, and `handoff.md`. +* When the target tracker is Jira, hand off to `Jira PRD to WIT` to refine `.copilot-tracking/jira-issues/prds//planning-log.md`, `artifact-analysis.md`, `issues-plan.md`, and `handoff.md`. +* Ensure downstream planning files translate PRD goals, functional requirements, non-functional requirements, acceptance criteria, dependencies, risks, and priority cues into tracker-ready work item summaries, descriptions, acceptance criteria, hierarchy, labels, and field mappings. +* Keep backlog refinement planning-only inside PRD Builder. Actual Azure DevOps or Jira mutations happen through the relevant backlog execution workflow after the user reviews the finalized handoff. + ### Session Continuity * Check `docs/project-planning/` for existing files when user mentions continuing work. @@ -453,7 +463,7 @@ Before asking any question, check state file: ## PRD Structure -The required and conditional PRD sections, the requirement quality rules, and the identifier schema (`FR-###`, `NFR-###`, goal IDs) are owned by the requirements-author skill's PRD phases and the canonical [prd-full.md](../../skills/project-planning/requirements-author/templates/prd/prd-full.md) template. Author content against those sections rather than restating them here. +The required and conditional PRD sections, the requirement quality rules, and the identifier schema (`FR-###`, `NFR-###`, goal IDs) are owned by the `requirements-author` skill's PRD phases and the canonical `templates/prd/prd-full.md` template. Author content against those sections rather than restating them here. ## Output Modes @@ -490,6 +500,7 @@ When the PRD reaches Finalize and passes the Final Approval Checklist, end the f |-------------------------|---------------------------------------------------------------| | **PRD Document** | `docs/project-planning/.md` | | **State File** | `.copilot-tracking/prd-sessions/.state.json` | +| **Backlog Handoff** | Planning handoff path or `Not requested` | | **Lifecycle Status** | Draft, In Review, or Approved | | **Goals** | Count of goals defined | | **Functional Reqs** | Count of FR items | From 5f20a254252c8a6cc0ef19e55b95fcdd62023643 Mon Sep 17 00:00:00 2001 From: jkim323 Date: Sun, 21 Jun 2026 15:46:05 -0700 Subject: [PATCH 4/9] changes to naming of folders and where artifacts live --- .../agents/design-thinking/dt-coach.agent.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/.github/agents/design-thinking/dt-coach.agent.md b/.github/agents/design-thinking/dt-coach.agent.md index 8588bbd94..9948c4408 100644 --- a/.github/agents/design-thinking/dt-coach.agent.md +++ b/.github/agents/design-thinking/dt-coach.agent.md @@ -111,7 +111,7 @@ This section is an overview. The Required Phases section is the authoritative op When a user starts a new DT coaching project: -1. Create the project directory at `.copilot-tracking/dt/{project-slug}/`. +1. Create the state directory at `.copilot-tracking/design-thinking-sessions/{project-slug}/` and the artifacts directory at `docs/design-thinking/{project-slug}/`. 2. Initialize `coaching-state.md` following the coaching state protocol. 3. Capture the initial request verbatim in the state file. 4. Begin with Method 1 (Scope Conversations) to assess whether the request is frozen or fluid. @@ -120,7 +120,7 @@ When a user starts a new DT coaching project: When resuming an existing project: -1. Read `.copilot-tracking/dt/{project-slug}/coaching-state.md` to restore context. +1. Read `.copilot-tracking/design-thinking/{project-slug}/coaching-state.md` to restore context. 2. Review the most recent session log and transition log entries. 3. Announce the current state: active method, current phase, and summary of previous work. 4. Continue coaching from the restored state. @@ -229,8 +229,8 @@ Do not rely on memory. Actively refresh context so guidance is accurate and curr When the coaching process produces artifacts (stakeholder maps, interview notes, synthesis themes, concept descriptions, feedback summaries): -1. Create artifacts in the project directory using descriptive kebab-case filenames prefixed with the method number. -2. Register each artifact in the coaching state file. +1. Create artifacts in `docs/design-thinking-sessions/{project-slug}/` using descriptive kebab-case filenames prefixed with the method number. +2. Register each artifact in the coaching state file (which remains in `.copilot-tracking/design-thinking/{project-slug}/coaching-state.md`). 3. Reference prior artifacts when they inform the current method's work. ## Patterns to Avoid @@ -250,9 +250,9 @@ The coaching conversation follows four phases. Announce phase transitions briefl Phase 1 follows these steps in order. Do not reorder or skip steps. -**Step 1: Greet and collect project slug.** Greet the user and ask for their project slug, a kebab-case identifier for the project directory (e.g., `factory-floor-maintenance`). Use this slug for all artifact paths under `.copilot-tracking/dt/{project-slug}/` throughout the session. Do not proceed to Step 2 until you have the slug. +**Step 1: Greet and collect project slug.** Greet the user and ask for their project slug, a kebab-case identifier for the project directory (e.g., `factory-floor-maintenance`). Use this slug for artifact paths under `docs/design-thinking/{project-slug}/` and state under `.copilot-tracking/design-thinking-sessions/{project-slug}/` throughout the session. Do not proceed to Step 2 until you have the slug. -**Step 2: Create or resume infrastructure (MANDATORY).** Check whether `.copilot-tracking/dt/{project-slug}/coaching-state.md` already exists. If it does, this is a **returning session**: follow the Resuming a Session protocol (read the state file, review recent session and transition logs, announce the current method, phase, and summary of previous work), then skip to Phase 2. If the state file does not exist, this is a **new project**: create the project directory and `coaching-state.md` following the coaching state protocol, then continue to Step 3. Do not display the disclaimer, ask questions, or continue coaching until the directory and state file exist. +**Step 2: Create or resume infrastructure (MANDATORY).** Check whether `.copilot-tracking/design-thinking/{project-slug}/coaching-state.md` already exists. If it does, this is a **returning session**: follow the Resuming a Session protocol (read the state file, review recent session and transition logs, announce the current method, phase, and summary of previous work), then skip to Phase 2. If the state file does not exist, this is a **new project**: create both directories (`.copilot-tracking/design-thinking-sessions/{project-slug}/` for state and `docs/design-thinking/{project-slug}/` for artifacts) and initialize `coaching-state.md` following the coaching state protocol, then continue to Step 3. Do not display the disclaimer, ask questions, or continue coaching until both directories and the state file exist. **Step 3: Display disclaimer and persist timestamp.** Display the Design Thinking Coaching CAUTION block from #file:../../instructions/shared/disclaimer-language.instructions.md verbatim. After displaying the disclaimer, set `current.disclaimerShownAt` to the current ISO 8601 timestamp in `coaching-state.md`. Display the disclaimer at the start of every new project and whenever `current.disclaimerShownAt` is `null` in `coaching-state.md`, before any questions or analysis. @@ -268,7 +268,7 @@ Phase 1 follows these steps in order. Do not reorder or skip steps. Complete Phase 1 when: -* The project directory `.copilot-tracking/dt/{project-slug}/` and `coaching-state.md` exist and contain valid initial state. +* The state file `.copilot-tracking/design-thinking/{project-slug}/coaching-state.md` exists with valid initial state and the artifacts directory `docs/design-thinking/{project-slug}/` exists. * The current method focus is clear. * The session objectives are captured in your own words and the user agrees. * You have refreshed context from the appropriate skill references. @@ -277,7 +277,7 @@ When Phase 1 is complete, explicitly state that you are moving into Phase 2: Act ### Phase 2: Active Coaching -* If `.copilot-tracking/dt/{project-slug}/coaching-state.md` does not exist, create the directory and state file immediately before continuing. +* If `.copilot-tracking/design-thinking-sessions/{project-slug}/coaching-state.md` does not exist, create both directories (`.copilot-tracking/design-thinking-sessions/{project-slug}/` and `docs/design-thinking/{project-slug}/`) and the state file immediately before continuing. * Lead a structured, conversational coaching flow aligned with the current method. * Ask targeted, open-ended questions rather than giving long lectures. * Co-create and refine artifacts (maps, notes, canvases, concepts, feedback summaries) with the user. @@ -349,4 +349,4 @@ After closing, do not introduce new methods or major topics. If the user re-enga ## Required Protocol -* All DT coaching artifacts are scoped to `.copilot-tracking/dt/{project-slug}/`. Never write DT artifacts directly under `.copilot-tracking/dt/` without a project-slug directory. +* The coaching state file lives in `.copilot-tracking/design-thinking-sessions/{project-slug}/coaching-state.md`. All other DT coaching artifacts are scoped to `docs/design-thinking/{project-slug}/`. Never write DT artifacts directly under `docs/design-thinking/` without a project-slug directory. From 4e4b2494758a553672d971b23ee56ba8b4807c22 Mon Sep 17 00:00:00 2001 From: jkim323 Date: Sun, 21 Jun 2026 16:01:26 -0700 Subject: [PATCH 5/9] fix path --- .github/agents/design-thinking/dt-coach.agent.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/.github/agents/design-thinking/dt-coach.agent.md b/.github/agents/design-thinking/dt-coach.agent.md index 9948c4408..290144771 100644 --- a/.github/agents/design-thinking/dt-coach.agent.md +++ b/.github/agents/design-thinking/dt-coach.agent.md @@ -120,7 +120,7 @@ When a user starts a new DT coaching project: When resuming an existing project: -1. Read `.copilot-tracking/design-thinking/{project-slug}/coaching-state.md` to restore context. +1. Read `.copilot-tracking/design-thinking-sessions/{project-slug}/coaching-state.md` to restore context. 2. Review the most recent session log and transition log entries. 3. Announce the current state: active method, current phase, and summary of previous work. 4. Continue coaching from the restored state. @@ -229,8 +229,8 @@ Do not rely on memory. Actively refresh context so guidance is accurate and curr When the coaching process produces artifacts (stakeholder maps, interview notes, synthesis themes, concept descriptions, feedback summaries): -1. Create artifacts in `docs/design-thinking-sessions/{project-slug}/` using descriptive kebab-case filenames prefixed with the method number. -2. Register each artifact in the coaching state file (which remains in `.copilot-tracking/design-thinking/{project-slug}/coaching-state.md`). +1. Create artifacts in `docs/design-thinking/{project-slug}/` using descriptive kebab-case filenames prefixed with the method number. +2. Register each artifact in the coaching state file (which remains in `.copilot-tracking/design-thinking-sessions/{project-slug}/coaching-state.md`). 3. Reference prior artifacts when they inform the current method's work. ## Patterns to Avoid @@ -252,7 +252,7 @@ Phase 1 follows these steps in order. Do not reorder or skip steps. **Step 1: Greet and collect project slug.** Greet the user and ask for their project slug, a kebab-case identifier for the project directory (e.g., `factory-floor-maintenance`). Use this slug for artifact paths under `docs/design-thinking/{project-slug}/` and state under `.copilot-tracking/design-thinking-sessions/{project-slug}/` throughout the session. Do not proceed to Step 2 until you have the slug. -**Step 2: Create or resume infrastructure (MANDATORY).** Check whether `.copilot-tracking/design-thinking/{project-slug}/coaching-state.md` already exists. If it does, this is a **returning session**: follow the Resuming a Session protocol (read the state file, review recent session and transition logs, announce the current method, phase, and summary of previous work), then skip to Phase 2. If the state file does not exist, this is a **new project**: create both directories (`.copilot-tracking/design-thinking-sessions/{project-slug}/` for state and `docs/design-thinking/{project-slug}/` for artifacts) and initialize `coaching-state.md` following the coaching state protocol, then continue to Step 3. Do not display the disclaimer, ask questions, or continue coaching until both directories and the state file exist. +**Step 2: Create or resume infrastructure (MANDATORY).** Check whether `.copilot-tracking/design-thinking-sessions/{project-slug}/coaching-state.md` already exists. If it does, this is a **returning session**: follow the Resuming a Session protocol (read the state file, review recent session and transition logs, announce the current method, phase, and summary of previous work), then skip to Phase 2. If the state file does not exist, this is a **new project**: create both directories (`.copilot-tracking/design-thinking-sessions/{project-slug}/` for state and `docs/design-thinking/{project-slug}/` for artifacts) and initialize `coaching-state.md` following the coaching state protocol, then continue to Step 3. Do not display the disclaimer, ask questions, or continue coaching until both directories and the state file exist. **Step 3: Display disclaimer and persist timestamp.** Display the Design Thinking Coaching CAUTION block from #file:../../instructions/shared/disclaimer-language.instructions.md verbatim. After displaying the disclaimer, set `current.disclaimerShownAt` to the current ISO 8601 timestamp in `coaching-state.md`. Display the disclaimer at the start of every new project and whenever `current.disclaimerShownAt` is `null` in `coaching-state.md`, before any questions or analysis. @@ -268,7 +268,7 @@ Phase 1 follows these steps in order. Do not reorder or skip steps. Complete Phase 1 when: -* The state file `.copilot-tracking/design-thinking/{project-slug}/coaching-state.md` exists with valid initial state and the artifacts directory `docs/design-thinking/{project-slug}/` exists. +* The state file `.copilot-tracking/design-thinking-sessions/{project-slug}/coaching-state.md` exists with valid initial state and the artifacts directory `docs/design-thinking/{project-slug}/` exists. * The current method focus is clear. * The session objectives are captured in your own words and the user agrees. * You have refreshed context from the appropriate skill references. From 2060e164a3b0d0d7db18e1969ec02f662da55089 Mon Sep 17 00:00:00 2001 From: jkim323 Date: Sun, 21 Jun 2026 21:55:38 -0700 Subject: [PATCH 6/9] fix powershell-yaml casing --- .github/workflows/model-validation.yml | 6 +++--- scripts/linting/Test-ModelReferences.ps1 | 2 +- scripts/linting/Update-ModelCatalog.ps1 | 2 +- 3 files changed, 5 insertions(+), 5 deletions(-) diff --git a/.github/workflows/model-validation.yml b/.github/workflows/model-validation.yml index 9331e455e..371116e7f 100644 --- a/.github/workflows/model-validation.yml +++ b/.github/workflows/model-validation.yml @@ -31,11 +31,11 @@ jobs: with: persist-credentials: false - - name: Install PowerShell-Yaml + - name: Install powershell-yaml shell: pwsh run: | - if (-not (Get-Module -ListAvailable -Name PowerShell-Yaml | Where-Object { $_.Version -eq '0.4.7' })) { - Install-Module -Name PowerShell-Yaml -RequiredVersion 0.4.7 -Force -Scope CurrentUser + if (-not (Get-Module -ListAvailable -Name powershell-yaml | Where-Object { $_.Version -eq '0.4.7' })) { + Install-Module -Name powershell-yaml -RequiredVersion 0.4.7 -Force -Scope CurrentUser } - name: Refresh model catalog from GitHub docs diff --git a/scripts/linting/Test-ModelReferences.ps1 b/scripts/linting/Test-ModelReferences.ps1 index 3133345f0..192628b48 100644 --- a/scripts/linting/Test-ModelReferences.ps1 +++ b/scripts/linting/Test-ModelReferences.ps1 @@ -40,7 +40,7 @@ $ErrorActionPreference = 'Stop' $gitRoot = git rev-parse --show-toplevel 2>$null $RepoRoot = if ($gitRoot) { $gitRoot } else { (Join-Path $PSScriptRoot '..' '..' | Resolve-Path).Path } -Import-Module PowerShell-Yaml -ErrorAction Stop +Import-Module powershell-yaml -ErrorAction Stop #region Functions diff --git a/scripts/linting/Update-ModelCatalog.ps1 b/scripts/linting/Update-ModelCatalog.ps1 index d5ac46318..fdd3663c9 100644 --- a/scripts/linting/Update-ModelCatalog.ps1 +++ b/scripts/linting/Update-ModelCatalog.ps1 @@ -54,7 +54,7 @@ param( $ErrorActionPreference = 'Stop' -Import-Module PowerShell-Yaml -ErrorAction Stop +Import-Module powershell-yaml -ErrorAction Stop #region Functions From 48e69f33c19ce4823a37c7af0a8c4e4bf8d405d0 Mon Sep 17 00:00:00 2001 From: jkim323 Date: Thu, 25 Jun 2026 23:38:24 -0700 Subject: [PATCH 7/9] update metadata contract mismatch in the agent frontmatter --- .github/agents/design-thinking/dt-coach.agent.md | 2 +- .github/agents/project-planning/brd-builder.agent.md | 2 +- .github/agents/project-planning/prd-builder.agent.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/.github/agents/design-thinking/dt-coach.agent.md b/.github/agents/design-thinking/dt-coach.agent.md index 290144771..d3cbe551a 100644 --- a/.github/agents/design-thinking/dt-coach.agent.md +++ b/.github/agents/design-thinking/dt-coach.agent.md @@ -1,6 +1,6 @@ --- name: DT Coach -description: 'Design Thinking coach guiding teams through the 9-method HVE framework with Think/Speak/Empower philosophy' +description: 'Design Thinking coach guiding teams through the 9-method HVE framework with Think/Speak/Empower - Brought to you by microsoft/hve-core' tools: [vscode/askQuestions, execute/getTerminalOutput, execute/awaitTerminal, execute/killTerminal, execute/runInTerminal, read, agent, edit, search, web] handoffs: diff --git a/.github/agents/project-planning/brd-builder.agent.md b/.github/agents/project-planning/brd-builder.agent.md index b0e4b180d..2c5eb128a 100644 --- a/.github/agents/project-planning/brd-builder.agent.md +++ b/.github/agents/project-planning/brd-builder.agent.md @@ -1,6 +1,6 @@ --- name: BRD Builder -description: "Business Requirements Document builder with guided Q&A and reference integration" +description: "Business Requirements Document builder with guided Q&A and references - Brought to you by microsoft/hve-core" agents: - BRD Quality Reviewer - Researcher Subagent diff --git a/.github/agents/project-planning/prd-builder.agent.md b/.github/agents/project-planning/prd-builder.agent.md index f3938ebc8..3494ff840 100644 --- a/.github/agents/project-planning/prd-builder.agent.md +++ b/.github/agents/project-planning/prd-builder.agent.md @@ -1,6 +1,6 @@ --- name: PRD Builder -description: "Product Requirements Document builder with guided Q&A and reference integration" +description: "Product Requirements Document builder with guided Q&A and references - Brought to you by microsoft/hve-core" agents: - PRD Quality Reviewer - Researcher Subagent From f01a97f5f87e5951654e5db43a55e0cc55678136 Mon Sep 17 00:00:00 2001 From: jkim323 Date: Fri, 26 Jun 2026 07:52:02 -0700 Subject: [PATCH 8/9] align agent-behavior fixtures with new builder output paths --- evals/agent-behavior/eval.yaml | 12 +++++------ .../expectations/brd-builder.expectations.yml | 14 ++++++------- .../expectations/dt-coach.expectations.yml | 20 +++++++++---------- .../expectations/prd-builder.expectations.yml | 4 +++- evals/agent-behavior/stimuli/brd-builder.yml | 4 ++-- evals/agent-behavior/stimuli/dt-coach.yml | 4 ++-- evals/agent-behavior/stimuli/prd-builder.yml | 4 ++-- .../surface-signatures/dt-coach.yml | 6 +++--- 8 files changed, 35 insertions(+), 33 deletions(-) diff --git a/evals/agent-behavior/eval.yaml b/evals/agent-behavior/eval.yaml index 94dc910ed..5a1b96d5d 100644 --- a/evals/agent-behavior/eval.yaml +++ b/evals/agent-behavior/eval.yaml @@ -269,7 +269,7 @@ stimuli: negate: true - name: brd-builder-class-recipe prompt: | - Draft a Business Requirements Document for a self-service password reset feature. Cover business goals, scope, and success metrics. Write the BRD under `.copilot-tracking/brd-sessions/` and report the path. + Draft a Business Requirements Document for a self-service password reset feature. Cover business goals, scope, and success metrics. Write the BRD under `docs/project-planning/` with session state under `.copilot-tracking/brd-sessions/`, and report the paths. tags: category: agent-behavior agent: brd-builder @@ -277,7 +277,7 @@ stimuli: - type: output-matches name: tracking-file-write config: - pattern: (?i)\.copilot-tracking[-/\\](brd-sessions|research) + pattern: (?i)(docs[-/\\]project-planning|\.copilot-tracking[-/\\](brd-sessions|research)) - type: output-matches name: topic-coverage config: @@ -514,7 +514,7 @@ stimuli: negate: true - name: dt-coach-class-recipe prompt: | - Coach me through scoping a Design Thinking project on "improving cafeteria experience for night-shift workers." Lay out the next 2-3 methods as phases. Write the coaching state under `.copilot-tracking/dt/` and tell me the path you wrote it to. + Coach me through scoping a Design Thinking project (use the project slug `cafeteria-night-shift`) on "improving cafeteria experience for night-shift workers." Lay out the next 2-3 methods as phases. Write the coaching state under `.copilot-tracking/design-thinking-sessions/` and tell me the path you wrote it to. tags: category: agent-behavior agent: dt-coach @@ -526,7 +526,7 @@ stimuli: - type: output-matches name: tracking-file-write config: - pattern: (?i)\.copilot-tracking[-/\\]dt + pattern: (?i)\.copilot-tracking[-/\\]design-thinking-sessions - type: output-matches name: no-source-edit config: @@ -1153,7 +1153,7 @@ stimuli: negate: true - name: prd-builder-class-recipe prompt: | - Draft a Product Requirements Document for a notification preferences page (in-app, email, SMS toggles). Include user stories and success criteria. Write the PRD under `.copilot-tracking/prd-sessions/` and report the path. + Draft a Product Requirements Document for a notification preferences page (in-app, email, SMS toggles). Include user stories and success criteria. Write the PRD under `docs/project-planning/` with session state under `.copilot-tracking/prd-sessions/`, and report the paths. tags: category: agent-behavior agent: prd-builder @@ -1161,7 +1161,7 @@ stimuli: - type: output-matches name: tracking-file-write config: - pattern: (?i)\.copilot-tracking[-/\\](prd-sessions|research) + pattern: (?i)(docs[-/\\]project-planning|\.copilot-tracking[-/\\](prd-sessions|research)) - type: output-matches name: topic-coverage config: diff --git a/evals/agent-behavior/expectations/brd-builder.expectations.yml b/evals/agent-behavior/expectations/brd-builder.expectations.yml index e3379c0d8..4c4dcf5b8 100644 --- a/evals/agent-behavior/expectations/brd-builder.expectations.yml +++ b/evals/agent-behavior/expectations/brd-builder.expectations.yml @@ -4,13 +4,13 @@ # by the next pass that rewrites stimuli + graders end-to-end; do not treat it # as a Vally grader file directly. # -# Note: the agent file places the BRD itself at `docs/brds/-brd.md` and -# the session state at `.copilot-tracking/brd-sessions/.state.json`. The -# current `brd-builder-class-recipe` stimulus' `tracking-file-write` grader -# expects the BRD path to start with `.copilot-tracking/(brd-sessions|research)/`, -# which does not match the agent's own contract. Expectations below ground in -# the agent file; the next pass should either align the grader to `docs/brds/` -# or expect both paths. +# Note: the agent file places the BRD itself at +# `docs/project-planning/-brd.md` and the session state at +# `.copilot-tracking/brd-sessions/.state.json`. The +# `brd-builder-class-recipe` stimulus' `tracking-file-write` grader accepts +# either the BRD output under `docs/project-planning/` or the state path under +# `.copilot-tracking/(brd-sessions|research)/`, matching the agent contract. +# Expectations below ground in the agent file. slug: brd-builder class: research-writer agent_file: .github/agents/project-planning/brd-builder.agent.md diff --git a/evals/agent-behavior/expectations/dt-coach.expectations.yml b/evals/agent-behavior/expectations/dt-coach.expectations.yml index f00dd1107..a7b8ce719 100644 --- a/evals/agent-behavior/expectations/dt-coach.expectations.yml +++ b/evals/agent-behavior/expectations/dt-coach.expectations.yml @@ -26,33 +26,33 @@ expectations: contract_ref: "agent §Required Phases (announces Phase 1–4 transitions) + stimulus grader `phase-marker-present`" - expectation_id: coaching-state-path - summary: New DT projects report a coaching-state file under the dated project slug directory. - signal: Output names a path matching `.copilot-tracking/dt//coaching-state.md`. + summary: New DT projects report a coaching-state file under the project slug directory. + signal: Output names a path matching `.copilot-tracking/design-thinking-sessions//coaching-state.md`. pass_criteria: | When the request initiates a new DT project, the response cites a - workspace-relative path under `.copilot-tracking/dt//` and + workspace-relative path under `.copilot-tracking/design-thinking-sessions//` and the named file is `coaching-state.md` (per §Session Management › Starting a New Project). failure_modes: - - Reports a slug-less file like `.copilot-tracking/dt/cafeteria-night-shift.md` directly under the `dt/` root (current 2026-05-28 output). + - Reports a slug-less file like `.copilot-tracking/design-thinking-sessions/cafeteria-night-shift.md` directly under the `design-thinking-sessions/` root. - Drops the `coaching-state.md` filename in favor of a generic `plan.md` or `scope.md`. - - Writes outside `.copilot-tracking/dt/` (e.g. session-state temp dirs). + - Writes outside `.copilot-tracking/design-thinking-sessions/` (e.g. session-state temp dirs). priority: high contract_ref: "agent §Session Management › Starting a New Project (`coaching-state.md`)" - expectation_id: project-slug-kebab-case summary: The project slug embedded in the path is kebab-case and matches the topic. - signal: Path segment after `.copilot-tracking/dt/` is a single kebab-case identifier. + signal: Path segment after `.copilot-tracking/design-thinking-sessions/` is a single kebab-case identifier. pass_criteria: | - The directory segment immediately under `.copilot-tracking/dt/` matches + The directory segment immediately under `.copilot-tracking/design-thinking-sessions/` matches `[a-z0-9]+(-[a-z0-9]+)*` and is derived from the user's topic (e.g. `cafeteria-night-shift`, `factory-floor-maintenance`). failure_modes: - Slug uses spaces, camelCase, or snake_case. - Slug is a generic placeholder like `project` or `dt-project`. - - No slug subdirectory (file written directly under `.copilot-tracking/dt/`). + - No slug subdirectory (file written directly under `.copilot-tracking/design-thinking-sessions/`). priority: medium - contract_ref: "agent §Session Management (slug under `.copilot-tracking/dt/{project-slug}/`)" + contract_ref: "agent §Session Management (slug under `.copilot-tracking/design-thinking-sessions/{project-slug}/`)" - expectation_id: nine-method-vocabulary summary: Method references use the agent's declared 9-method vocabulary. @@ -140,7 +140,7 @@ expectations: - Coach claims to modify source files as part of a scoping turn. - Coach edits `package.json` to add DT-related scripts. priority: medium - contract_ref: "agent scope (coaching writes are confined to `.copilot-tracking/dt/` per §Session Management)" + contract_ref: "agent scope (coaching writes are confined to `.copilot-tracking/design-thinking-sessions/` per §Session Management)" - expectation_id: stimulus-topic-fidelity summary: Output substantively addresses the stimulus's DT scoping topic. diff --git a/evals/agent-behavior/expectations/prd-builder.expectations.yml b/evals/agent-behavior/expectations/prd-builder.expectations.yml index c17bf7c34..99b51d7d4 100644 --- a/evals/agent-behavior/expectations/prd-builder.expectations.yml +++ b/evals/agent-behavior/expectations/prd-builder.expectations.yml @@ -17,7 +17,9 @@ expectations: pass_criteria: | The response reports a session-state path beginning with `.copilot-tracking/prd-sessions/` whose slug matches the PRD topic. This - satisfies the `tracking-file-write` grader (`.copilot-tracking/(prd-sessions|research)`). + satisfies the `tracking-file-write` grader, which accepts either the PRD + output under `docs/project-planning/` or the state path under + `.copilot-tracking/(prd-sessions|research)`. failure_modes: - State path omitted or only the PRD path reported (current 2026-05-28 output fails state-file path reporting). diff --git a/evals/agent-behavior/stimuli/brd-builder.yml b/evals/agent-behavior/stimuli/brd-builder.yml index 814609176..c716442f2 100644 --- a/evals/agent-behavior/stimuli/brd-builder.yml +++ b/evals/agent-behavior/stimuli/brd-builder.yml @@ -1,14 +1,14 @@ stimuli: - name: brd-builder-class-recipe prompt: | - Draft a Business Requirements Document for a self-service password reset feature. Cover business goals, scope, and success metrics. Write the BRD under `.copilot-tracking/brd-sessions/` and report the path. + Draft a Business Requirements Document for a self-service password reset feature. Cover business goals, scope, and success metrics. Write the BRD under `docs/project-planning/` with session state under `.copilot-tracking/brd-sessions/`, and report the paths. tags: category: agent-behavior graders: - type: output-matches name: tracking-file-write config: - pattern: '(?i)\.copilot-tracking[-/\\](brd-sessions|research)' + pattern: '(?i)(docs[-/\\]project-planning|\.copilot-tracking[-/\\](brd-sessions|research))' - type: output-matches name: topic-coverage config: diff --git a/evals/agent-behavior/stimuli/dt-coach.yml b/evals/agent-behavior/stimuli/dt-coach.yml index 2c853e83e..195e2c05e 100644 --- a/evals/agent-behavior/stimuli/dt-coach.yml +++ b/evals/agent-behavior/stimuli/dt-coach.yml @@ -1,7 +1,7 @@ stimuli: - name: dt-coach-class-recipe prompt: | - Coach me through scoping a Design Thinking project on "improving cafeteria experience for night-shift workers." Lay out the next 2-3 methods as phases. Write the coaching state under `.copilot-tracking/dt/` and tell me the path you wrote it to. + Coach me through scoping a Design Thinking project (use the project slug `cafeteria-night-shift`) on "improving cafeteria experience for night-shift workers." Lay out the next 2-3 methods as phases. Write the coaching state under `.copilot-tracking/design-thinking-sessions/` and tell me the path you wrote it to. tags: category: agent-behavior graders: @@ -12,7 +12,7 @@ stimuli: - type: output-matches name: tracking-file-write config: - pattern: '(?i)\.copilot-tracking[-/\\]dt' + pattern: '(?i)\.copilot-tracking[-/\\]design-thinking-sessions' - type: output-matches name: no-source-edit config: diff --git a/evals/agent-behavior/stimuli/prd-builder.yml b/evals/agent-behavior/stimuli/prd-builder.yml index 4591fea4c..155d9217c 100644 --- a/evals/agent-behavior/stimuli/prd-builder.yml +++ b/evals/agent-behavior/stimuli/prd-builder.yml @@ -1,14 +1,14 @@ stimuli: - name: prd-builder-class-recipe prompt: | - Draft a Product Requirements Document for a notification preferences page (in-app, email, SMS toggles). Include user stories and success criteria. Write the PRD under `.copilot-tracking/prd-sessions/` and report the path. + Draft a Product Requirements Document for a notification preferences page (in-app, email, SMS toggles). Include user stories and success criteria. Write the PRD under `docs/project-planning/` with session state under `.copilot-tracking/prd-sessions/`, and report the paths. tags: category: agent-behavior graders: - type: output-matches name: tracking-file-write config: - pattern: '(?i)\.copilot-tracking[-/\\](prd-sessions|research)' + pattern: '(?i)(docs[-/\\]project-planning|\.copilot-tracking[-/\\](prd-sessions|research))' - type: output-matches name: topic-coverage config: diff --git a/evals/baseline-equivalence/surface-signatures/dt-coach.yml b/evals/baseline-equivalence/surface-signatures/dt-coach.yml index a8dc9d0c3..f4698f2c2 100644 --- a/evals/baseline-equivalence/surface-signatures/dt-coach.yml +++ b/evals/baseline-equivalence/surface-signatures/dt-coach.yml @@ -1,12 +1,12 @@ # Generated by scripts/evals/New-AgentSurfaceSignatures.ps1 — re-run with -Force to regenerate. # Agent: dt-coach required: - - name: dt-scope-language + - name: design-thinking-sessions-scope-language type: output-matches config: - pattern: '(?i)\.copilot-tracking/dt' + pattern: '(?i)\.copilot-tracking/design-thinking-sessions' disallowed: - - name: writes-outside-dt-dir + - name: writes-outside-design-thinking-sessions-dir type: output-matches config: pattern: '(?i)(C:\\|/etc/|/usr/|~/Documents)' From 121c7f0d4b69ab9b1e1960b9dd57c997cdd77016 Mon Sep 17 00:00:00 2001 From: jkim323 Date: Fri, 26 Jun 2026 08:06:28 -0700 Subject: [PATCH 9/9] regenerate plugin and extension outputs for prd/brd builder updates" --- collections/design-thinking.collection.md | 8 ++++---- collections/hve-core-all.collection.md | 6 +++--- collections/project-planning.collection.md | 4 ++-- plugins/design-thinking/README.md | 8 ++++---- plugins/hve-core-all/README.md | 6 +++--- plugins/project-planning/README.md | 4 ++-- 6 files changed, 18 insertions(+), 18 deletions(-) diff --git a/collections/design-thinking.collection.md b/collections/design-thinking.collection.md index 51ad7a5ce..6aa3b5b3c 100644 --- a/collections/design-thinking.collection.md +++ b/collections/design-thinking.collection.md @@ -10,10 +10,10 @@ Coaching identity, quality constraints, and methodology skills for AI-enhanced d ### Chat Agents -| Name | Description | -|-----------------------|------------------------------------------------------------------------------------------------------------| -| **dt-coach** | Design Thinking coach guiding teams through the 9-method HVE framework with Think/Speak/Empower philosophy | -| **dt-learning-tutor** | Design Thinking learning tutor providing structured curriculum, comprehension checks, and adaptive pacing | +| Name | Description | +|-----------------------|-----------------------------------------------------------------------------------------------------------| +| **dt-coach** | Design Thinking coach guiding teams through the 9-method HVE framework with Think/Speak/Empower | +| **dt-learning-tutor** | Design Thinking learning tutor providing structured curriculum, comprehension checks, and adaptive pacing | ### Prompts diff --git a/collections/hve-core-all.collection.md b/collections/hve-core-all.collection.md index 53613f55e..6271cc4ac 100644 --- a/collections/hve-core-all.collection.md +++ b/collections/hve-core-all.collection.md @@ -25,7 +25,7 @@ Use this edition when you want access to everything without choosing a focused c | **ado-prd-to-wit** | Product Manager expert for analyzing PRDs and planning Azure DevOps work item hierarchies | | **adr-creation** | ADR Creator: phase-gated creator producing standards-aligned Architecture Decision Records (Frame, Decide, Govern), with state recovery, Researcher Subagent delegation, and dual-format backlog handoff | | **agile-coach** | Creates and refines goal-oriented user stories with clear acceptance criteria for any tracking tool | -| **brd-builder** | Business Requirements Document builder with guided Q&A and reference integration | +| **brd-builder** | Business Requirements Document builder with guided Q&A and references | | **brd-quality-reviewer** | Read-only BRD quality reviewer that emits both BRD_STANDARD_FINDINGS_V1 and BRD_QUALITY_REPORT_V1 payloads | | **code-review-accessibility** | Pre-PR branch diff reviewer for accessibility conformance across web, mobile, and document UI surfaces using WCAG, ARIA, COGA, Section 508, and EN 301 549 skills | | **code-review-full** | Orchestrator that runs functional, standards, and accessibility code reviews via subagents and produces a merged report | @@ -33,7 +33,7 @@ Use this edition when you want access to everything without choosing a focused c | **code-review-standards** | Skills-based code reviewer applying project-defined coding standards to local changes and PRs | | **codebase-profiler** | Scans the repository to build a technology profile and select applicable security skills | | **documentation** | Orchestrates documentation audit, drift, authoring, and validation work through the documentation skill | -| **dt-coach** | Design Thinking coach guiding teams through the 9-method HVE framework with Think/Speak/Empower philosophy | +| **dt-coach** | Design Thinking coach guiding teams through the 9-method HVE framework with Think/Speak/Empower | | **dt-learning-tutor** | Design Thinking learning tutor providing structured curriculum, comprehension checks, and adaptive pacing | | **eval-dataset-creator** | Creates evaluation datasets and documentation for AI agent testing using interview-driven data curation | | **experiment-designer** | Coach for designing a Minimum Viable Experiment (MVE) with hypothesis formation, vetting, and experiment planning | @@ -54,7 +54,7 @@ Use this edition when you want access to everything without choosing a focused c | **pptx-subagent** | Executes PowerPoint skill operations including content extraction, YAML creation, deck building, and visual validation | | **pr-review** | Pull Request review assistant for code quality, security, and convention compliance | | **pr-walkthrough** | Narrative-driven PR orientation surfacing design forks, implicit bets, and architectural shape for reviewer judgment. | -| **prd-builder** | Product Requirements Document builder with guided Q&A and reference integration | +| **prd-builder** | Product Requirements Document builder with guided Q&A and references | | **prd-quality-reviewer** | Read-only PRD quality reviewer that emits both PRD_STANDARD_FINDINGS_V1 and PRD_QUALITY_REPORT_V1 payloads | | **product-manager-advisor** | Product management advisor for requirements discovery, validation, and issue creation | | **prompt-builder** | Prompt engineering assistant for creating and validating prompts, agents, and instructions | diff --git a/collections/project-planning.collection.md b/collections/project-planning.collection.md index 5e87194e3..6854d6c0b 100644 --- a/collections/project-planning.collection.md +++ b/collections/project-planning.collection.md @@ -13,14 +13,14 @@ Create architecture decision records (MADR v4 + Y-Statement) with phase-gated co | **accessibility-planner** | Phase-based accessibility planner that guides users through structured planning for WCAG 2.2, ARIA APG, Cognitive Accessibility, Section 508, and EN 301 549, producing framework selections, control mappings, evidence-register entries, plan-risk classifications, and dual-format backlog handoff. Brought to you by microsoft/hve-core. | | **adr-creation** | ADR Creator: phase-gated creator producing standards-aligned Architecture Decision Records (Frame, Decide, Govern), with state recovery, Researcher Subagent delegation, and dual-format backlog handoff | | **agile-coach** | Creates and refines goal-oriented user stories with clear acceptance criteria for any tracking tool | -| **brd-builder** | Business Requirements Document builder with guided Q&A and reference integration | +| **brd-builder** | Business Requirements Document builder with guided Q&A and references | | **brd-quality-reviewer** | Read-only BRD quality reviewer that emits both BRD_STANDARD_FINDINGS_V1 and BRD_QUALITY_REPORT_V1 payloads | | **implementation-validator** | Validates implementation quality against architectural requirements, design principles, and code standards with severity-graded findings | | **meeting-analyst** | Meeting transcript analyzer that extracts product requirements for PRD creation via work-iq-mcp | | **network-isa95-planner** | ISA-95-aligned network planning for secure edge Kubernetes to Azure connectivity and remediation roadmaps | | **phase-implementor** | Executes a single implementation phase from a plan with full codebase access and change tracking | | **plan-validator** | Validates implementation plans against research documents with severity-graded findings | -| **prd-builder** | Product Requirements Document builder with guided Q&A and reference integration | +| **prd-builder** | Product Requirements Document builder with guided Q&A and references | | **prd-quality-reviewer** | Read-only PRD quality reviewer that emits both PRD_STANDARD_FINDINGS_V1 and PRD_QUALITY_REPORT_V1 payloads | | **product-manager-advisor** | Product management advisor for requirements discovery, validation, and issue creation | | **rai-planner** | Responsible AI assessment planner evaluating against NIST AI RMF 1.0, producing an RAI security model, impact assessment, control surface catalog, and backlog handoff | diff --git a/plugins/design-thinking/README.md b/plugins/design-thinking/README.md index 7ecea4fac..c4b425163 100644 --- a/plugins/design-thinking/README.md +++ b/plugins/design-thinking/README.md @@ -17,10 +17,10 @@ Coaching identity, quality constraints, and methodology skills for AI-enhanced d ### Chat Agents -| Name | Description | -|-----------------------|------------------------------------------------------------------------------------------------------------| -| **dt-coach** | Design Thinking coach guiding teams through the 9-method HVE framework with Think/Speak/Empower philosophy | -| **dt-learning-tutor** | Design Thinking learning tutor providing structured curriculum, comprehension checks, and adaptive pacing | +| Name | Description | +|-----------------------|-----------------------------------------------------------------------------------------------------------| +| **dt-coach** | Design Thinking coach guiding teams through the 9-method HVE framework with Think/Speak/Empower | +| **dt-learning-tutor** | Design Thinking learning tutor providing structured curriculum, comprehension checks, and adaptive pacing | ### Prompts diff --git a/plugins/hve-core-all/README.md b/plugins/hve-core-all/README.md index 18a1943ec..c102de176 100644 --- a/plugins/hve-core-all/README.md +++ b/plugins/hve-core-all/README.md @@ -30,7 +30,7 @@ Use this edition when you want access to everything without choosing a focused c | **ado-prd-to-wit** | Product Manager expert for analyzing PRDs and planning Azure DevOps work item hierarchies | | **adr-creation** | ADR Creator: phase-gated creator producing standards-aligned Architecture Decision Records (Frame, Decide, Govern), with state recovery, Researcher Subagent delegation, and dual-format backlog handoff | | **agile-coach** | Creates and refines goal-oriented user stories with clear acceptance criteria for any tracking tool | -| **brd-builder** | Business Requirements Document builder with guided Q&A and reference integration | +| **brd-builder** | Business Requirements Document builder with guided Q&A and references | | **brd-quality-reviewer** | Read-only BRD quality reviewer that emits both BRD_STANDARD_FINDINGS_V1 and BRD_QUALITY_REPORT_V1 payloads | | **code-review-accessibility** | Pre-PR branch diff reviewer for accessibility conformance across web, mobile, and document UI surfaces using WCAG, ARIA, COGA, Section 508, and EN 301 549 skills | | **code-review-full** | Orchestrator that runs functional, standards, and accessibility code reviews via subagents and produces a merged report | @@ -38,7 +38,7 @@ Use this edition when you want access to everything without choosing a focused c | **code-review-standards** | Skills-based code reviewer applying project-defined coding standards to local changes and PRs | | **codebase-profiler** | Scans the repository to build a technology profile and select applicable security skills | | **documentation** | Orchestrates documentation audit, drift, authoring, and validation work through the documentation skill | -| **dt-coach** | Design Thinking coach guiding teams through the 9-method HVE framework with Think/Speak/Empower philosophy | +| **dt-coach** | Design Thinking coach guiding teams through the 9-method HVE framework with Think/Speak/Empower | | **dt-learning-tutor** | Design Thinking learning tutor providing structured curriculum, comprehension checks, and adaptive pacing | | **eval-dataset-creator** | Creates evaluation datasets and documentation for AI agent testing using interview-driven data curation | | **experiment-designer** | Coach for designing a Minimum Viable Experiment (MVE) with hypothesis formation, vetting, and experiment planning | @@ -59,7 +59,7 @@ Use this edition when you want access to everything without choosing a focused c | **pptx-subagent** | Executes PowerPoint skill operations including content extraction, YAML creation, deck building, and visual validation | | **pr-review** | Pull Request review assistant for code quality, security, and convention compliance | | **pr-walkthrough** | Narrative-driven PR orientation surfacing design forks, implicit bets, and architectural shape for reviewer judgment. | -| **prd-builder** | Product Requirements Document builder with guided Q&A and reference integration | +| **prd-builder** | Product Requirements Document builder with guided Q&A and references | | **prd-quality-reviewer** | Read-only PRD quality reviewer that emits both PRD_STANDARD_FINDINGS_V1 and PRD_QUALITY_REPORT_V1 payloads | | **product-manager-advisor** | Product management advisor for requirements discovery, validation, and issue creation | | **prompt-builder** | Prompt engineering assistant for creating and validating prompts, agents, and instructions | diff --git a/plugins/project-planning/README.md b/plugins/project-planning/README.md index 5db8cfff5..63f65aace 100644 --- a/plugins/project-planning/README.md +++ b/plugins/project-planning/README.md @@ -18,14 +18,14 @@ Create architecture decision records (MADR v4 + Y-Statement) with phase-gated co | **accessibility-planner** | Phase-based accessibility planner that guides users through structured planning for WCAG 2.2, ARIA APG, Cognitive Accessibility, Section 508, and EN 301 549, producing framework selections, control mappings, evidence-register entries, plan-risk classifications, and dual-format backlog handoff. Brought to you by microsoft/hve-core. | | **adr-creation** | ADR Creator: phase-gated creator producing standards-aligned Architecture Decision Records (Frame, Decide, Govern), with state recovery, Researcher Subagent delegation, and dual-format backlog handoff | | **agile-coach** | Creates and refines goal-oriented user stories with clear acceptance criteria for any tracking tool | -| **brd-builder** | Business Requirements Document builder with guided Q&A and reference integration | +| **brd-builder** | Business Requirements Document builder with guided Q&A and references | | **brd-quality-reviewer** | Read-only BRD quality reviewer that emits both BRD_STANDARD_FINDINGS_V1 and BRD_QUALITY_REPORT_V1 payloads | | **implementation-validator** | Validates implementation quality against architectural requirements, design principles, and code standards with severity-graded findings | | **meeting-analyst** | Meeting transcript analyzer that extracts product requirements for PRD creation via work-iq-mcp | | **network-isa95-planner** | ISA-95-aligned network planning for secure edge Kubernetes to Azure connectivity and remediation roadmaps | | **phase-implementor** | Executes a single implementation phase from a plan with full codebase access and change tracking | | **plan-validator** | Validates implementation plans against research documents with severity-graded findings | -| **prd-builder** | Product Requirements Document builder with guided Q&A and reference integration | +| **prd-builder** | Product Requirements Document builder with guided Q&A and references | | **prd-quality-reviewer** | Read-only PRD quality reviewer that emits both PRD_STANDARD_FINDINGS_V1 and PRD_QUALITY_REPORT_V1 payloads | | **product-manager-advisor** | Product management advisor for requirements discovery, validation, and issue creation | | **rai-planner** | Responsible AI assessment planner evaluating against NIST AI RMF 1.0, producing an RAI security model, impact assessment, control surface catalog, and backlog handoff |