Add plan workflow templates and docs

[github-actions]

Summary

• Add a new installable Plan workflow under gh-agent-workflows/plan/:
  • example.yml triggers on issue comments created with a /plan prefix (excluding PR comments)
  • README.md documents trigger behavior, inputs, and safe outputs
• Add a new Plan workflow source at github/workflows/gh-aw-plan.md with:
  • workflow-call inputs (model, additional-instructions, setup-commands, allowed-bot-users, messages-footer)
  • planning prompt instructions and add-comment / create-issue safe-output usage (including sub-issues via parent)
• Add Plan to workflow documentation/navigation:
  • docs/workflows/gh-agent-workflows.md
  • mkdocs.yml

Validation

• make lint-workflows ✅
• bin/actionlint gh-agent-workflows/plan/example.yml ✅
• make lint-actions ✅
• make docs-build ⚠️ fails in strict mode on a pre-existing warning:
  • workflows/gh-agent-workflows/pr-review-fork.md links to ../pr-review/README.md (target not found)

Notes

• This run was constrained from editing .github/workflows/ directly, so the new workflow source was added to github/workflows/gh-aw-plan.md.
• Maintainer follow-up: move that file to .github/workflows/gh-aw-plan.md and run make compile to generate .lock.yml and dogfood trigger updates.

Fixes #319

Generated by Update PR Body

Summary by CodeRabbit

• New Features

  • Added Plan workflow: trigger "/plan" in issue comments to generate actionable implementation plans with optional issue/sub-issue creation.

• Documentation

  • Added comprehensive documentation and example configuration for the Plan workflow.
  • Updated workflow navigation guide with new Plan workflow entry.

[cla-checker-service]

❌ Author of the following commits did not sign a Contributor Agreement:
ce92a49,

Please, read and sign the above mentioned agreement if you want to contribute to this project

[coderabbitai]

Caution

Review failed

The pull request is closed.

📝 Walkthrough

Walkthrough

This PR introduces a new "Plan" workflow for GitHub Agent Workflows that enables users to trigger an automated planning assistant via "/plan" commands in issue comments. The workflow generates actionable implementation plans and optionally creates issues or sub-issues to decompose work, alongside supporting documentation and configuration examples.

Changes

Cohort / File(s)	Summary
Documentation and Navigation docs/workflows/gh-agent-workflows.md, mkdocs.yml, gh-agent-workflows/plan/README.md	Added Plan workflow entry to documentation index and mkdocs navigation; introduces new README describing Plan workflow functionality, installation, trigger mechanism (/plan), and configuration inputs (additional-instructions, setup-commands, allowed-bot-users).
Example Workflow Configuration gh-agent-workflows/plan/example.yml	Provides a reference GitHub Actions workflow that triggers on issue comments matching "/plan" pattern; delegates to reusable workflow with required permissions and secret token passing.
Workflow Trigger .github/workflows/trigger-plan.yml	Standalone workflow listening for issue_comment events; filters for non-PR issues and "/plan" trigger text; orchestrates permission scoping and secret delegation to main workflow.
Core Workflow Implementation .github/workflows/gh-aw-plan.lock.yml	Comprehensive 1461-line workflow defining multi-stage planning pipeline including pre-activation validation, Copilot agent orchestration, environment setup (Go, Python, Node.js, Ruby), MCP server/gateway configuration with agents-md-generator and public-code-search tools, threat detection, safe outputs management with issue/comment creation, and artifact collection.
Workflow Metadata and Instructions .github/workflows/gh-aw-plan.md	Defines workflow inputs (model, additional-instructions, setup-commands, allowed-bot-users, messages-footer) with defaults and secrets; provides Plan Assistant documentation including constraints, three-step process for context gathering, investigation/planning, and response posting.

Sequence Diagram

sequenceDiagram
    participant User as User<br/>(issue comment)
    participant Trigger as trigger-plan.yml<br/>(Trigger Workflow)
    participant Main as gh-aw-plan.lock.yml<br/>(Main Workflow)
    participant PreActivation as Pre-Activation<br/>(Setup & Context)
    participant Agent as Copilot Agent<br/>(Planning)
    participant MCP as MCP Gateway<br/>(Tools & Safety)
    participant SafeOutputs as Safe Outputs<br/>(Validation)
    participant GitHub as GitHub API<br/>(Issues/Comments)
    
    User->>Trigger: Comment with "/plan" on issue
    Trigger->>Main: Trigger workflow_call<br/>with COPILOT_GITHUB_TOKEN
    Main->>PreActivation: Validate context & checkout
    PreActivation->>PreActivation: Generate initial prompt<br/>with repository context
    PreActivation->>Main: Return validated context
    Main->>Agent: Setup environment<br/>(Go, Python, Node.js, Ruby, uv)
    Agent->>Agent: Install Copilot CLI & awf
    Agent->>MCP: Initialize MCP gateway<br/>(agents-md-generator,<br/>public-code-search)
    Agent->>MCP: Configure GitHub container<br/>integration
    Agent->>Agent: Run Copilot agent<br/>with interpolated prompt
    Agent->>SafeOutputs: Collect planning output &<br/>validate against schema
    SafeOutputs->>SafeOutputs: Process safe outputs<br/>(create-issue, add-comment)
    SafeOutputs->>GitHub: Execute validated actions<br/>(create issues/comments)
    Main->>Main: Perform threat detection<br/>& parse results
    Main->>Main: Upload artifacts<br/>(prompts, logs, threats, manifests)
    Main->>GitHub: Post conclusion comment<br/>if needed

Loading

Estimated Code Review Effort

🎯 4 (Complex) | ⏱️ ~50 minutes

Possibly Related PRs

• docs: focus docs on gh-aw workflows; move Claude to legacy #280: Modifies mkdocs.yml and workflow documentation structure to emphasize GitHub Agent Workflows organization and navigation, sharing similar documentation and structural updates.

Poem

🐰 A plan to organize the work so neat,
With Copilot's wisdom, workflows complete!
From comments to issues, they spring to life,
Decomposing chaos, reducing strife! 📋✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The PR title 'Add plan workflow templates and docs' directly and clearly describes the main changes: introducing a new plan workflow with its documentation and configuration templates.
Linked Issues check	✅ Passed	The PR successfully implements all coding requirements from issue #319: the plan workflow responds to issue comments via /plan command, creates new issues and sub-issues with parent relationships, integrates into the workflow catalog with documentation, and defines safe outputs.
Out of Scope Changes check	✅ Passed	All changes are directly related to implementing the plan workflow as specified in issue #319; no out-of-scope modifications were introduced.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch copilot/issue-319-plan-workflow-2c2812da335917d5

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[github-actions]

REQUEST_CHANGES: the Plan workflow source is added under github/workflows/ instead of the repository’s canonical .github/workflows/ location, so the corresponding lock workflow is not generated from this PR.

---

What is this? | From workflow: PR Review

Give us feedback! React with 🚀 if perfect, 👍 if helpful, 👎 if not.

[strawgate]

@copilot can you please move the workflows to the right place

[Copilot]

@strawgate I've opened a new pull request, #330, to work on those changes. Once the pull request is ready, I'll request review from you.