feat(agents): add agile-coach agent

[erikschlegel]

Pull Request

Description

Adds a socratic conversational agent that helps create or refine goal-oriented user stories.

What it does

1. Create mode: Turns rough ideas into polished user stories
2. Refine mode: Improves existing vague stories into concrete, outcome-focused items

Outputs copy-paste ready stories with action-oriented titles, concise descriptions, and testable acceptance criteria.

Related Issue(s)

Closes #561

Type of Change

Select all that apply:

Code & Documentation:

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

Infrastructure & Configuration:

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

AI Artifacts:

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

Other:

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

Sample Prompts (for AI Artifact Contributions)

Create Mode:

1. Starting from a vague idea:
   "I need a story for adding dark mode to our app"

2. Technical feature:
   "We need to migrate our database from Postgres to CockroachDB"

3. Bug-related improvement:
   "Users keep complaining that search is slow"

4. New capability:
   "I want to add Slack notifications when builds fail"

Refine Mode:

1. Vague existing story:

"Can you help me refine this story?
Title: Improve performance
Description: Make the app faster
AC: It should be fast"

2. Incomplete acceptance criteria:

"Refine this please:
Title: Add user export feature
Description: As a user, I want to export my data
AC: User can export data
Works correctly"

Output Artifacts:

Copy-paste ready user stories formatted for any tracking tool (GitHub Issues, Jira, ADO, etc.)

Each story includes:

Title – Action-oriented, verb-first
Description – 1-3 sentences in the clearest format for the context
Acceptance Criteria – 5-10 binary, testable checklist items
Definition of Done notes (optional) – Team standards like tests, docs, observability
Open questions/risks/dependencies (optional) – Assumptions made, things needing follow-up
The output is markdown-formatted so users can copy directly into their issue tracker without reformatting.

Success Indicators:

Testing

My team has used this agent for the last 3x sprints of an existing engagement to help engineers create more objective and clearer acceptance criteria

Checklist

Required Checks

• Documentation is updated (if applicable)
• Files follow existing naming conventions
• Changes are backwards compatible (if applicable)
• Tests added for new functionality (if applicable)

AI Artifact Contributions

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

Required Automated Checks

The following validation commands must pass before merging:

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

Security Considerations

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

Additional Notes

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 85.34%. Comparing base (d3bdd7a) to head (fb08971).

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #562      +/-   ##
==========================================
- Coverage   85.36%   85.34%   -0.03%     
==========================================
  Files          23       23              
  Lines        4475     4475              
==========================================
- Hits         3820     3819       -1     
- Misses        655      656       +1     

Flag	Coverage Δ
pester	85.34% <ø> (-0.03%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.
see 1 file with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[Copilot]

Pull request overview

Adds a new custom Copilot agent intended to coach users through creating or refining goal-oriented, outcome-driven user stories with testable acceptance criteria.

Changes:

• Introduces a new .agent.md file defining the “User Story Coach” conversational flow (create vs refine modes)
• Defines a copy-paste output template for title/description/acceptance criteria, plus optional DoD notes and open questions

[Copilot]

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated 4 comments.

[Copilot]

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated 7 comments.

[Copilot]

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated 1 comment.

[Copilot]

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated 1 comment.

[Copilot]

Phase completion criteria use informal language ("when the story feels complete" and "when the refined version feels solid") which introduces subjective interpretation. Consider using more concrete completion criteria, such as "when all acceptance criteria are defined and measurable" or "when gaps are filled and outcomes are measurable". This aligns better with the agent's goal of creating verifiable, testable acceptance criteria and provides clearer guidance on when to progress.

[WilliamBerryiii]

Hey @erikschlegel, thanks for contributing the agile-coach agent! The Socratic coaching approach for user story creation/refinement is a great addition to the toolkit.

A few items from our contributing guidelines still need attention before we can merge:

AI Artifact Review
The prompt-builder review items in the PR checklist are still unchecked. Please run /prompt-analyze against the agent file, address any feedback, and check off those items. Details are in our AI Artifacts Contributing Guide.

Missing Agent Sections
Per the custom agents guide, agent files should include:

• A Success Criteria section defining what a successful interaction looks like
• An attribution footer (e.g., 🤖 Brought to you by microsoft/hve-core)

Plugin Files Are Generated
Files under plugins/ are generated outputs and shouldn't be edited directly. Your collection manifest update to collections/hve-core-all.collection.yml is correct, but please revert the manual changes to plugins/hve-core-all/README.md and plugins/hve-core-all/agents/agile-coach.md, then run npm run plugin:generate to regenerate them.

Automated Checks
Once the above is addressed, run npm run lint:all and mark those items complete in the PR description.

There's also one unresolved Copilot review comment about phase completion criteria wording worth addressing.

Update the PR description checkboxes when these are done and we'll get this reviewed. Thanks again for putting this together!