Constrain agentic-workflows agent to single-file output

[Copilot]

The agentic-workflows agent was producing 3–6 documentation files per workflow request (architecture docs, runbooks, usage guides) instead of a single workflow .md file.

Changes

• .github/aw/create-agentic-workflow.md — Added explicit Produce a single workflow file guideline to the Guidelines section with ✅/❌ examples to make the constraint unambiguous:

  • ✅ One file: .github/workflows/<workflow-id>.md (inline ## Usage section permitted)
  • ❌ Multiple files: workflow + docs/workflow-guide.md + README-workflow.md + architecture docs

• .github/agents/agentic-workflows.agent.md — Added Single-file output note to the dispatcher agent's Important Notes so the constraint is enforced at the routing layer, before the creation prompt is even loaded.

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[plan] Guide agentic-workflows agent to produce single-file outputs instead of multiple documentation files</issue_title>
<issue_description>## Objective

Update the agentic-workflows custom agent to explicitly instruct the AI to produce a single workflow .md file as primary output, rather than generating 3–6 documentation files per request.

Context

From discussion #17371 (Agent Persona Exploration), a consistent anti-pattern was observed: the agent creates 3–6 documentation files per workflow request, cluttering the workspace and diluting focus. This was noted in 5 of 8 evaluated scenarios including fe-visual and be-deploy.

Expected: one workflow .md file + a concise inline README section.
Actual: multiple files (architecture docs, runbooks, usage guides, etc.)

Approach

1. Locate the agent system prompt or instructions (likely in skills/ or .github/instructions/)
2. Add an explicit constraint:

   "Produce one workflow .md file as the primary deliverable. If documentation is needed, add a brief inline ## Usage section within the same file. Do not create separate documentation files."

3. Optionally, add a positive example showing the single-file pattern
4. Verify the constraint doesn't conflict with scenarios that legitimately need multiple files

Files to Investigate / Modify

• skills/agentic-chat.md or similar skill file used by the agent
• Agent instruction files in .github/instructions/

Acceptance Criteria

• Agent instructions explicitly state to produce a single workflow file
• Instructions discourage creating separate documentation files
• Guidance is clearly placed where the agent will see it at generation time

Generated by Plan Command for issue #discussion #17371

• expires on Feb 23, 2026, 12:13 PM UTC

Comments on the Issue (you are @copilot in this section)

• Fixes [plan] Guide agentic-workflows agent to produce single-file outputs instead of multiple documentation files #17464

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

[Copilot]

Pull request overview

Updates the agentic-workflows agent instructions to prevent it from generating multiple ancillary documentation files per workflow request, enforcing a single workflow .md as the main output.

Changes:

• Adds an explicit “single workflow file” constraint (with ✅/❌ examples) to the workflow-creation guidance.
• Adds a “single-file output” constraint to the dispatcher agent’s Important Notes to enforce the behavior earlier in routing.

Reviewed changes

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

File	Description
.github/aw/create-agentic-workflow.md	Adds a guideline explicitly requiring single-file workflow output and discouraging extra docs.
.github/agents/agentic-workflows.agent.md	Adds a dispatcher-level note to enforce single-file workflow output before loading creation prompts.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The new “Produce a single workflow file” rule could be read as “only create one file total”, which conflicts with earlier instructions in this doc to include both the source .github/workflows/<workflow-id>.md and the compiled .github/workflows/<workflow-id>.lock.yml in the PR. Consider clarifying that the single-file constraint is about avoiding additional docs (runbooks/architecture/etc.), and that the .lock.yml is still expected.

Suggested change

	- **Produce a single workflow file**: Always output exactly **one** workflow `.md` file as the primary deliverable. Do not create separate architecture documents, runbooks, usage guides, or any other documentation files alongside the workflow.
	- If documentation is needed, add a brief inline `## Usage` section within the same `.md` file.
	- ✅ **Correct**: One file — `.github/workflows/<workflow-id>.md` (with optional `## Usage` section inside)
	- **Produce a single workflow _source_ file**: Always output exactly **one** workflow **source** `.md` file as the primary deliverable. This constraint is about avoiding additional documentation files (architecture docs, runbooks, usage guides, etc.) alongside the workflow source.
	- The compiled lock file **is still required** and does **not** count against this “single source file” rule. You should expect `.github/workflows/<workflow-id>.lock.yml` to be present/committed along with the source `.md`.
	- If documentation is needed, add a brief inline `## Usage` section within the same `.md` file.
	- ✅ **Correct**: One workflow source file — `.github/workflows/<workflow-id>.md` (with optional `## Usage` section inside`)`, plus its compiled `.github/workflows/<workflow-id>.lock.yml`.

[Copilot]

This “Single-file output” note says to produce exactly one workflow .md file, but the same section also states workflows must be compiled to .lock.yml files before running. To avoid confusion (and agents skipping compilation/committing the lock), consider wording this as “no additional documentation files beyond the workflow .md (and its required .lock.yml)”.

Suggested change

	- **Single-file output**: When creating a workflow, produce exactly **one** workflow `.md` file. Do not create separate documentation files (architecture docs, runbooks, usage guides, etc.). If documentation is needed, add a brief `## Usage` section inside the workflow file itself.
	- **Single-file output**: When creating a workflow, do not create additional documentation files beyond the workflow `.md` (and its required `.lock.yml`). Avoid separate architecture docs, runbooks, usage guides, etc.; if documentation is needed, add a brief `## Usage` section inside the workflow file itself.