GitHub Issues + Projects ↔ Copilot Coding Agent: End-to-End Automation

Status: background, not as-built. The repo adopted a provider-agnostic implementation that runs the coding agent via GitHub Agentic Workflows (gh-aw) on the repository’s own API key, not the GitHub Copilot Coding Agent, so any maintainer with write access can drive it without a Copilot seat (see ADR-0002). The canonical, as-built description is ai-pathway.md; where the two differ, that document wins. Notable deviations from the design below: the ai:improve-writing button was dropped; “assign to Copilot” became “add path:ai-automation → agent posts a plan → /approve-plan”; the @copilot iteration loop became the /coco slash command (gh-aw has no @mention trigger); and notifications are GitHub @-mentions rather than email. This document is retained for the design rationale and the broader landscape (§10).

This document describes an automation that turns a GitHub Issue into a deployed dev build with minimal human steps, entirely inside GitHub (no external tracker, no external orchestrator). The implementer is GitHub Copilot Coding Agent; the orchestrator is GitHub Actions; the human-facing “buttons” are issue labels, GitHub Project status columns, and slash commands in issue/PR comments. The visual board is a GitHub Project (v2) attached to the repo. The design satisfies four constraints:

Every step of the lifecycle is recorded as a comment on a single GitHub issue and as a status change on the Project board; together they are the audit log.
All AI instructions (system prompts, persistent agent rules, per-flow prompts) live in this repository, version-controlled and reviewable in PRs.
The reviewer can talk back to Copilot by @copilot-mentioning it on the PR. Copilot replies, pushes new commits, and CI re-runs. No custom backend is needed for the iteration loop; GitHub provides it natively.
The existing CI pipeline (semver tags → dev-vX.Y.Z → dev environment) is kept as-is. The automation only triggers it; it does not replace it.

Because everything stays inside GitHub, the design is deliberately simple: no cross-system tokens, no web-request plumbing, no custom-field ID mapping, no mirror workflow. The GitHub Issue is the work item.

1. High-level flow

Every transition writes a comment back to the originating issue and updates the issue’s row on the Project board.

2. Why this shape

Copilot Coding Agent is the implementer. When an issue is assigned to Copilot, it provisions a sandboxed VM, clones the repo, reads the agent instructions, opens a draft PR, and iterates until tests pass. The feedback loop is built in: a comment that mentions @copilot on the PR is treated as a new instruction, and Copilot preserves PR history as context. That loop does not need to be built separately.
GitHub Actions is the orchestrator, not a separate backend service. Each “button” is either an issues: labeled workflow, an issue_comment workflow, or (rarely) a projects_v2_item workflow. Secrets live in GitHub Secrets; there is no extra host to operate and no cross-system token.
All prompts live in the repo (.github/prompts/, AGENTS.md, .github/instructions/). They are reviewed in PRs and rollback is git revert.
The Project (v2) is the visual board. It is GitHub-native, supports custom fields and saved views, and has built-in automations for the obvious transitions (issue closed → Done, PR merged → Done). For more nuanced transitions, an Action calls the GraphQL updateProjectV2ItemFieldValue mutation.
The existing CI tag-based deploy is the deploy mechanism. promote-dev.yml only creates the tag; ci.yml does the rest.

Native Copilot integration. This document assumes a GitHub Copilot plan that grants the Copilot Coding Agent. Assigning an issue to the Copilot user is the only trigger Copilot needs to start work (no app install, no webhook setup). The trigger is already in GitHub.

3. Repository + Project layout

Everything the automation needs is in .github/ and a single GitHub Project attached to the repo (or to the org):

What goes where, conceptually

File / directory	Read by	When	Purpose
`AGENTS.md`	Copilot Coding Agent	Every implementation run	Persistent project rules (style, no-secrets, dependency policy, …).
`.github/instructions/*.instructions.md`	Copilot Coding Agent	When touching matching paths	Layer-specific rules (e.g. “use FastAPI’s dependency injection, not globals”).
`.github/prompts/*.md`	Orchestration workflows	When that workflow runs	Templated prompts for non-Copilot LLM calls (issue rewrite, PR review, …).
`.github/automation/config.yml`	All workflows	At workflow start	Single source of truth for model IDs, label names, Project + field node IDs.
GitHub Project (v2)	Humans + sync workflow	Continuously	Visual board, status field, custom fields (Reviewer, Dev URL, PR URL).

