feat: Create `.github/aw/workflow-designer.md` — portable conversational workflow design skill

[lpcox]

Summary

Create a new skill file .github/aw/workflow-designer.md that any coding agent can load to conduct a structured conversational interview with a user, progressively gathering requirements, and ultimately generating a complete agentic workflow .md file.

This is distinct from:

• agentic-chat.md — generates task description specs (pseudo-code, no implementation)
• create-agentic-workflow.md — a prompt for agents that already know what to build (references syntax, expects the agent to ask minimal questions)

The workflow-designer skill sits before both: it helps an agent that has zero context about what the user wants conduct a quality interview and arrive at a well-specified workflow.

Motivation

Users often know their goal ("I want to automate PR reviews") but not the gh-aw primitives that map to it (triggers, tools, safe-outputs, network, etc.). The existing create-agentic-workflow.md has an "interactive mode" section but it's minimal — just "ask the next question needed." A dedicated skill with interview structure, decision heuristics, and progressive disclosure will produce consistently better workflows across any coding agent.

Requirements

Portability

• Must work when loaded into any coding agent (Copilot, Claude, Codex, Gemini, custom agents)
• Self-contained — does not assume access to the gh-aw CLI at design time
• References external docs via relative paths (for in-repo agents) and HTTPS URLs (for external agents)

Interview Framework

