ai-workflow-playbooks
varunk130/ai-workflow-playbooks
Production-grade operational playbooks for AI coding agents across the full software delivery pipeline. 21 playbooks, 10 agent skills, 4 specialist guardians, 5 operational runbooks — from discovery through operations.
Instalação
npx convez-ai varunk130/ai-workflow-playbooks1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
README
A tradução para o português deste README ainda está na fila.
🛠 AI Workflow Playbooks
Production-grade operational playbooks for AI coding agents across the full software delivery pipeline
Maintained by Varun Kulkarni · Quick Start ↓ · Pipeline Stages ↓ · Contributing
AI agents are powerful — but without structured guardrails, they cut corners: skipping specifications, ignoring edge cases, bypassing security reviews, and shipping untested code. These playbooks encode the operational discipline of seasoned engineering teams into repeatable, verifiable workflows that any AI agent can follow consistently.
⚡ TL;DR - Get Started in 60 Seconds
git clone https://github.com/varunk130/ai-workflow-playbooks.git
claude --plugin-dir /path/to/ai-workflow-playbooks
# Then in Claude Code, run any pipeline command:
# /discover /architect /construct /harden /validate /release /operate
Full setup, Cursor/Copilot/Gemini/Windsurf integration, and per-stage details: see ⚡ Quick Start below.
The Problem
When AI agents work without guardrails:
- Requirements get assumed, not documented
- Tests are an afterthought — or absent entirely
- Security surfaces go unexamined
- Code ships without review, monitoring, or rollback plans
- Technical debt compounds silently
The Solution
This repository provides 21 production playbooks, 10 agent skills, 4 specialist guardians, and 5 operational runbooks organized across a 7-stage delivery pipeline. Each playbook is a structured, executable workflow — not a reference document. Agents follow steps, produce artifacts, and meet exit criteria before proceeding.
The Pipeline
flowchart LR
A["🔎 DISCOVER<br/>Ideate · Scope"] --> B["📐 ARCHITECT<br/>Design · Plan"]
B --> C["🛠 CONSTRUCT<br/>Build · Wire"]
C --> D["🛡 HARDEN<br/>Armor · Guard"]
D --> E["✅ VALIDATE<br/>Prove · Gate"]
E --> F["🚀 RELEASE<br/>Ship · Deploy"]
F --> G["📡 OPERATE<br/>Watch · Learn"]
classDef stage fill:#1a73e8,color:#fff,stroke:#1558b0,stroke-width:2px,rx:8,ry:8
classDef gate fill:#ea8600,color:#fff,stroke:#c57200,stroke-width:2px,rx:8,ry:8
class A,B,C,F,G stage
class D,E gate
🛡 Stages HARDEN and VALIDATE are gating reviews — a guardian must sign off before the agent proceeds.
Stage 1: DISCOVER
Define and refine what you're building.
| Playbook | Purpose |
|---|---|
| Discovery & Ideation | Structured exploration of problem space and solution candidates |
| Specification Authoring | Write a complete spec before any code is written |
Stage 2: ARCHITECT
Design the system and decompose work.
| Playbook | Purpose |
|---|---|
| Architecture & Decomposition | Break specs into ordered, verifiable work units |
Stage 3: CONSTRUCT
Build the system incrementally with quality baked in.
| Playbook | Purpose |
|---|---|
| Iterative Construction | Deliver thin vertical slices with continuous integration |
| Test-First Engineering | Red-green-refactor with a disciplined test strategy |
| Context Orchestration | Feed agents the right context at the right moment |
| Interface Craftsmanship | Build accessible, maintainable frontend systems |
| Contract-First APIs | Design APIs from the contract outward |
Stage 4: HARDEN
Armor the system against threats and inefficiency.
| Playbook | Purpose |
|---|---|
| Threat Mitigation | Systematic security hardening across all boundaries |
| Throughput Tuning | Measure-first performance optimization |
Stage 5: VALIDATE
Prove the system works and meets standards.
| Playbook | Purpose |
|---|---|
| Runtime Diagnostics | Browser and runtime verification using live instrumentation |
| Fault Isolation & Recovery | Systematic debugging from reproduction to resolution |
| Peer Review Protocol | Multi-axis code review with clear severity and verdicts |
| Complexity Reduction | Simplify code while preserving behavior |
Stage 6: RELEASE
Ship with confidence and traceability.
| Playbook | Purpose |
|---|---|
| Version Control Discipline | Atomic commits, trunk-based flow, clean history |
| Pipeline Automation | CI/CD with quality gates and fast feedback |
| Sunset & Evolution | Managed deprecation and migration paths |
| Knowledge Capture | ADRs, API docs, and living documentation |
| Release Orchestration | Staged rollouts, feature flags, and go-live checklists |
Stage 7: OPERATE
Monitor, learn, and improve after deployment.
| Playbook | Purpose |
|---|---|
| Observability & Ops | Post-deploy monitoring, alerting, and incident response |
Cross-Cutting: Meta
| Playbook | Purpose |
|---|---|
| Meta - How To Use | The onboarding playbook: pick the right playbook for the task and stage you're in |
ℹ️ New here? Start with the Meta - How To Use playbook - it's the entry point that routes you to the right stage.
Agent Skills
Skills are persistent competency profiles that define how AI agents behave across all pipeline stages. Unlike playbooks (which are step-by-step workflows), skills are capabilities agents carry throughout a session.
| Skill | Capability |
|---|---|
| Codebase Navigation | Efficiently explore, map, and understand unfamiliar codebases |
| Requirement Extraction | Transform vague inputs into structured, testable requirements |
| Safe Refactoring | Restructure code without changing behavior, verified by tests |
| Dependency Assessment | Evaluate packages on maintenance, security, size, and licensing |
| Error Interpretation | Read error messages and stack traces systematically |
| Context Window Management | Load the right information and omit the noise |
| Multi-Agent Collaboration | Coordinate when multiple agents work on the same codebase |
| Human Escalation | Know when to stop and involve a human decision-maker |
| Incremental Verification | Verify work at every step, not just at the end |
| Production Awareness | Think about production consequences while writing code |
⚡ Quick Start
With Claude Code (Recommended)
# Clone and reference as a plugin directory
git clone https://github.com/varunk130/ai-workflow-playbooks.git
claude --plugin-dir /path/to/ai-workflow-playbooks
Then use pipeline commands:
/discover → Explore and scope the problem
/architect → Plan the system and decompose tasks
/construct → Build incrementally with tests
/harden → Run security and performance checks
/validate → Diagnose, debug, and review code before shipping
/release → Ship with confidence
/operate → Set up monitoring and observability
With Other AI Agents
Playbooks are plain Markdown. Copy the relevant PLAYBOOK.md files into your agent's system prompt, rules directory, or context window.
| Agent | Integration |
|---|---|
| Cursor | Copy into .cursor/rules/ |
| GitHub Copilot | Add to .github/copilot-instructions.md |
| Gemini CLI | Load as context files |
| Windsurf | Add to Windsurf rules |
See the docs/ folder for platform-specific guides.
Guardians
Specialist review personas that bring focused expertise:
| Guardian | Role | Use When |
|---|---|---|
| Architecture Guardian | Principal Engineer | Reviewing system design, API contracts, data flow |
| Quality Guardian | QA Lead | Assessing test coverage, test strategy, edge cases |
| Security Guardian | AppSec Engineer | Auditing auth, input handling, secrets, dependencies |
| Operations Guardian | SRE Lead | Evaluating deployability, observability, runbooks |
Runbooks
Operational checklists loaded on demand:
| Runbook | Covers |
|---|---|
| Testing Patterns | Test structure, mocking, component and E2E patterns |
| Security Baseline | OWASP Top 10, auth, input validation, headers |
| Performance Baseline | Core Web Vitals, frontend/backend optimization |
| Accessibility Baseline | WCAG 2.1 AA, keyboard nav, screen readers |
| Incident Response | Triage, communication, resolution, postmortem |
Recommended Starting Set
If you're new, start with these:
- Meta - How To Use - Routes you to the right playbook for what you're doing
- Specification Authoring - Forces clear requirements before code
- Test-First Engineering - Ensures correctness through tests
- Peer Review Protocol - Catches issues before merge
Design Principles
- Workflows, not wikis - Each playbook is a step-by-step process, not a knowledge article
- Guardrails over guidelines - Exit criteria must be met with evidence, not promises
- Anti-pattern inoculation - Every playbook documents common shortcuts and why they fail
- Progressive loading - Core playbook stays focused; runbooks load only when needed
- Agent-agnostic - Plain Markdown works with any AI agent or IDE
- Production-first - The pipeline extends through deployment into operations
Contributing
See CONTRIBUTING.md for guidelines on writing new playbooks or improving existing ones.
Related Work
Part of a portfolio of AI agent and skill libraries for product, GTM, and decision-making teams.
Discovery & research
- ai-customer-discovery-skills - Turn raw customer signal into validated product opportunities (12 skills planned)
- jtbd-extractor - Extract Jobs-to-be-Done statements from research, with opportunity scoring
Strategy & decisions
- claude-code-skills - 29 production-grade skills for finance, product, strategy, and game theory
- AI-Builder-Decision-Analyst - 11 skills that catch bad bets before you ship across DECIDE / BUILD / COMMUNICATE / LEARN
Go-to-market
- ai-gtm-skill-library - 31 opinionated GTM skills across the full discover -> renew lifecycle
- ai-marketing-claude-skills - 12 marketing-ops skills with scoring algorithms and statistical frameworks
- ai-partner-ecosystem-analysis - Deep research on any ISV, partner, or competitor with a 1-slide PPTX output
UX & design
- ai-ux-skill-library - 12 frameworks for designing UX for AI products, agents, and AI-powered experiences
Multi-agent demos
- ai-pm-agents-suite - 6-agent pipeline plus 3 standalone PM agents (decision engine, financial analyst, stakeholder translator) that turn customer feedback into strategy, PRDs, and comms
- ai-legal-agents-skills-os - Agentic operating system for legal work: one master agent, nine specialist skills, MCP + MCP Apps
Evaluation & operations
- AI-Eval-Skills - 6 skills to plan, generate, run, interpret, and triage AI agent evaluations
License
MIT — see LICENSE for details.
Built by Varun Kulkarni — part of a portfolio of AI agent systems for product teams.