The .prompt.md and .agent.md filename conventions are reserved for IDE/CLI chat; they are not used here. This repo uses plain .md files invoked by workflows, which gives full control over the body.

4. The seven manual triggers

Every trigger is a native GitHub gesture:

#	“Button” the human uses	Mechanism	Effect
1	Improve issue writing	Add label `ai:improve-writing` to the issue	Workflow rewrites the issue body in place; removes the label.
2	Hand to Copilot	Assign the issue to `Copilot` (or set Project status → “Ready for AI”)	Copilot opens a draft PR. Project auto-moves the row to “In Progress”.
3	Request automated review	Add label `ai:review` to the PR (also auto on CI green)	Workflow posts an AI review on the PR.
4	Promote to dev	PR comment `/promote dev`	Creates `dev-vX.Y.Z` tag; CI deploys.
5	Notify reviewer	Automatic after dev deploy success	Email to the user named in the Project’s Reviewer field.
6	Notify me (final review)	Automatic on PR `approved` review	Email to the issue author.
7	Apply reviewer instruction	PR comment `@copilot …`	Copilot natively revises.

Triggers 1 and 3 use labels as buttons: adding the label is the user’s action, and the workflow’s first step is to remove the label so it can be re-added later. Triggers 4 and 7 use slash/mention commands in PR comments, which read naturally in the review thread. Trigger 2 uses the native assign field, which is the single trigger the Copilot Coding Agent listens for. Trigger 7 deliberately bypasses the orchestration: Copilot’s own iteration loop is the simplest, most reliable way to apply a reviewer’s instruction with full history.

5. Step-by-step setup

Step 5.1: Decide on the Project shape

Create a GitHub Project (v2), either at the org or user level, and attach it to this repo. Add these custom fields:

Status (single-select, built-in): Backlog, Ready for AI, In Progress, Review, On Dev, Approved, Done.
AI Status (single-select, optional): Idle, Improving, Implementing, Reviewing, On Dev. Useful for a concurrent field separating human progress from AI progress on the same row.
Reviewer (User picker): drives email notifications.
Dev URL (URL).
PR URL (URL): also auto-filled when an issue is linked to a PR via “Development” sidebar.
Sprint / Iteration (Iteration field, optional).

Suggested views on the board:

Triage: filter Status = Backlog. Where humans land new issues.
AI queue: filter Status in (Ready for AI, In Progress). Where Copilot’s work is watched.
Review on dev: filter Status = On Dev. Reviewer’s queue.
Released: filter Status = Done, group by iteration.

Configure the Project’s built-in workflows (Project → Settings → Workflows):

Item added to project → set Status = Backlog.
Pull request merged → set Status = Done.
Issue closed → set Status = Done.
Code changes requested on PR → set Status = In Progress.

These cover the obvious transitions for free. The non-obvious transitions (Ready for AI → In Progress on PR open, In Progress → On Dev on dev deploy) are handled by project-status-sync.yml (§5.11) using the GraphQL API. There is no need to model every status as a hard state machine; most transitions are advisory and the workflows reconcile them.

Step 5.2: Configure repository permissions for Actions

Because every trigger fires from inside GitHub, the workflows can use the default GITHUB_TOKEN. It just needs enough scope granted. In Settings → Actions → General → Workflow permissions:

Choose Read and write permissions.
Allow GitHub Actions to create and approve pull requests.

Per-workflow, declare the minimum scopes (always prefer this over the global toggle once things are stable):

permissions:
  issues: write          # edit issue body, comment, label
  pull-requests: write   # comment, label
  contents: write        # push tags from promote-dev.yml only

For Projects (v2), the default GITHUB_TOKEN cannot write to org-owned projects. If the Project is org-owned, create a fine-grained PAT for a service account with Projects: read & write on the relevant org, store it as the repo secret PROJECTS_TOKEN, and reference it from project-status-sync.yml. If the Project is user-owned and attached to this repo only, GITHUB_TOKEN is sufficient.

Step 5.3: Add LLM + notification secrets

The only secrets required are:

