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. Validate a change — QA it like a curious human tester: check it does what it claims, then try to break what is around it
4. Extract knowledge from codebases into living documentation
5. Security test repositories against 17 focused security lenses
6. Audit design consistency across frontend codebases
7. Run campaigns — systematic large-scale refactoring across many files over multiple sessions
8. Triage on-call tickets — investigate incidents, propose fixes, and turn each resolution into durable runbooks
9. Run retrospectives — read recent agent threads, quantify recurring friction, apply the high-confidence fixes with a rollback, and approve the rest

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,code-review,on-call,validate,retro}

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>"
• "Validate <github PR URL | ticket>"
• "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>"
• "retro" (or "retro --days 7")

Layout

greybeard/
├── .claude-plugin/plugin.json   # Plugin manifest
├── hooks/hooks.json             # SessionStart hook: creates $GREYBEARD_DATA dirs
├── hooks/sync-skills-if-changed.sh  # Stop hook (user settings): re-runs skills/sync-local.sh when a SKILL.md changed
├── agents/                      # Custom subagents (canonical Claude Code frontmatter)
│   └── sync-local.sh            # Generates ~/.claude/agents + ~/.pi/agent/agents copies
├── skills/                      # One skill per workflow — auto-activates on its trigger words
│   └── <workflow>/SKILL.md      # Thin router → workflows/<workflow>/AGENTS.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
│   ├── implement/               # Ticket/requirements → TDD → review --fix → browser validation
│   ├── validate/                # QA: check the stated behavior, then explore around it
│   │   ├── pipeline/            # Check → charter → explore loop → confirm
│   │   ├── lenses/              # Exploratory heuristics (inputs, CRUD, states, timing, data, roles…)
│   │   ├── context/             # Per-app launch, logins, seed data, known quirks
│   │   └── templates/           # Report and run record
│   ├── 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
│   │   ├── context/             # Archetype-specific gotchas
│   │   └── 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
│   └── retro/                   # Retrospective over recent threads → quantified, ranked improvements
│       ├── lenses/              # What is measured: one file per kind of friction (extend by adding a file)
│       ├── pipeline/            # 5-phase gather → summarize → synthesize → report → apply
│       └── templates/           # Report, thread summary, state schema
├── 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)
    ├── code-review/{repo}/runs/        # plain review run records (one per review)
    ├── validate/{repo}/{run}/         # Validation runs: report, record, screenshots
    ├── on-call/                       # Runbooks (by repo/domain) + PHI-free audit logs
    └── retro/                         # Retro state, reports, changelog (or $RETRO_HOME → a private repo)

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. When the branch was already reviewed, it reviews only the commits since (2-round cap), unless they are a large share of the branch or touch migrations or config. 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, and validated code on a branch, with one list of decisions for you at the end.

implement <Linear issue | Jira ticket URL | ticket ID | GitHub issue URL | freeform requirements> [in <repo-name>] [--worktree [--base <branch>]] [--skip-ui] [--no-validate] [--pr]

How it works:

1. Intake the ticket and investigate the target repo's conventions and existing patterns; ask only what changes what gets built
2. Implement test-first, one behavior at a time — red, green, refactor
3. Commit once the changed files' tests are green
4. Code review, then validate, on that commit, with no fixes in between
5. One fix pass: safe review fixes, the bugs validate found (test-first), and the agent's own recommendation on every judgment call
6. A review of only those fixes, and a quick re-check of the criteria and the fixed bugs
7. One list: what changed, the decisions made on your behalf, what needs you, what wasn't built
8. For a Linear issue, attach an agent-summary.md to it: what was built, why, and the decisions made along the way

A stacked branch (--base) skips validate; validate the whole stack once from its top branch with validate --stack. Never pushes or opens a PR unless --pr is passed. See workflows/implement/ for details.

🔎 Validate

General-purpose QA, done the way a curious human tester would do it. Check the change does what it claims, then explore at and around it for what nobody specified.

validate <ticket | github PR URL | branch in repo | freeform> [--check-only] [--rounds N] [--url <base-url>]
validate --stack <top-branch> in <repo>

How it works:

1. Pick the interface: a browser for UI changes, HTTP for APIs, a local console for jobs and model rules
2. Map the change: where users meet it, the things it creates and changes, their states, everywhere its data shows up, what it depends on, and the rules it must never break
3. Check each stated criterion as real use, looking where the user would look next
4. Loop: a fresh session runs the top charters, then a debrief follows up on bugs and odd leads and reorders the backlog
5. Stop when the backlog is empty, a round finds nothing new, or the round cap hits; replay every finding before it is reported

Never touches production, never modifies code. See workflows/validate/ 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/AGENTS.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