Agent-Based Coding Workflow

This document describes the agent-based workflow for feature development in this project. The workflow is inspired by best practices from the GitHub Copilot agents article, the VS Code Copilot Custom Agents documentation, and modern software engineering principles. Agents work locally and produce artifacts as markdown files in the repository. The Maintainer coordinates handoffs between agents by starting chat sessions with each agent in VS Code. Agents may ask the Maintainer for clarification or request that feedback be relayed to a previous agent. ---

The workflow begins when the Maintainer identifies a need:

• New Feature: Start with the Requirements Engineer agent to gather requirements and create a Feature Specification • Bug Fix / Incident: Start with the Issue Analyst agent to investigate and document the issue • Workflow Improvement: Start with the Workflow Engineer agent to modify the development process itself • Website Changes: Start with the Web Designer agent to implement design, content, or functionality changes to the tfplan2md website Throughout the workflow, the Maintainer coordinates handoffs between agents and provides clarifications as needed.

For well-defined features or bugs, use the Workflow Orchestrator agent to automate the complete workflow: • GitHub (Cloud) - RECOMMENDED: Assign a GitHub issue to @copilot to trigger automated orchestration from issue to release. The orchestrator runs as a coding agent with full delegation capabilities via the task tool. • VS Code (Local) - LIMITED: Use @workflow-orchestrator in chat for interactive orchestration. Note that full programmatic delegation is limited in VS Code context compared to GitHub. How It Works: • The orchestrator never asks clarifying questions - it immediately delegates to the appropriate entry point agent (Requirements Engineer for features, Issue Analyst for bugs) • The orchestrator never implements anything itself - it purely delegates to specialized agents in sequence • Entry point agents (Requirements Engineer, Issue Analyst) handle requirements gathering and ask any needed clarifying questions • The orchestrator tracks progress and handles feedback loops (code review rework, UAT failures) Best for: • Complete feature implementations with clear issue descriptions • Bug fixes needing full workflow (investigation → fix → release) • Reducing cognitive load on routine development tasks • GitHub issue-driven development Not suitable for: • Exploratory analysis or design work (use individual agents directly) • Single-agent tasks (just use that agent) • Highly interactive work requiring maintainer decisions at each step Verification note: If a change only touches agent instructions / skills / documentation (for example .github/agents/, .github/skills/, .github/copilot-instructions.md, or docs/), running dotnet test is not required because the test suite does not validate those changes. Run dotnet test when C# code changes. ---