Self-Improvement GitHub Workflow

Automatically detect and fix UX issues in your codebase using recapt behavioral intelligence and GitHub Agentic Workflows.

Overview

The self-improvement workflow comes in two variants for GitHub Actions:

Full (with Workers)

Uses a multi-agent architecture for parallel execution:

Orchestrator checks PR statuses and evaluates deployed fixes
Orchestrator runs diagnostics to detect new UX issues
Orchestrator triages and dispatches fix-workers (one per issue)
Fix-workers run in parallel, each creating a focused PR for one issue
Orchestrator waits for workers and generates a summary

This architecture provides:

Parallel execution: Multiple issues fixed simultaneously
Focused PRs: Each PR addresses one specific issue (easier to review)
Fault isolation: One worker failing doesn't affect others

Lite (Single Agent)

Uses a single agent for simpler, more cost-effective execution:

Agent checks PR statuses and evaluates deployed fixes
Agent runs diagnostics to detect new UX issues
Agent triages and fixes issues sequentially
Agent creates one PR with all fixes

This architecture provides:

Lower cost: ~5x cheaper than the full variant
Simpler execution: No orchestration overhead
Single PR: All fixes in one place (easier to review as a batch)

Aspect	Full	Lite
Agent invocations	1 orchestrator + N workers	1 agent
PRs created	Up to N (one per issue)	1 (all fixes combined)
Parallelism	Yes	No
Cost per run	Higher	Lower
Best for	Large sites, many issues	Small sites, budget-conscious

Fix Lifecycle

Fixes are tracked through their complete lifecycle:

Status	Meaning
`proposed`	Fix implemented, no PR yet
`waiting`	PR open, awaiting human review/merge
`deployed`	PR merged to main
`evaluating`	Collecting post-deploy metrics
`succeeded`	Metrics improved - fix validated
`failed`	No improvement
`dismissed`	PR closed without merge

The orchestrator automatically:

Checks PR status for waiting fixes and updates to deployed or dismissed
Dispatches evaluate-workers for deployed fixes ready for evaluation (24h+ since deploy)

Quick Setup

The fastest way to set up the self-improvement workflow:

npx @recapt/cli setup-self-improvement-gh

This command will:

Let you choose your AI engine (Claude, GitHub Copilot, or Codex)
Let you choose the workflow variant (Full or Lite)
Install the self-improvement skill
Create the workflow file with your selected engine and variant
Compile the workflow
Guide you through adding the required GitHub secrets

Prerequisites

Before setting up the workflow, you need:

GitHub CLI - Install from cli.github.com
gh-aw extension - GitHub Agentic Workflows extension
```
gh extension install github/gh-aw
```
AI Engine API Key - One of the following as a GitHub secret:
- ANTHROPIC_API_KEY for Claude
- COPILOT_GITHUB_TOKEN for GitHub Copilot
- OPENAI_API_KEY for Codex
See the gh-aw authentication docs for details.
Recapt MCP Key - Get from dash.recapt.app/mcp
Repository Permissions - Enable GitHub Actions to create pull requests:
- Go to Settings → Actions → General
- Scroll to Workflow permissions
- Enable "Allow GitHub Actions to create and approve pull requests"

Manual Setup

If you prefer to set things up manually, follow these steps:

Step 1: Install the Self-Improvement Skill

npx @recapt/cli skill install self-improvement

This creates .agents/recapt/self-improvement.md which contains the workflow logic.

Step 2: Create the Workflow File

Choose one of the two variants:

Option A: Lite Variant (Recommended for most users)

Create .github/workflows/self-improvement-lite.md:

---
on:
  schedule: daily
  workflow_dispatch:
    inputs:
      branch:
        description: "Branch to analyze"
        default: "main"
      max_fixes:
        description: "Maximum issues to fix"
        default: "3"

engine: claude # or: copilot, codex

permissions:
  contents: read
  issues: read
  pull-requests: read

mcp-servers:
  recapt:
    command: npx
    args: ["@recapt/mcp@latest"]
    env:
      RECAPT_SECRET_KEY: "${{ secrets.RECAPT_SECRET_KEY }}"
    allowed: ["*"]

