Skip to content

feat(agents): Create dt-coach.agent.md #579

@WilliamBerryiii

Description

@WilliamBerryiii

Overview

Create dt-coach.agent.md — the single conversational DT coaching agent implementing Approach C (Single Coach + Knowledge Modules). This agent maintains identity continuity across all 9 methods, loads method-specific knowledge through tiered instructions, manages coaching state, and supports handoffs to RPI agents and the learning tutor.

This is the starter issue for Phase 2 — depends on Phase 1 completion (all 6 foundation instruction files).

Target File

.github/agents/dt-coach.agent.md

Agent Specification

Identity

  • Role: Collaborative DT coaching colleague
  • Personality: Curious, supportive, occasionally challenging — never authoritative, never directive
  • Philosophy: Think/Speak/Empower (defined in dt-coaching-identity.instructions.md)
  • Consistency: Same personality across all methods, all sessions, all industries

Required Phases

The agent definition follows prompt-builder's phase-based protocol (## Required Phases### Phase N: ...):

  1. Phase 1: Session Initialization — Read coaching state, load industry context, orient to current method
  2. Phase 2: Active Coaching — Guide user through current method using Think/Speak/Empower, activate appropriate hats
  3. Phase 3: Method Transition — Handle method completion, offer choices (next method, revisit, hand off)
  4. Phase 4: Session Closure — Update coaching state, provide session summary, set next session context

Tools

Tool Purpose
read_file Load coaching state, method instructions (on-demand tier), industry context
create_file Initialize coaching state, create method artifacts
replace_string_in_file Update coaching state during session
runSubagent Mid-session research dispatch for focused queries

Handoffs

Handoff Target Trigger
"Learn DT" dt-learning-tutor User wants to learn methodology, not apply it
"Research" task-researcher Full handoff for deep research (via space exit prompts)
"Plan" task-planner Full handoff for implementation planning (via space exit prompts)
"Implement" task-implementor Full handoff for implementation (via Implementation Space exit)

Three-Tier Instruction Loading

Tier Loading Content
Ambient Auto-loaded via applyTo glob on .copilot-tracking/dt/** Identity, quality constraints, sequencing
Method Auto-loaded via applyTo glob on .copilot-tracking/dt/**/method-{NN}* Method-specific coaching for the active method
On-demand Loaded via read_file when deep expertise needed Deep method files with advanced techniques

Hat-Switching System

  • 2 shared hats: Active across all methods (Coaching Facilitator, Session Manager)
  • 19 specialized hats: 2 per method (Methods 1-6, 8-9) + 3 for Method 7
  • Hats activate based on method context from coaching state
  • Agent file references hat behaviors defined in method instruction files

Mid-Session Subagent Dispatch

The coach dispatches runSubagent for focused research without full RPI handoff:

  • Industry data, competitive analysis, technical constraints
  • Coach provides specific research query to subagent
  • Subagent returns findings to coach
  • Coach weaves results into coaching conversation
  • Session state and identity continuity maintained throughout

Graduation Awareness

At DT space boundaries, the coach:

  1. Summarizes the current space's outputs
  2. Assesses readiness for next space
  3. Offers choices: continue, hand off via exit prompt, or revisit
  4. References the appropriate space exit handoff prompt when user chooses handoff

Coaching State Management

The agent reads/writes coaching state at .copilot-tracking/dt/{project-slug}/coaching-state.md:

project: "{{project-slug}}"
current_method: 1
current_phase: "planning"
dt_space: "problem"
methods_completed: []
hint_calibration:
  level: 1
  pattern_notes: ""
user_preferences:
  detail_level: "moderate"
  coaching_style: "collaborative"
session_recovery_instructions: |
  Free-text recovery context for session continuity

Authoring Standards

Follow .github/instructions/prompt-builder.instructions.md for agent files:

  • Phase-based protocol structure
  • Frontmatter: description:, tools:, handoffs: fields
  • Writing style: guidance over commands
  • Agent tool access explicitly declared

How to Build This File

This is an .agent.md file — use the prompt-builder agent (not task-implementor) for the authoring phase. The prompt-builder includes built-in Prompt Quality Criteria validation and sandbox testing specific to AI artifacts (.instructions.md, .prompt.md, .agent.md, SKILL.md).

Workflow: /task-research/task-plan/prompt-build/task-review

Between each phase, use /clear to reset context, then attach the output artifact from the previous phase as input for the next.

Phase 1: Research

Gather source material for the Design Thinking Coach agent file.

Source Material: The upstream agent definition — phase structure, hat-switching
mechanics, coaching state schema, handoff specifications, and tool
declarations — is defined in the DT4HVE repository:

design-thinking-for-hve-capabilities/.github/chatmodes/design-thinking.chatmode.md

The chatmode contains the full agent definition including phase protocol
(initialization, coaching, transition, closure), tool declarations, handoff
specifications, three-tier instruction loading, hat-switching mechanics, and
coaching state management. If you don't have the DT4HVE repository cloned, ask
a maintainer for access.

Steps:

  1. Type /clear to start a fresh conversation.
  2. Attach the DT4HVE chatmode file listed above as context.
  3. Copy the prompt below into chat and send.
/task-research topic="DT Coach agent definition for hve-core"

Research the Design Thinking Coach agent patterns for an .agent.md file
targeting `.github/agents/dt-coach.agent.md`.

Use the attached DT4HVE Design Thinking Coach chatmode as the primary source.
Extract and analyze:
- Four-phase agent structure: initialization, coaching, transition, closure
- Tool declarations: read_file, create_file, replace_string_in_file,
  runSubagent
