Skip to content
UXClaim
Design Ops

Architect Playbook

Self-improving Claude Code audit skills for TypeScript/React codebases covering architecture, security, accessibility, performance, testing, and more.

View source More in Design Ops

What it does

Architect Playbook is a collection of Claude Code slash-command skills that systematically audit TypeScript and React codebases across nine dimensions: security, accessibility, performance, architecture, testing, quality gates, linting, dependencies, and React patterns.

How it works

Install the playbook once globally or locally, then run audits in parallel from separate chat sessions. Each audit:

  • Grades against opinionated baselines, not just what’s in your codebase
  • Reports findings, then asks before generating implementation plans
  • Saves structured findings (markdown + JSON) to disk for cross-session review
  • Supports optional enrichment flags (--with-lighthouse-results, --with-network) for deeper analysis

When you find gaps during review, /system-self-improve patches the originating audit skill itself, making the playbook smarter over time.

Use cases

  • Onboarding to new projects: Walk onto a codebase and run all audits in parallel worktrees
  • Architecture reviews: Validate module boundaries, coupling, and design patterns
  • Security gates: Scan for auth flaws, XSS, secrets, and header misconfigurations
  • Accessibility compliance: Check WCAG 2.2 AA across components and the shell
  • CI/CD integration: Evolve audit quality based on real review feedback

Who benefits

Engineering teams, tech leads, and architects who want repeatable, evolving code review workflows without manual checklist fatigue.

Frequently asked questions

How do I install Architect Playbook?
Clone the repository, open it in Claude Code, then run `/install-architect-playbook-globally` (or `/install-architect-playbook-locally` to pin it to a single project). That's it—all audit commands are now available in every session.
Can I run audits in parallel?
Yes. Open multiple Claude Code chats, then use `/worktree <audit-name>` in each to run audits against isolated Git worktrees simultaneously. This prevents interference between long-running audits.
What happens after an audit finds issues?
The audit generates a concise Top 5 recommendations plus a full report saved to `.architect-audits/`. You fix the issues in the same chat, re-run the audit in a fresh chat to review, then optionally run `/system-self-improve` to patch the audit skill if gaps surface.
What audits are included?
Nine audits: security, accessibility, performance, architecture, testing, react patterns, linting, dependencies, and quality gates. Each supports standard `--learn` teaching mode, plus optional enrichment flags like `--with-network` or `--with-lighthouse-results`.
How does the self-improvement workflow work?
`/system-self-improve` reads a review's gap report and proposes edits to the originating audit's skill definition. Merge the patch, commit it, and the playbook evolves with your codebase's learnings.
Are audits read-only?
By default, yes. Every audit is static analysis and read-only. Runtime or network data is opt-in via explicit flags like `--with-scan` or `--with-network`.
What format are findings saved in?
Four files: `findings.md` (human-readable), `findings.json` (machine-readable issues list), `snapshot.md` (diagnostic snapshot), and `metadata.json` (skill version, timestamp, repo hash).
Can I customize audit thresholds?
Yes. Each audit supports per-audit `--threshold-*` flags documented in its `SKILL.md`. Use these to adjust severity filters or baseline expectations for your team's standards.

Glossary

Worktree
An isolated Git working directory created from your codebase. Audits run in worktrees to prevent interference when executing multiple audits in parallel.
Opinionated baseline
A specific, well-defined standard against which each audit grades code. The baseline is the team's or industry standard—not whatever happens to be in the current codebase.
Enrichment flag
Optional command-line flags like `--with-network` or `--with-lighthouse-results` that enable audits to pull live runtime data, security scanner output, or external tooling results beyond static analysis.
Findings contract
The deterministic on-disk structure (findings.md, findings.json, snapshot.md, metadata.json) that allows audits, fixes, and reviews to share state across separate chat sessions.
Top 5 recommendations
The highest-impact audit findings surfaced in the chat: violations and missing foundations, plus the most important partial gaps. The full report on disk contains all check statuses.

More in Design Ops

All →
Design Ops

Autonomous Development Pipeline

Claude Code skill turning specs into shipped code through adaptive phases with feedforward guides, feedback sensors, and requirement traceability.

0xPuncker
Design Ops

Ibras AI Agent

Claude Code marketplace for building and evaluating AI agents. Install plugins to generate complete Mastra evaluation systems with scorers, datasets, experim...

volfadar
Design Ops

Claude Skills

Production-grade Claude AI skills for stock analysis, prompt engineering, meeting documentation, and UX design with visual-first outputs.

bhrpraju
Design Ops

Propose

Run three parallel design agents with different philosophies to generate ranked approach proposals for any design decision.