OPENAI_API_KEY (or ANTHROPIC_API_KEY): for the LLM calls in workflows.
SENDGRID_API_KEY (or SMTP_*): for notification emails.
PROJECTS_TOKEN: only if the Project is org-owned (§5.2).

Note that no cross-system credentials are needed. That entire surface area is gone.

Step 5.4: Write the persistent agent instructions

Create AGENTS.md at .github/AGENTS.md. This is the file Copilot reads on every implementation run. Keep it short and load-bearing.

# Repository agent instructions

## Project shape
- Monorepo: `backend/` (FastAPI), `frontend/` (Next.js), `deployment/`.
- PRs must target `develop`, never `main`.

## Coding rules
- Backend: type-hint all new functions. Use FastAPI dependency injection.
- Frontend: TypeScript only; no `any`.
- Never commit secrets. `.env*` files are gitignored; do not unignore them.

## Test rules
- Backend: pytest. New endpoints require a happy-path test.
- Frontend: lint must pass (`npm run lint`).

## Out of scope
- Do not modify `.github/workflows/ci.yml` or `deployment/` files unless the
  issue explicitly says so.

Add path-scoped instructions for finer-grained rules:

.github/instructions/backend.instructions.md
.github/instructions/frontend.instructions.md

Each should have YAML frontmatter declaring its scope:

---
applyTo: "backend/**"
---
- Use the existing `backend/app/llm/` factory; do not call provider SDKs directly from routes.
- Database access must go through `backend/app/db/` repositories.

Step 5.5: Write the one-shot prompts

Each file in .github/prompts/ is a Markdown template with placeholders the workflow substitutes at runtime. Example improve-issue.md.

You are rewriting a GitHub issue so engineers can act on it.

Rules:
- Preserve the original intent. Do not invent requirements.
- Output sections in this exact order: ## Context, ## Goal, ## Acceptance criteria, ## Out of scope.
- Acceptance criteria must be a checklist of testable statements.
- Preserve any "Linked PR" or "Related issues" trailers at the bottom.

## Original issue
Title: {{title}}

Body:
{{body}}

Repeat for review-pr.md (review prompt fed the PR diff) and any other one-shot LLM operation as needed.

Step 5.6: Workflow: improve issue writing (label-triggered)

.github/workflows/improve-issue.yml:

name: Improve issue writing
on:
  issues:
    types: [labeled]

jobs:
  improve:
    if: github.event.label.name == 'ai:improve-writing'
    runs-on: ubuntu-latest
    permissions:
      issues: write
    steps:
      - uses: actions/checkout@v4

      - name: Render prompt + call LLM + edit issue
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
          ISSUE_NUMBER: ${{ github.event.issue.number }}
          ISSUE_TITLE:  ${{ github.event.issue.title }}
          ISSUE_BODY:   ${{ github.event.issue.body }}
        run: |
          python .github/scripts/improve_issue.py

      - name: Remove the trigger label
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          gh issue edit "${{ github.event.issue.number }}" \
            --remove-label "ai:improve-writing"

Companion script .github/scripts/improve_issue.py reads .github/prompts/improve-issue.md, substitutes placeholders, calls the LLM, and runs gh issue edit "$ISSUE_NUMBER" --body-file <(...). It also posts a comment with the diff against the previous body so the audit log is preserved. Why a label and not a slash command? A label is visible in the issue sidebar, can be added from mobile, and is reflected on the Project board as a filterable property. Slash commands are great for PRs but slightly hidden on issues.

Step 5.7: Hand the issue to Copilot

There are two equally good UX choices; either can be picked, or both supported. Option A: Direct assignment (recommended). The human opens the issue and sets the Assignees field to Copilot. That is the only trigger the Copilot Coding Agent needs. No workflow required. Option B: Status-driven. The human drags the row on the Project board to Status = Ready for AI. A workflow (assign-to-copilot.yml) listens to projects_v2_item events, sees the status change, and runs gh issue edit --add-assignee Copilot. This is the nicer board-driven UX but costs an extra workflow. .github/workflows/assign-to-copilot.yml (Option B):

name: Assign issue to Copilot when ready
on:
  # `projects_v2_item` is available on repos linked to org-owned Projects.
  # If your Project is user-owned, use Option A or a `workflow_dispatch` shim.
  projects_v2_item:
    types: [edited]