- Handoff specifications between phases and to/from prompts
- Three-tier instruction loading: core (always loaded), method-tier (loaded
  per active method), state-tier (loaded when coaching-state.md is open)
- Hat-switching mechanics: how the agent activates and deactivates specialized
  hats per method
- Coaching state management: state file schema, read/write patterns, session
  persistence
- Subagent dispatch examples for research-heavy coaching steps
- Graduation awareness: how the agent detects readiness to transition between
  methods and spaces

Focus areas:
- How the agent orchestrates without duplicating instruction file content
- What state the agent manages vs. what instructions manage
- How hat-switching creates distinct coaching voices per method
- How handoffs work between the agent and start/resume prompts

The research output will feed `/task-plan` and then `/prompt-build` to author
the agent file.

Output: DT coach agent research

Phase 2: Plan

Plan the agent file structure and orchestration logic using the research output.

Steps:

  1. Type /clear to reset the conversation.
  2. Attach the research document from Phase 1 (from the research phase above).
  3. Copy the prompt below into chat and send.
/task-plan

Plan the implementation of `.github/agents/dt-coach.agent.md` — the central
Design Thinking Coach agent file.

Use the attached research document as the primary input.

The plan should cover:
- Frontmatter structure (`description`)
- Four-phase agent structure (initialization, coaching, transition, closure)
- Tool declarations (read_file, create_file, replace_string_in_file,
  runSubagent)
- Handoff specifications to/from dt-start-project and dt-resume-coaching prompts
- Three-tier instruction loading strategy
- Hat-switching mechanics per method
- Coaching state management (read/write patterns, session persistence)
- Subagent dispatch patterns for research tasks
- Graduation awareness and space transition detection
- The agent orchestrates and references instruction files — it does not
  duplicate their content

The implementation phase will use `/prompt-build` (not task-implementor) since
this is an AI artifact file.

Output: .copilot-tracking/plans/{date}-dt-coach-agent-plan.md

Phase 3: Build

Author the agent file using the prompt-builder agent. Prompt-builder handles authoring standards (frontmatter, writing style, progressive disclosure) automatically through its built-in Prompt Quality Criteria validation.

Steps:

  1. Type /clear to reset the conversation.
  2. Attach the plan document from Phase 2 (find it in .copilot-tracking/plans/).
  3. Copy the prompt below into chat and send.
/prompt-build file=.github/agents/dt-coach.agent.md

Build the Design Thinking Coach agent file following the attached
implementation plan.

Requirements:
- Four-phase agent structure: initialization, coaching, transition, closure
- Tool declarations: read_file, create_file, replace_string_in_file,
  runSubagent
- Handoff specifications to/from dt-start-project and dt-resume-coaching prompts
- Three-tier instruction loading: core (always), method-tier (per active
  method), state-tier (when coaching-state.md is open)
- Hat-switching mechanics with clear activation/deactivation triggers
- Coaching state management: schema reference, read/write patterns
- Subagent dispatch for research-heavy coaching steps
- Graduation awareness for method and space transitions
- Agent orchestrates by referencing instruction files — no content duplication
- Agent definition follows prompt-builder standards for .agent.md files

Output: .github/agents/dt-coach.agent.md

Phase 4: Review

Validate the agent file against the plan and prompt-builder standards.

Steps:

  1. Type /clear to reset the conversation.
  2. Attach the plan document from Phase 2 and the new agent file from Phase 3.
  3. Copy the prompt below into chat and send.
/task-review

Review the implementation of `.github/agents/dt-coach.agent.md` against the
attached plan.

Validate:
- Prompt Quality Criteria from `.github/instructions/prompt-builder.instructions.md`
- Four-phase structure: initialization, coaching, transition, closure
- Tool declarations match planned set (read_file, create_file,
  replace_string_in_file, runSubagent)
- Handoff specifications are complete for start/resume prompts
- Three-tier instruction loading references correct file paths
- Hat-switching mechanics create distinct coaching voices per method
- Coaching state management: schema reference, lifecycle events
- Graduation awareness detects readiness for method and space transitions
- Agent orchestrates without duplicating instruction file content
- No temporal markers, task IDs, or DT4HVE-specific references remain
- Writing style follows prompt-builder standards for .agent.md files

Output: .copilot-tracking/reviews/{date}-dt-coach-agent-review.md

After Review

The reviewer reports one of three outcomes:

  • Pass — The agent file meets all criteria. Open a PR with the new file.
  • Iterate — The reviewer identified specific issues. Return to Phase 3: /clear, attach the review document, then re-run /prompt-build with the fixes noted.
  • Escalate — Fundamental gaps need more research. Return to Phase 1 to investigate the identified areas.

Success Criteria

  • Agent file created at .github/agents/dt-coach.agent.md
  • Phase-based protocol with 4 phases (initialization, coaching, transition, closure)
  • Tools declared: read_file, create_file, replace_string_in_file, runSubagent
  • Handoffs to dt-learning-tutor, task-researcher, task-planner, task-implementor
  • Three-tier instruction loading described (ambient, method, on-demand)
  • Mid-session subagent dispatch specified
  • Graduation awareness at DT space boundaries
  • Coaching state schema defined with all required fields
  • Identity is conversational coaching colleague — never directive
  • Passes task-reviewer validation against prompt-builder standards

Metadata

Metadata

Assignees

Labels

agentsCustom chat agents (.agent.md)featureNew feature triggering minor version bumpgood first issueGood for newcomers

Projects

Status

Done

Milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions