Feature: Scheduled + on-demand repo health audit that auto-creates improvement issues

[oitray]

Summary

A GitHub Action that analyzes the blueprint repo as a whole — commands, personas, settings, MCP configs, workflows, docs — and automatically opens GitHub issues for identified efficiency and workflow improvements. Runs on a cron schedule and on demand via `workflow_dispatch`.

Teams that fork the blueprint inherit the audit workflow and can customize the prompts for their own conventions.

Motivation

As a blueprint repo grows (more commands, more personas, more MCP tools), drift accumulates: redundant patterns, missing cross-references, stale docs, gaps in error handling. A periodic audit surfaces these as actionable issues without requiring manual review.

Combined with the error-reporting hook (#2), this gives any team forking the blueprint two self-healing layers:

• Reactive (issue Feature: PostToolUse hooks for automatic error issue creation #2): errors at tool-use time → instant issue
• Proactive (this issue): scheduled analysis of the whole repo → improvement backlog

Proposed Design

Triggers

on:
  schedule:
    - cron: '0 9 * * 1'   # Every Monday 9am UTC (customize per team)
  workflow_dispatch:
    inputs:
      model:
        description: 'Claude model'
        default: 'claude-sonnet-4-6'
        type: choice
        options: [claude-sonnet-4-6, claude-opus-4-6]
      scope:
        description: 'Audit scope'
        default: 'full'
        type: choice
        options: [full, commands, personas, workflows, docs]

Analysis Scope

Area	What's analyzed
Commands	Overlapping intent, missing error paths, undocumented params
Personas	Routing gaps, inconsistent format rules, missing capabilities
Settings / hooks	Missing matchers, permission gaps, hook coverage
MCP configs	Orphaned servers, missing fallbacks, insecure patterns
GitHub Actions	Redundant jobs, missing failure handling, coverage gaps
Docs / README	Stale references, missing sections, broken cross-links

Deduplication

Searches open issues for semantic similarity before creating. Skips if match found. Uses [AUDIT] prefix on all generated issue titles.

Issue Format

## Finding
[Plain English description]

## Why it matters
[Impact on efficiency or workflow]

## Suggested fix
[Specific, actionable recommendation]

---
*Auto-generated by repo-audit workflow. Run: [link]*

Rate Limiting

Cap at 10 issues per run. Overflow batched into one summary issue.

Files to Create

• .github/workflows/repo-audit.yml — the action
• scripts/audit/analyze.py — Claude API call + issue creation logic
• scripts/audit/prompts/full-audit.md — system prompt for what "good" looks like
• scripts/audit/prompts/ — scoped prompts per area (commands, personas, etc.)

Secrets Required

• ANTHROPIC_API_KEY — add to repo secrets
• GITHUB_TOKEN — available in Actions context automatically

Customization for Forks

Teams that fork the blueprint:

1. Edit scripts/audit/prompts/ to reflect their own conventions
2. Adjust the cron schedule in repo-audit.yml
3. Add ANTHROPIC_API_KEY to their repo secrets

No other setup required.

Acceptance Criteria

• Action triggers on Monday 9am UTC cron and on workflow_dispatch
• workflow_dispatch accepts model and scope inputs
• Analyzes all areas in scope table
• Deduplicates against existing open issues
• Issues use [AUDIT] prefix and standard finding format
• Capped at 10 issues/run; overflow in summary issue
• Prompts are generic — no org-specific context
• Customization instructions in scripts/audit/README.md
• Cross-reference: error-reporting hook Feature: PostToolUse hooks for automatic error issue creation #2 (reactive layer)
• Cross-reference: OITApps/claude-config#24 (OIT implementation)