jobs:
  assign:
    runs-on: ubuntu-latest
    permissions:
      issues: write
    steps:
      - name: Check if this edit moved the item to "Ready for AI"
        id: gate
        uses: actions/github-script@v7
        with:
          script: |
            const change = context.payload.changes?.field_value;
            if (!change) return core.setOutput('go', 'false');
            const moved = change.from?.name !== 'Ready for AI'
                       && change.to?.name === 'Ready for AI';
            core.setOutput('go', moved ? 'true' : 'false');
      - name: Resolve linked issue and assign Copilot
        if: steps.gate.outputs.go == 'true'
        env:
          GH_TOKEN: ${{ secrets.PROJECTS_TOKEN || secrets.GITHUB_TOKEN }}
        run: |
          python .github/scripts/assign_to_copilot.py \
            --item-id "${{ github.event.projects_v2_item.node_id }}"

The script resolves the linked Issue node, then runs gh issue edit "$NUMBER" --add-assignee Copilot. When the issue is assigned to Copilot, Copilot spins up a sandboxed environment, reads AGENTS.md, opens a draft PR on copilot/issue-<n>, and begins committing. No workflow is needed for that step; the assignment is the trigger.

Step 5.8: Workflow: AI review after CI passes

.github/workflows/ai-review-pr.yml runs when CI completes successfully on a PR (or when the ai:review label is added for an on-demand re-review):

name: AI review PR
on:
  workflow_run:
    workflows: ["CI"]
    types: [completed]
  pull_request:
    types: [labeled]

jobs:
  review:
    if: |
      (github.event_name == 'workflow_run' &&
       github.event.workflow_run.conclusion == 'success' &&
       github.event.workflow_run.event == 'pull_request')
      ||
      (github.event_name == 'pull_request' &&
       github.event.label.name == 'ai:review')
    runs-on: ubuntu-latest
    permissions:
      pull-requests: write
      contents: read
    steps:
      - uses: actions/checkout@v4
        with:
          ref: ${{ github.event.workflow_run.head_sha || github.event.pull_request.head.sha }}
      - run: python .github/scripts/ai_review.py \
               --pr-sha "${{ github.event.workflow_run.head_sha || github.event.pull_request.head.sha }}" \
               --prompt .github/prompts/review-pr.md
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}

The script fetches the PR diff, renders the prompt, calls the LLM, posts a review comment (not an approval) summarising risks and suggested changes. Approval stays human.

Step 5.9: Workflow: `/promote dev` comment → dev tag

.github/workflows/promote-dev.yml:

name: Promote to dev
on:
  issue_comment:
    types: [created]

jobs:
  promote:
    if: |
      github.event.issue.pull_request &&
      startsWith(github.event.comment.body, '/promote dev') &&
      contains(fromJson('["OWNER","MEMBER","COLLABORATOR"]'),
               github.event.comment.author_association)
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - name: Compute next dev tag
        id: tag
        run: |
          # naive bump: replace with your conventional-commits / semver script
          LAST=$(git tag --list 'dev-v*' --sort=-v:refname | head -n1 || echo dev-v0.0.0)
          NEXT=$(echo "$LAST" | awk -F. -v OFS=. '{$NF+=1; print}')
          echo "name=$NEXT" >> $GITHUB_OUTPUT
      - name: Push tag
        run: |
          git tag "${{ steps.tag.outputs.name }}"
          git push origin "${{ steps.tag.outputs.name }}"
      - name: Acknowledge in PR thread
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          gh pr comment "${{ github.event.issue.number }}" \
            --body "Tag \`${{ steps.tag.outputs.name }}\` pushed. Dev deploy starting."

Because the existing ci.yml already deploys on dev-vX.Y.Z tags, that is the entire dev-promotion step.

Permission gate. The author_association check restricts who can run /promote dev; otherwise anyone with read access could trigger a deploy. Tighten further with a team check via gh api /orgs/.../teams/.../members to restrict the power to a specific team.

Step 5.10: Workflow: notify on approval

.github/workflows/notify-on-approve.yml listens for pull_request_review events of type approved and sends the email:

name: Email author on PR approval
on:
  pull_request_review:
    types: [submitted]