safe-outputs:
  create-pull-request:
    title-prefix: "[self-improvement] "
    labels: [automated, ux-fix]
    base-branch: main
    draft: true
    max: 1
---

## Self-Improvement (Lite)

You are a UX engineer using recapt behavioral intelligence to automatically detect and fix user friction points.

### Important: Autonomous Mode

You are running in a GitHub Actions sandbox with NO human interaction possible. You must:

- **Never wait for user input** - Make all decisions autonomously
- **Never ask questions** - Proceed with reasonable defaults
- **Complete all work in one run** - There is no "check back later"
- **Fix issues directly** - Do NOT dispatch workers, implement fixes yourself
- **Create one PR** - All fixes go into a single pull request

### Workflow

Follow the self-improvement workflow. The recapt MCP server is connected and provides all necessary tools.

### Output

Create a single pull request containing all fixes with clear descriptions.

Option B: Full Variant (For large sites with many issues)

Create .github/workflows/self-improvement-full.md:

---
on:
  schedule: daily
  workflow_dispatch:
    inputs:
      branch:
        description: "Branch to analyze"
        default: "main"
      max_fixes:
        description: "Maximum issues to fix"
        default: "5"

engine: claude # or: copilot, codex

permissions:
  contents: read
  issues: read
  pull-requests: read
  actions: read

mcp-servers:
  recapt:
    command: npx
    args: ["@recapt/mcp@latest"]
    env:
      RECAPT_SECRET_KEY: "${{ secrets.RECAPT_SECRET_KEY }}"
    allowed: ["*"]

safe-outputs:
  dispatch-workflow:
    workflows:
      - evaluate-worker
      - fix-worker
    max: 10
---

## Self-Improvement Orchestrator (Full)

You are the orchestrator for the self-improvement workflow with parallel workers.

### Important: Autonomous Mode

You are running in a GitHub Actions sandbox with NO human interaction possible. You must:

- **Never wait for user input** - Make all decisions autonomously
- **Never ask questions** - Proceed with reasonable defaults
- **Complete all work in one run** - There is no "check back later"
- **Dispatch workers for parallel execution** - Don't fix issues yourself

### Workflow

1. Check and update PR statuses for pending fixes
2. Dispatch evaluate-workers for deployed fixes ready for evaluation
3. Run diagnostics to find new issues
4. Triage and select issues to fix
5. Dispatch fix-workers for each selected issue
6. Wait for all workers to complete
7. Generate a summary and complete the improvement run

Step 3: Compile the Workflow

gh aw compile

This generates the corresponding .lock.yml file:

self-improvement-lite.lock.yml for the lite variant
self-improvement-full.lock.yml for the full variant

Step 4: Add GitHub Secrets

You need two secrets:

AI Engine Secret (one of):
- ANTHROPIC_API_KEY if using engine: claude
- COPILOT_GITHUB_TOKEN if using engine: copilot
- OPENAI_API_KEY if using engine: codex
Recapt Secret:
- Name: RECAPT_SECRET_KEY
- Value: Your recapt MCP key (get it from dash.recapt.app/mcp)

To add secrets:

Go to your repository on GitHub
Navigate to Settings → Secrets and variables → Actions
Click New repository secret for each

Step 5: Commit and Push

git add .
git commit -m "Add recapt self-improvement workflow"
git push

Running the Workflow

Manual Trigger

For the lite variant:

gh aw run self-improvement-lite

For the full variant:

gh aw run self-improvement-full

Or from the GitHub Actions UI, go to Actions → select your workflow → Run workflow.

Scheduled Runs

By default, the workflow runs daily (GitHub distributes the exact time to reduce load spikes). You can use a specific cron schedule instead:

on:
  schedule:
    - cron: "0 9 * * 1-5" # 9 AM UTC, weekdays only

How It Works

Lite Variant

┌─────────────────────────────────────────────────────────────────┐
│                      Single Agent                                │
│                                                                 │
│  1. Start improvement run                                       │
│  2. Check PR status for waiting fixes → deployed/dismissed      │
│  3. Evaluate deployed fixes                                     │
│  4. Run diagnostics → find issues                               │
│  5. Triage → select issues to fix                               │
│  6. Fix issues sequentially                                     │
│  7. Create single PR with all fixes                             │
│  8. Complete run                                                │
└─────────────────────────────────────────────────────────────────┘

