Greybeard

AI-powered workflows centered around code. Installable as a Claude Code plugin.

What is this?

Greybeard is a collection of structured AI agent workflows that help you:

1. Review code against technical best practices and team-specific context
2. Implement tickets — requirements in, a test-first, reviewed, browser-checked branch out
3. Extract knowledge from codebases into living documentation
4. Security test repositories against 17 focused security lenses
5. Audit design consistency across frontend codebases
6. Run campaigns — systematic large-scale refactoring across many files over multiple sessions
7. Triage on-call tickets — investigate incidents, propose fixes, and turn each resolution into durable runbooks

Each workflow is a set of prompts and templates that guide AI agents through multi-stage analysis.

Install

Install the plugin, then set up the data directory.

1. Install the plugin

This repo is its own marketplace (.claude-plugin/marketplace.json). Add it as a marketplace, then install:

/plugin marketplace add casconed/greybeard
/plugin install greybeard@greybeard

Or, for a local clone you're developing against, add it by path instead of by GitHub repo:

/plugin marketplace add /path/to/greybeard
/plugin install greybeard@greybeard

2. Set up the data directory

Greybeard keeps cloned repos and workflow output outside the plugin, at $GREYBEARD_DATA/ (defaults to ~/.greybeard-data/). Set GREYBEARD_DATA to relocate it. The data directory is created automatically on the first session after install (a SessionStart hook runs mkdir -p idempotently), so this step is optional — run it manually only if you want to populate sources/ before launching Claude:

mkdir -p "${GREYBEARD_DATA:-$HOME/.greybeard-data}/sources" "${GREYBEARD_DATA:-$HOME/.greybeard-data}/output"/{knowledge-extraction,security-testing,design-audit,campaigns,on-call}

3. Add your repositories

Clone the repos you want to analyze into the data directory:

git clone https://github.com/your-org/your-repo.git "${GREYBEARD_DATA:-$HOME/.greybeard-data}/sources/your-repo"

4. Customize context (optional)

Add team-specific review criteria to workflows/code-review/context/:

• GOTCHYAS.md — Known pitfalls
• NITS.md — Style preferences

5. Run

Then ask Claude to run a workflow (the leading word routes it):

• "Review <github PR URL>"
• "Extract knowledge from my-repo"
• "Pen test my-repo"
• "Design audit my-repo"
• "Campaign plan 'convert all JS to TypeScript' in my-repo"
• "Triage <Jira ticket URL>"

Layout

greybeard/
├── .claude-plugin/plugin.json   # Plugin manifest
├── skills/                      # One skill per workflow — auto-activates on its trigger words
│   └── <workflow>/SKILL.md      # Thin router → workflows/<workflow>/CLAUDE.md
├── workflows/                   # Shared instruction tree (lenses, pipelines, templates, context)
│   ├── code-review/             # Technical code review pipeline
│   │   ├── lenses/              # General technical criteria
│   │   ├── context/             # Team/repo-specific criteria
│   │   └── templates/           # Canonical report format
│   ├── review-fix/              # Loop-based auto-fix on top of code review
│   │   ├── pipeline/            # 3-phase triage → fix → gate loop
│   │   └── templates/           # Fix-run audit record format
│   ├── knowledge-extraction/    # Business logic documentation pipeline
│   │   ├── pipeline/            # 5-phase extraction process
│   │   └── templates/           # Output templates
│   ├── security-testing/        # Security vulnerability scanning
│   │   ├── pipeline/            # 3-phase scan process
│   │   ├── lenses/              # 17 security-focused lenses
│   │   └── templates/           # Output templates
│   ├── design-audit/            # Frontend design consistency assessment
│   │   ├── pipeline/            # 4-phase audit process
│   │   ├── lenses/              # Design dimension criteria
│   │   └── templates/           # Output templates
│   ├── campaign/                # Large-scale refactoring campaign execution
│   │   └── pipeline/            # 6-phase plan → execute → review cycle
│   └── on-call/                 # On-call ticket triage + self-improving runbooks
│       ├── pipeline/            # 5-phase triage → publish → capture → curate → sync
│       ├── context/             # Authoring standard + escalation map
│       └── templates/           # Runbook, audit, and index templates
├── sources/                     # Repo relationship docs
└── sketches/                    # Drafts and ideas

Private data lives outside the plugin:

$GREYBEARD_DATA/                       # default ~/.greybeard-data/
├── sources/                           # Cloned repositories
│   └── {repo}/
└── output/                            # Workflow output
    ├── knowledge-extraction/{repo}/
    ├── security-testing/{repo}/
    ├── design-audit/{repo}/
    ├── campaigns/{repo}/{campaign}/
    ├── code-review/{repo}/fix-runs/    # review-fix audit records (one per run)
    └── on-call/                       # Runbooks (by repo/domain) + PHI-free audit logs

Workflows

⚙️ Code Review

Multi-stage review that evaluates code changes against:

• Lenses: General technical patterns (security, performance, React, TypeScript, etc.)
• Context: Team-specific gotchas and conventions

review <github PR URL>