jobs:
  notify:
    if: github.event.review.state == 'approved'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: python .github/scripts/notify_author.py \
               --pr-number "${{ github.event.pull_request.number }}" \
               --author "${{ github.event.pull_request.user.login }}"
        env:
          SENDGRID_API_KEY: ${{ secrets.SENDGRID_API_KEY }}
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Read recipient addresses from .github/automation/config.yml (mapped from the GitHub login of the author) or, better, from the Project’s Reviewer field via GraphQL; that way the recipient is whatever the human set on the row.

Step 5.11: Configure Project automations (the human side)

Most of the Project board’s behavior comes from its built-in workflows (set up in Step 5.1). The remaining transitions are handled by .github/workflows/project-status-sync.yml, which reacts to GitHub events and writes back to the Project via GraphQL:

Event	Status set to	Notes
Issue assigned to `Copilot`	`In Progress`	(only if Copilot then opens a draft PR within ~2 min; otherwise stays at the prior status)
PR labeled `ai:review`	`Review`	Manual override.
`dev-vX.Y.Z` tag deploy succeeds	`On Dev`	Resolves PR from tag’s commit.
PR reviewed & approved	`Approved`
PR merged	`Done`	Also covered by built-in workflow.

Skeleton workflow:

name: Sync Project status
on:
  issues:
    types: [assigned]
  pull_request:
    types: [labeled]
  pull_request_review:
    types: [submitted]
  workflow_run:
    workflows: ["CI"]   # to catch dev deploys
    types: [completed]

jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: python .github/scripts/project_status_sync.py
        env:
          GH_TOKEN: ${{ secrets.PROJECTS_TOKEN || secrets.GITHUB_TOKEN }}
          PROJECT_ID:        ${{ vars.PROJECT_ID }}
          STATUS_FIELD_ID:   ${{ vars.STATUS_FIELD_ID }}
          STATUS_OPTION_IDS: ${{ vars.STATUS_OPTION_IDS }}   # JSON map

PROJECT_ID, STATUS_FIELD_ID, and the option IDs are resolved once via the GraphQL Explorer (or gh api graphql -f query='…') and stored as repo variables. They do not rotate. The script uses the updateProjectV2ItemFieldValue GraphQL mutation:

mutation($projectId: ID!, $itemId: ID!, $fieldId: ID!, $optionId: String!) {
  updateProjectV2ItemFieldValue(input: {
    projectId: $projectId,
    itemId:    $itemId,
    fieldId:   $fieldId,
    value:     { singleSelectOptionId: $optionId }
  }) {
    projectV2Item { id }
  }
}

6. The Copilot loop in detail

Once the issue is assigned to Copilot:

