​

The AI-assisted pathway (implementation)

​

1. The flow

​

Stage labels: where each item is, at a glance

• Assignee: the issue’s assignee, carried onto the PR (github.event.issue.assignee.login); if the issue is unassigned, this falls back to the maintainer who applied path:ai-automation (github.actor). The assignee shepherds the PR, tests on dev, and approves.
• Final-merge reviewer: does the final human merge, pinged on approval by notify-approved; set with the REVIEWER_LOGIN repo variable (defaults to the repo owner).
• Requested PR reviewer(s): GitHub users requested for review on the plan PR, read from the linked issue’s optional Reviewer(s) form field by coco-plan-comment.yml; defaults to REVIEWER_LOGIN when the field is blank. This is distinct from the final-merge reviewer above, though both default to petrosrapto.

• The PR stays a draft through plan, implementation, and dev testing; marking it “Ready for review” is what triggers Coco’s automated review, and a human still does the final merge (the agents never do).
• Opening the plan PR triggers one CI run on the .coco/PLAN.md commit; the meaningful CI run happens on the implementation push, and the AI review happens later, when the PR is marked ready for review (or on demand with /review).
• gh-aw cannot comment on a PR it creates in the same run, so coco-plan-comment.yml is the small companion that posts the plan as the first comment.

​

2. One-time setup

​

2.1 Secrets (Settings → Secrets and variables → Actions → Secrets)

​

2.2 Variables (Settings → Secrets and variables → Actions → Variables)

​

2.3 Compile the agentic workflows

gh extension install github/gh-aw     # one time
gh aw compile --approve               # generates .github/workflows/ai-*-*.lock.yml (15 files)
git add .github/workflows .github/aw .github/dependabot.yml   # the wrappers, generated *.lock.yml, shared bodies, dependabot
git commit -m "build: compile AI-pathway agentic workflows"

​

2.4 Labels

​

2.5 Branch protection (the human gate)

​

2.6 Choosing the engine and model (Claude / Codex / Copilot)

# Copilot (default). Requires a Copilot seat (COPILOT_GITHUB_TOKEN, no API key).
# Uses max-continuations, not the Claude-only max-turns.
engine:
  id: copilot
  model: "${{ vars.AI_MODEL_COPILOT_<STAGE> || vars.AI_MODEL_COPILOT || 'claude-sonnet-4.6' }}"
  max-continuations: 15

# Claude (seat-free). max-turns is Claude-only.
engine:
  id: claude
  model: "${{ vars.AI_MODEL_CLAUDE_<STAGE> || vars.AI_MODEL_CLAUDE || vars.AI_MODEL || 'claude-opus-4-5' }}"  # <STAGE> = PLAN/IMPLEMENT/ITERATE/REVIEW
  max-turns: 40            # per stage: 30 plan / 80 implement / 60 iterate / 40 review
  env:
    ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}

# Codex / OpenAI (seat-free). No max-turns (Codex does not support it).
engine:
  id: codex
  model: "${{ vars.AI_MODEL_CODEX_<STAGE> || vars.AI_MODEL_CODEX || 'gpt-5.5' }}"
  env:
    OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}

​

3. Security model (the four guardrails)

1. Write-access only. roles: [admin, maintainer, write] on every agent, which is the gh-aw default. A non-collaborator cannot trigger any agent. The triggering gestures (path:ai-automation, /approve-plan, /promote dev) are maintainer actions, so the actor is always trusted; the issue/PR content, however, is still untrusted input the agent must treat with suspicion.
2. No secrets to forks. gh-aw blocks fork-originated triggers by default (repository-ID check), on top of GitHub’s standard rule that fork PRs get no secrets. push-to-pull-request-branch additionally refuses to push to forks.
3. Least privilege. The agent job runs read-only; all writes happen in separate, narrowly-scoped safe-output jobs. No agent has direct write access to the repo.
4. Human merge gate. ai-review posts COMMENT reviews only, never APPROVE, so an agent can never satisfy a required-approval rule. Merge is always a human action.

​

3.5 Threat-detection screen

​

4. Cost & billing

• AI tokens are billed per engine: the Claude engine bills ANTHROPIC_API_KEY, Codex bills OPENAI_API_KEY, and the default Copilot engine consumes the Copilot seat behind COPILOT_GITHUB_TOKEN (no API key), for every agent run.
• Actions minutes are billed to the repo owner regardless of who triggered the run, which is how a non-Copilot colleague’s trigger still runs “on your account”.
• Review cost is bounded: the automated review runs once, at the ready-for-review checkpoint, not on every /coco push, and it posts a single review (there is no separate summary comment). Use /review only when you want an extra pass. On the Claude engine, set AI_MODEL (or AI_MODEL_CLAUDE) to a Sonnet or Haiku ID to cut per-run cost further.