(also accepts review <branch-name> in <repo-name> when there's no PR yet)

How it works:

1. Resolve the PR URL to a repo + branch (or use the given branch), then diff against origin/main
2. Evaluate in parallel against each lens
3. Evaluate against team context
4. Fact-check findings against the actual codebase
5. Output an impact-first report: a pass/fail/nit tally, numbered failures with a one-sentence fix, then the nits as one line each

Auto-fix mode (review --fix): instead of stopping at a report, classifies findings, auto-applies the safe ones, commits them separately from the author's original commits, and re-reviews with a fresh pass — looping (bounded) until nothing auto-fixable remains or a 3-round cap is hit. Never pushes; only runs on a branch you own. See workflows/review-fix/.

Interactive mode (review --interactive): prints the report, then walks failures 1-by-1 — drafting a PR review comment in your voice (concise, question-framed, user-impact focused), revising on feedback, and posting inline to GitHub only after approval. Skips pre-existing findings; nits skipped by default.

See workflows/code-review/ for details.

🛠️ Implement

Takes a ticket or a set of requirements and turns it into working, tested, reviewed code on a branch.

implement <Jira ticket URL | ticket ID | GitHub issue URL | freeform requirements> [in <repo-name>]

How it works:

1. Intake the ticket and investigate the target repo's conventions and existing patterns
2. Implement test-first, one behavior at a time — red, green, refactor
3. Commit once the whole suite is green
4. Run review --fix against the branch, then apply any remaining in-scope corrections in a separate commit
5. When the change has a UI, drive it in a real browser against the acceptance criteria

Never pushes, never opens a PR. See workflows/implement/ for details.

📓 Knowledge Extraction

Extract business logic from code into structured documentation. Produces:

• Domain records: Documented business rules with confidence levels
• Ubiquitous language: Glossary of domain terms
• Open questions: Gaps requiring SME review

5-phase pipeline:

1. Crawl → Structural map
2. Extract → Business rules
3. Research → Evidence gathering
4. Interrogate → Gap analysis
5. Synthesize → Final knowledge base

See workflows/knowledge-extraction/ for details.

🔐 Security Testing

Scan entire repositories for security vulnerabilities. Produces a prioritized report ranked by severity.

pen test <repo-name>

How it works:

1. Segment the repo into parallelizable scan units
2. Scan each segment against applicable security lenses in parallel
3. Consolidate, deduplicate, fact-check, and rank all findings
4. Output a prioritized security report (Critical/High/Medium/Low)

Supports incremental catch-up:

catch up security for <repo-name>

See workflows/security-testing/ for details.

👓 Design Audit

Scan frontend repositories for design consistency and produce a living design specification.

design audit <repo-name>

How it works:

1. Inventory all design metrics from source code (colors, typography, spacing, layout, components)
2. Capture screenshots at mobile/tablet/desktop viewports via Playwright
3. Analyze inventory + screenshots against design lenses
4. Synthesize a living design specification documenting tokens, patterns, and conventions

Supports incremental catch-up:

catch up design for <repo-name>

See workflows/design-audit/ for details.

🗂️ Campaign

Execute large-scale, systematic refactoring campaigns across many files over multiple sessions. The human defines the goal; the pipeline writes the recipe, tracks progress, and makes the changes in reviewable batches.

campaign plan <goal> in <repo-name>

How it works:

1. Interpret the goal and write a recipe with done criteria (Planner, Opus)
2. Inventory all in-scope items and assess current status in parallel (Inventorier, Sonnet)
3. Group into prioritized batches (Coordinator, Opus)
4. Execute the batch — one commit per item (Executor, Sonnet, parallel)
5. Verify each item against done criteria (Verifier, Sonnet, parallel)
6. First-pass code review, auto-fix, summarize for human (Reviewer, Opus)
7. Human reviews and merges the batch branch, then continue

Continue an in-progress campaign:

campaign continue <campaign-name> in <repo-name>

Check progress without making changes:

campaign status <campaign-name> in <repo-name>

See workflows/campaign/ for details on execution modes (autonomous vs. guided) and DDD campaign integration.

📟 On-Call

Triage engineering on-call (ER) tickets and turn each resolution into durable knowledge — a hierarchy of short, self-contained runbooks plus a PHI-free audit trail. Spans origami_claims, care_platform, and sana_mobile. This is the canonical, cross-repo home for on-call knowledge; the /oncall slash commands inside origami_claims are separate and left as-is.

triage <Jira ticket URL>

How it works:

1. Gather the ticket, classify it (ops change / investigation / bug), match a runbook, and investigate the code
2. Confirm the root-cause hypothesis with read-only snippets before proposing any data change — the engineer runs them and reports back (one at a time when they chain; complete, ready-to-paste snippets)
3. Propose a fix — a self-service redirect where possible, otherwise a specific, confirmed change
4. Publish the reviewed analysis back to the ticket (confirmation-gated)
5. Capture a PHI-free audit entry, create/update runbooks, and log any surfaced code bugs to the On-call bugs Linear project
6. Curate the corpus over time, and at end of shift sync the runbooks into the app repo via a branch + PR

Five verbs: triage, on-call publish, on-call capture, on-call curate, on-call sync.

Runbooks and audit logs are the source of truth in $GREYBEARD_DATA/output/on-call/ — PHI/PII-free (the JIRA ticket ID is the pointer to real identifiers). Needs the atlassian (JIRA) MCP, declared in the plugin's .mcp.json.

See workflows/on-call/ for details.

Adding Workflows

New workflows go in workflows/{workflow-name}/ with a matching skills/{workflow-name}/SKILL.md entry point. See workflows/CLAUDE.md for conventions.

Lenses Included

Category	Lenses
Security	Auth, PHI/HIPAA
React	Hooks, Performance, State
TypeScript	Type Safety, Defensive Code
Data	N+1 Queries, Migrations, Idempotency
Architecture	Separation of Concerns, Extensibility, Clarity
Infrastructure	Cron, Jobs, WebSockets
Compatibility	API Breaking Changes, Browser, CORS, Client-Server Contracts
Quality	Testing, Accessibility

License

MIT