Copilot creates branch copilot/issue-<n> and opens a draft PR using .github/pull_request_template.md.
Copilot reads AGENTS.md, then the relevant .github/instructions/*.instructions.md files based on which paths it is about to touch.
Copilot iterates internally: write → run tests → diagnose → revise. Each iteration pushes a commit, which appears as a comment-like entry in the PR timeline.
ci.yml runs on each push because of the existing pull_request trigger.
When the agent believes it is done, it marks the PR ready for review and posts a summary comment.

To send feedback, a reviewer comments on the PR (not the issue):

@copilot the dev container failed health-check at /api/health.
The cause looks like a missing env var. Please add a default to settings.py
and a test that covers the missing-env path.

Copilot picks up the mention, treats the entire PR thread + AGENTS.md as context, and pushes new commits. Nothing needs to be dispatched manually.

7. Optional: structured input via Issue Forms

A free-text issue body is fine, but issue forms (.github/ISSUE_TEMPLATE/*.yml) give Copilot cleaner context. Example feature_request.yml:

name: Feature request
description: Ask Copilot to implement a feature
title: "[feat] "
labels: ["enhancement"]
body:
  - type: textarea
    id: context
    attributes:
      label: Context
      description: What is the user need, and what is the current behavior?
    validations:
      required: true
  - type: textarea
    id: goal
    attributes:
      label: Goal
      description: One sentence describing what success looks like.
    validations:
      required: true
  - type: textarea
    id: acceptance
    attributes:
      label: Acceptance criteria
      description: Checklist of testable statements. Copilot will use these.
      placeholder: |
        - [ ] Endpoint `POST /foo` returns 201 with the new id
        - [ ] Unit test covers the missing-field error path
    validations:
      required: true
  - type: input
    id: out_of_scope
    attributes:
      label: Out of scope

When the human fills the form, the resulting issue body has predictable sections, so the improve-issue workflow rarely needs to run, and Copilot can parse the acceptance criteria directly.

8. Things that are deliberately not in scope

A FastAPI orchestrator. Adding one is justified if the project later needs cross-repo orchestration, long-running jobs >6h, or non-GitHub destinations (Slack threads, custom dashboards). Until then, Actions is enough.
Auto-approval by AI. ai-review-pr.yml posts a comment, never an approval. The human gate is non-negotiable for merges to develop.
Status as a hard state machine. The Project’s Status field is a convenience for humans, not a contract. Workflows do not block on it being in a particular state; they react to the underlying GitHub events.
Mirroring to external systems. The whole point of this variant is that the issue + PR + Project board are the audit log. No mirror layer.

9. Open decisions to make

Hand-off UX. Option A (assign to Copilot) is simpler and works without projects_v2_item permissions. Option B (drag on the board) is nicer for teams that live on the board. Both can be supported; they are not exclusive.
Which LLM provider for the non-Copilot calls. OpenAI, Anthropic, or Google. Pick one and set it in .github/automation/config.yml.
Tag-naming for dev promotions. The existing CI expects strict dev-vX.Y.Z. Decide whether /promote dev bumps PATCH automatically or whether the comment must include the version: /promote dev v1.2.3.
Permission policy for /promote dev. Restrict to OWNER/MEMBER (default in the example), or to a specific GitHub team.
Project scope (user vs. org). Org-owned Projects support projects_v2_item events but require the PROJECTS_TOKEN PAT for writes. User-owned Projects skip the PAT but lose the event-driven status updates, falling back to polling or label-based triggers.
Issue forms vs. free-text. Strongly recommended to use forms; they make §5.6’s improve-issue workflow optional.

Once these are decided, the files can be scaffolded and issues labelled one by one.

10. The broader GitHub AI automation landscape

The GitHub-only Issue → Copilot loop is one slice of what GitHub now ships. This section catalogues the rest so the doc gives a holistic picture, and notes which ones are worth turning on for this repo. Each item is tagged:

Turn on: clear ROI for this repo, low setup cost.
Consider: useful but adds operational surface; pick when there’s a need.
Watch: preview / early-stage; revisit later.

A. Native integrations worth enabling

A.1. GitHub Copilot code review (Turn on)

A built-in PR-review feature, distinct from this repo’s custom ai-review-pr.yml. Two modes:

On-demand: request a review from Copilot in the PR reviewers panel.
Automatic: configure Copilot to review every PR opened in selected repos (Repository → Rulesets → branch ruleset, or in user settings for personal Copilot Pro).

What it does well: catches obvious bugs, style issues, missing null-checks, suggests fixes inline. What it does not do: domain-specific architecture review against the AGENTS.md rules. That’s what the custom ai-review-pr.yml prompt is for. Recommendation: run both. The native review is free with the Copilot plan; the custom review is where HAICO-specific constraints are encoded.

A.2. CodeQL + Copilot Autofix (Turn on)

CodeQL is GitHub’s static-analysis engine (free for public repos, included with GitHub Advanced Security on private). Copilot Autofix turns each CodeQL finding into a suggested patch that can be merged with one click. Together they cover the “security review” leg without a custom workflow. Setup: Settings → Code security → enable CodeQL analysis (default config) and Copilot Autofix for CodeQL. Findings appear in the Security tab and as PR review comments.

A.3. Dependabot (already on)

This repo already has .github/dependabot.yml. The AI layer worth adding here is Dependabot’s grouped updates + Copilot Autofix for vulnerable dependencies, which can land a tested upgrade PR with no human-authored code.

A.4. Secret scanning + push protection (Turn on)

GitHub-native, free for public repos. Push protection blocks commits that contain known secret patterns before they reach the remote, an important guardrail when Copilot has write access to the branch.

A.5. Project built-in workflows (Turn on)

Already used in §5.1. Worth flagging here as a reminder: the Item added, Auto-close issue, Auto-archive items, and Pull request merged automations cover ~60% of the Project transitions that would otherwise need scripting. Reach for the custom project-status-sync.yml only for the rest.

There is no issue-creation workflow in this design, because the issue is filed directly in GitHub.

B. New surface area for AI-driven workflows

B.1. Agentic Workflows (`gh-aw`) (Consider: technical preview)

Released as a technical preview in February 2026. A workflow is written as a Markdown file with natural-language instructions and a frontmatter declaring inputs / tools / triggers; the gh aw compile CLI emits a hardened *.lock.yml GitHub Actions workflow that runs an AI agent (Copilot, Claude, or Codex) in a sandboxed container. Example use cases that fit this repo:

Triage incoming issues: read the issue, apply labels (needs-info, bug, enhancement), ask for missing reproduction info. Especially useful in the GitHub-only flow since there is no upstream layer to do triage.
Generate a changelog for each dev-vX.Y.Z tag from the commit range.
Refresh documentation when files in backend/app/api/ change.
Project hygiene: sweep the Project board weekly, flag stale items, ask authors for status.

When to use it instead of writing Actions directly: when the task is underspecified, the inputs vary, and the agent should decide what to do. When to not use it: deterministic glue (creating an issue, posting a comment, pushing a tag); plain Actions are clearer and cheaper.

B.2. GitHub Copilot Spaces (Consider)

GA since 2025. A Space is a shareable container of repos + docs + free text + behavioural instructions that Copilot uses as grounding context. A Space is useful when knowledge sits outside the repo (e.g. a Notion export of architecture decisions, transcripts of design reviews, third-party API specs) and should be considered by Copilot in chat. For HAICO specifically: a “HAICO architecture” Space attached to this repo, with the project’s design/reference documents attached, would make Copilot answer architecture questions with paper-aware context, without adding those documents to the repo’s text-search index.

B.3. MCP servers (Model Context Protocol) (Consider for advanced flows)

MCP lets an agent call external tools as if they were local functions. Copilot in VS Code, CLI, and the cloud agent can all consume MCP servers. Relevant catalog for a GitHub-only flow:

MCP server	Lets the agent…
GitHub MCP	call any GitHub API operation, not just the wrapped ones
Sentry / Datadog	pull error traces while debugging
Postgres / Supabase	run read-only queries against a dev DB
Linear / Notion	only if one is adopted later, none currently in scope

MCP servers are configured per-environment (e.g. .vscode/mcp.json for the IDE; the Copilot Coding Agent has its own configuration UI). For this scope, the GitHub server covers ~90% of value because the rest of the world lives outside this stack anyway.

B.4. GitHub Spark (Watch)

GitHub’s prompt-to-app builder. Out of scope for an established repo; it’s better suited to generating new prototypes. Worth knowing about when sketching a sibling demo app.

C. Things to enforce in the repo’s structure

Independent of any product, these are conventions that make every AI feature work better:

AGENTS.md at the repo root: already in the plan (§5.4). This is the single highest-leverage file that can be added.
.github/instructions/*.instructions.md with applyTo: frontmatter for per-area rules (backend/frontend/deployment).
Issue forms (.github/ISSUE_TEMPLATE/*.yml): see §7. The GitHub-only flow leans hard on these, because they serve as the structured input.
CODEOWNERS mapping paths to humans: Copilot uses this to choose reviewers when opening PRs, and the Project’s Reviewer field can default from this mapping.
ADRs (Architecture Decision Records) under docs/adr/: Copilot reads them as context for architecture-touching changes.

Community & contribution

CI & automation

Background

Copilot automation (background)

GitHub Issues + Projects ↔ Copilot Coding Agent: End-to-End Automation

1. High-level flow

2. Why this shape

3. Repository + Project layout

What goes where, conceptually

4. The seven manual triggers

5. Step-by-step setup

Step 5.1: Decide on the Project shape

Step 5.2: Configure repository permissions for Actions

Step 5.3: Add LLM + notification secrets

Step 5.4: Write the persistent agent instructions

Step 5.5: Write the one-shot prompts

Step 5.6: Workflow: improve issue writing (label-triggered)

Step 5.7: Hand the issue to Copilot

Step 5.8: Workflow: AI review after CI passes

Step 5.9: Workflow: `/promote dev` comment → dev tag

Step 5.10: Workflow: notify on approval

Step 5.11: Configure Project automations (the human side)

6. The Copilot loop in detail

7. Optional: structured input via Issue Forms

8. Things that are deliberately not in scope

9. Open decisions to make

10. The broader GitHub AI automation landscape

A. Native integrations worth enabling

A.1. GitHub Copilot code review (Turn on)

A.2. CodeQL + Copilot Autofix (Turn on)

A.3. Dependabot (already on)

A.4. Secret scanning + push protection (Turn on)

A.5. Project built-in workflows (Turn on)

B. New surface area for AI-driven workflows

B.1. Agentic Workflows (`gh-aw`) (Consider: technical preview)

B.2. GitHub Copilot Spaces (Consider)

B.3. MCP servers (Model Context Protocol) (Consider for advanced flows)

B.4. GitHub Spark (Watch)

C. Things to enforce in the repo’s structure

11. Sources

​GitHub Issues + Projects ↔ Copilot Coding Agent: End-to-End Automation

​1. High-level flow

​2. Why this shape

​3. Repository + Project layout

​What goes where, conceptually

​4. The seven manual triggers

​5. Step-by-step setup

​Step 5.1: Decide on the Project shape

​Step 5.2: Configure repository permissions for Actions

​Step 5.3: Add LLM + notification secrets

​Step 5.4: Write the persistent agent instructions

​Step 5.5: Write the one-shot prompts

​Step 5.6: Workflow: improve issue writing (label-triggered)

​Step 5.7: Hand the issue to Copilot

​Step 5.8: Workflow: AI review after CI passes

​Step 5.9: Workflow: /promote dev comment → dev tag

​Step 5.10: Workflow: notify on approval

​Step 5.11: Configure Project automations (the human side)

​6. The Copilot loop in detail

​7. Optional: structured input via Issue Forms

​8. Things that are deliberately not in scope

​9. Open decisions to make

​10. The broader GitHub AI automation landscape

​A. Native integrations worth enabling

​A.1. GitHub Copilot code review (Turn on)

​A.2. CodeQL + Copilot Autofix (Turn on)

​A.3. Dependabot (already on)

​A.4. Secret scanning + push protection (Turn on)

​A.5. Project built-in workflows (Turn on)

​B. New surface area for AI-driven workflows

​B.1. Agentic Workflows (gh-aw) (Consider: technical preview)

​B.2. GitHub Copilot Spaces (Consider)

​B.3. MCP servers (Model Context Protocol) (Consider for advanced flows)

​B.4. GitHub Spark (Watch)

​C. Things to enforce in the repo’s structure

​11. Sources

GitHub Issues + Projects ↔ Copilot Coding Agent: End-to-End Automation

1. High-level flow

2. Why this shape

3. Repository + Project layout

What goes where, conceptually

4. The seven manual triggers

5. Step-by-step setup

Step 5.1: Decide on the Project shape

Step 5.2: Configure repository permissions for Actions

Step 5.3: Add LLM + notification secrets

Step 5.4: Write the persistent agent instructions

Step 5.5: Write the one-shot prompts

Step 5.6: Workflow: improve issue writing (label-triggered)

Step 5.7: Hand the issue to Copilot

Step 5.8: Workflow: AI review after CI passes

Step 5.9: Workflow: `/promote dev` comment → dev tag

Step 5.10: Workflow: notify on approval

Step 5.11: Configure Project automations (the human side)

6. The Copilot loop in detail

7. Optional: structured input via Issue Forms

8. Things that are deliberately not in scope

9. Open decisions to make

10. The broader GitHub AI automation landscape

A. Native integrations worth enabling

A.1. GitHub Copilot code review (Turn on)

A.2. CodeQL + Copilot Autofix (Turn on)

A.3. Dependabot (already on)

A.4. Secret scanning + push protection (Turn on)

A.5. Project built-in workflows (Turn on)

B. New surface area for AI-driven workflows

B.1. Agentic Workflows (`gh-aw`) (Consider: technical preview)

B.2. GitHub Copilot Spaces (Consider)

B.3. MCP servers (Model Context Protocol) (Consider for advanced flows)

B.4. GitHub Spark (Watch)

C. Things to enforce in the repo’s structure

11. Sources