The skill must define an ordered question taxonomy with progressive disclosure (don't ask everything upfront):

Phase	Questions	Maps To
1. Goal	"What do you want to automate?"	workflow name, description, emoji
2. Trigger	"When should this run?" + follow-ups based on answer	on: block
3. Scope	"What does it need to read? What should it write/create?"	permissions:, tools:, safe-outputs:
4. Guardrails	"Should it block merging, just advise, or silently log?"	safe-output behavior, noop guidance
5. Context	"Does it need external APIs, web access, or specific packages?"	network:, MCP servers
6. Engine	"Any AI engine preference?" (skip if obvious)	engine:
7. Confirmation	Summarize proposed config, ask for approval	—

Decision Heuristics

Include a mapping table that translates natural-language answers to config:

## Trigger Heuristics

| User says... | Maps to |
|---|---|
| "when someone opens a PR" | `on: pull_request:` types: [opened] |
| "when a PR is updated" | `on: pull_request:` types: [opened, synchronize] |
| "every morning" / "daily" | `schedule: daily` (fuzzy) |
| "every Monday" / "weekly" | `schedule: weekly on Monday` |
| "when I say /review" | `on: issue_comment:` + `command: /review` |
| "when an issue is labeled bug" | `on: issues:` types: [labeled] + filter |
| "manually" / "on demand" | `on: workflow_dispatch:` |
| "when a deployment fails" | `on: deployment_status:` |
| "when another workflow finishes" | `on: workflow_run:` |

## Safe Output Heuristics

| User says... | Maps to |
|---|---|
| "post a comment" | `add-comment` |
| "create an issue" | `create-issue` |
| "open a PR" / "submit changes" | `create-pull-request` |
| "add labels" | `add-labels` |
| "remove labels" | `remove-labels` |
| "close the issue" | `close-issue` |
| "assign someone" | `assign-to-user` |
| "nothing visible" / "just analyze" | no safe-outputs needed |

## Network Heuristics

| User says... | Maps to |
|---|---|
| "calls an external API" | ask for FQDN → `network.allowed: [fqdn]` |
| "installs npm packages" | `network.allowed: [node]` |
| "runs pip install" | `network.allowed: [python]` |
| "builds Go code" | `network.allowed: [go]` |
| "no external access" | `network.allowed: [defaults]` |

Progressive Disclosure Rules

The skill must instruct the agent to:

1. Never dump all options at once — ask one question at a time
2. Skip questions when answers are inferrable — if user says "PR reviewer that posts comments", trigger and safe-outputs are already clear
3. Offer smart defaults — "I'd suggest Copilot engine since you haven't mentioned a preference. Sound good?"
4. Ask at most 5 questions before presenting a summary — if more info is needed, present what you have and ask "anything else?"
5. Detect when the user is done — phrases like "that's it", "looks good", "generate it" mean proceed to generation

Confirmation & Generation

After gathering requirements, the agent must:

1. Present a structured summary (not prose):

   📋 Proposed workflow:
   - Name: security-review
   - Trigger: pull_request (opened, synchronize)
   - Engine: copilot
   - Tools: github (gh-proxy)
   - Safe outputs: add-comment
   - Network: defaults
   - Intent: Review PR diffs for security issues and post findings
   

2. Ask: "Ready to generate, or want to adjust anything?"

3. On confirmation, generate the full workflow .md following the skeleton from create-agentic-workflow.md

Validation Self-Check

Before outputting the final workflow, the skill should instruct the agent to verify:

• Permissions are read-only on the agent job (writes go through safe-outputs)
• safe-outputs: matches every write action mentioned in the prompt
• Network access is scoped (no blanket *)
• Trigger matches the user's described activation event
• Prompt instructs agent to call noop when no action is needed
• No unnecessary default fields are included (e.g., engine: copilot is the default — omit it)

References Section

The skill should tell agents where to find more detail:

## References (load only when needed)

- Syntax reference: `.github/aw/syntax.md`
- Safe outputs catalog: `.github/aw/safe-outputs.md`
- Network configuration: `.github/aw/network.md`
- Workflow patterns: `.github/aw/patterns.md`
- Trigger reference: `.github/aw/triggers.md`

Implementation Approach

File Location

.github/aw/workflow-designer.md

Frontmatter

---
name: workflow-designer
description: Conversational skill that interviews users to design new agentic workflows
disable-model-invocation: true
---

Document Structure

# Workflow Designer

[1-2 sentence purpose statement]

## When to Use This Skill
[Routing guidance — when to load this vs create-agentic-workflow.md]

## Interview Framework
### Phase 1: Goal
### Phase 2: Trigger
### Phase 3: Scope (Read/Write)
### Phase 4: Guardrails
### Phase 5: Context & Network
### Phase 6: Engine (optional)
### Phase 7: Confirmation

## Decision Heuristics
### Trigger Mapping
### Safe Output Mapping
### Network Mapping
### Tool Mapping

## Progressive Disclosure Rules
[The 5 rules above]

## Confirmation Format
[The structured summary template]

## Generation Template
[Skeleton with placeholders — references create-agentic-workflow.md skeleton]

## Validation Checklist
[Pre-output self-check]

## References
[Links to load on demand]

Source Material

Draw decision heuristics from:

• .github/aw/create-agentic-workflow.md (trigger mappings lines 58-70, network mappings lines 100-112, safe output mappings lines 119-126)
• .github/aw/syntax.md (full frontmatter field reference)
• .github/aw/triggers.md (trigger types and options)
• .github/aw/safe-outputs.md (all available safe output types)
• .github/aw/network.md (valid ecosystem identifiers)
• .github/aw/patterns.md (architecture patterns for complex requests)
• pkg/cli/interactive.go (the existing TUI question flow — lines 112-240 show the form structure that maps to the interview phases)

Relationship to Other Files

• Does NOT replace create-agentic-workflow.md — that file is the execution prompt for when the agent already knows what to build
• Complements agentic-chat.md — that file generates specs/pseudo-code; this file generates actual workflows
• Should be referenced from the agentic-workflows SKILL.md router when the task is "help me figure out what workflow I need"

Testing

• After creating the file, verify it's valid YAML frontmatter + markdown
• The real test is usage: load it into a Copilot agent session and try designing a workflow conversationally
• No compilation needed (this is a skill doc, not a workflow)

Acceptance Criteria

• .github/aw/workflow-designer.md exists with proper frontmatter
• Contains all 7 interview phases with clear question guidance
• Contains decision heuristic tables for triggers, safe-outputs, network, and tools
• Contains progressive disclosure rules (max 5 questions before summary)
• Contains confirmation summary format template
• Contains generation template (or references the skeleton from create-agentic-workflow.md)
• Contains validation self-check list
• References section points to syntax.md, safe-outputs.md, network.md, triggers.md, patterns.md
• .github/skills/agentic-workflows/SKILL.md is updated to route "help me design a workflow" → this file
• Total file size < 300 lines (concise, not a novel)

Labels

enhancement, documentation

[lpcox]

Addendum: Token Efficiency as Core Design Principle

The workflow-designer skill must produce token-optimized workflows by default. Every generated workflow should apply the DataOps pattern and minimal tooling unless the user explicitly requests otherwise.

Additional Interview Phase: Data Strategy (insert between Phase 3 and Phase 4)

Before deciding on guardrails, the designer should ask:

"What data does the agent need to make its decisions? Can we pre-fetch and aggregate it with shell commands so the agent only reads compact JSON?"

This maps directly to steps: blocks in the frontmatter.

Token Optimization Rules for Generated Workflows

The skill must instruct the agent to apply these rules to every generated workflow:

1. DataOps by Default

If the workflow reads GitHub data (issues, PRs, comments, files), the designer must:

• Generate steps: that use gh CLI + jq to pre-fetch and aggregate data
• Store results as compact JSON under /tmp/gh-aw/data/
• Reference file paths in the prompt body so the agent reads pre-computed data

Bad (agent fetches everything):

Read all open issues and classify them by priority.

Good (pre-fetched):

steps:
  - name: Fetch issues
    run: |
      gh issue list --state open --limit 100 \
        --json number,title,labels,body \
        > /tmp/gh-aw/data/issues.json

Read `/tmp/gh-aw/data/issues.json` and classify each issue by priority.

2. Minimal Tool Surface

• Default to tools.github.mode: gh-proxy (not mode: local)
• Only include tools the workflow actually needs — never dump all toolsets
• Prefer bash + gh over adding MCP toolsets for simple reads
• Use cli-proxy: true when additional MCP servers are needed (agent pipes output through jq)

3. Scope GitHub Toolsets

When gh-proxy is used, specify only the toolsets required:

tools:
  github:
    mode: gh-proxy
    toolsets: [default]  # not [default, pull_requests, issues, repos, ...]

4. Sub-Agent Pattern for Batch Work

If the workflow processes multiple items (issues, PRs, files), the designer should suggest:

• Split items into per-file JSON in steps:
• Use a model: small sub-agent for classification/extraction per item
• Main agent synthesizes compact sub-agent results

5. Prompt Compactness

Generated prompts must:

• Be imperative and concise (no filler, no pleasantries)
• Reference pre-computed file paths explicitly
• Include noop guidance as a single line, not a paragraph
• Put stable instructions before dynamic content (prompt caching)

Decision Heuristic Addition: Data Strategy

User says...	Designer generates
"analyze PRs" / "review issues" / "check status"	steps: with gh CLI pre-fetch
"read the diff" / "look at changed files"	steps: with gh pr diff or gh pr files
"search for patterns across repos"	steps: with gh search + jq filter
"just respond to a comment"	No pre-fetch needed (event payload is enough)
"process each item individually"	Sub-agent pattern with model: small

Updated Validation Checklist

Add these to the pre-output self-check:

• If the workflow reads GitHub data, a steps: block pre-fetches it (DataOps)
• tools.github.mode is gh-proxy (not local) unless MCP toolsets are explicitly needed
• Only required toolsets are listed (no blanket [default, pull_requests, issues, repos])
• Prompt references specific file paths for pre-computed data
• For batch processing (>5 items), sub-agent pattern is suggested

References

Add to the skill's reference section:

• Token optimization: .github/aw/token-optimization.md
• Sub-agents: .github/aw/subagents.md

[pelikhan]

This file belongs in the .github/skills folder and should be packaged as a skill, not as an instruction file.