Full Variant

┌─────────────────────────────────────────────────────────────────┐
│                     Orchestrator Agent                          │
│                                                                 │
│  1. Start improvement run                                       │
│  2. Check PR status for waiting fixes → deployed/dismissed      │
│  3. Dispatch evaluate-workers for deployed fixes                │
│  4. Run diagnostics → find issues                               │
│  5. Triage → select issues to fix                               │
│  6. Dispatch fix-workers (parallel)                             │
│  7. Wait for all workers                                        │
│  8. Generate summary and complete run                           │
└─────────────────────────────────────────────────────────────────┘
         │                              │
         ▼                              ▼
┌─────────────────┐          ┌─────────────────┐
│ evaluate-worker │          │   fix-worker    │
│                 │          │                 │
│ • Fetch metrics │          │ • Investigate   │
│ • Compare to    │          │ • Implement fix │
│   baseline      │          │ • Create PR     │
│ • Update status │          │ • Record action │
│ • Record lessons│          │ • Track fix     │
└─────────────────┘          └─────────────────┘

Trigger: The workflow runs on schedule or manual dispatch
Orchestrator Start: Creates an improvement run to track progress
PR Status Check: Updates waiting fixes based on PR merge/close status
Evaluation: Evaluates deployed fixes (inline for lite, workers for full)
Diagnostics: Runs run_full_diagnostic to find current issues
Triage: Selects high-confidence, actionable issues to fix
Fix: Implements fixes (sequential for lite, parallel workers for full)
PR Creation: Creates PR(s) with the fixes
Complete: Generates title and summary

Security

Read-only by default: The agent runs with read-only GitHub permissions
Draft PRs: All PRs are created as drafts requiring manual review before merge
Sandboxed execution: Agent runs in an isolated container with network firewall
Secret isolation: RECAPT_SECRET_KEY is only passed to the MCP server process

Customization

Change AI Engine

Edit the engine field in your workflow file (e.g., .github/workflows/self-improvement-lite.md):

engine: copilot # Options: claude, copilot, codex

Remember to add the corresponding API key secret for your chosen engine.

Change Schedule

Edit the schedule field in your workflow file. Use fuzzy schedules or specific cron:

on:
  schedule: weekly # Options: hourly, daily, weekly, monthly
  # Or use cron for specific times:
  # schedule:
  #   - cron: "0 9 * * 1-5"  # 9 AM UTC, weekdays only

Change PR Labels

Modify the safe-outputs section:

safe-outputs:
  create-pull-request:
    title-prefix: "[auto-fix] "
    labels: [bot, ux-improvement]

Troubleshooting

"GitHub Actions is not permitted to create or approve pull requests"

This error means you need to enable PR creation permissions:

Go to your repository on GitHub
Navigate to Settings → Actions → General
Scroll down to Workflow permissions
Enable "Allow GitHub Actions to create and approve pull requests"
Click Save

Workflow Not Running

Check that both secrets are set: your AI engine secret and RECAPT_SECRET_KEY
Verify the workflow file compiled successfully (gh aw compile)
Check GitHub Actions is enabled for your repository

No Issues Found

Ensure you have session data in recapt (check your dashboard)
The workflow only finds issues with sufficient behavioral evidence

Fixes Not Working

Review the PR carefully before merging
Check the agent's reasoning in the PR description
Use evaluate_fix to track fix effectiveness over time

Overview​

Full (with Workers)​

Lite (Single Agent)​

Fix Lifecycle​

Quick Setup​

Prerequisites​

Manual Setup​

Step 1: Install the Self-Improvement Skill​

Step 2: Create the Workflow File​

Option A: Lite Variant (Recommended for most users)​

Option B: Full Variant (For large sites with many issues)​

Step 3: Compile the Workflow​

Step 4: Add GitHub Secrets​

Step 5: Commit and Push​

Running the Workflow​

Manual Trigger​

Scheduled Runs​

How It Works​

Lite Variant​

Full Variant​

Security​

Customization​

Change AI Engine​

Change Schedule​

Change PR Labels​

Troubleshooting​

"GitHub Actions is not permitted to create or approve pull requests"​

Workflow Not Running​

No Issues Found​

Fixes Not Working​