convez.ai
Skill
varunk130

ai-workflow-playbooks

varunk130/ai-workflow-playbooks

Ver no GitHub
BomPluginScore · de 0 a 100

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-playbooks

1 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

Estrelas
2
Forks
0
Acompanhando
0
Saúde
85%
Último commit
há 1 semana
Versão
—
Issues abertas
1
Contribuidores
1

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

Playbooks Skills Guardians Runbooks License: MIT Built with Claude Code

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.

PlaybookPurpose
Discovery & IdeationStructured exploration of problem space and solution candidates
Specification AuthoringWrite a complete spec before any code is written

Stage 2: ARCHITECT

Design the system and decompose work.

PlaybookPurpose
Architecture & DecompositionBreak specs into ordered, verifiable work units

Stage 3: CONSTRUCT

Build the system incrementally with quality baked in.

PlaybookPurpose
Iterative ConstructionDeliver thin vertical slices with continuous integration
Test-First EngineeringRed-green-refactor with a disciplined test strategy
Context OrchestrationFeed agents the right context at the right moment
Interface CraftsmanshipBuild accessible, maintainable frontend systems
Contract-First APIsDesign APIs from the contract outward

Stage 4: HARDEN

Armor the system against threats and inefficiency.

PlaybookPurpose
Threat MitigationSystematic security hardening across all boundaries
Throughput TuningMeasure-first performance optimization

Stage 5: VALIDATE

Prove the system works and meets standards.

PlaybookPurpose
Runtime DiagnosticsBrowser and runtime verification using live instrumentation
Fault Isolation & RecoverySystematic debugging from reproduction to resolution
Peer Review ProtocolMulti-axis code review with clear severity and verdicts
Complexity ReductionSimplify code while preserving behavior

Stage 6: RELEASE

Ship with confidence and traceability.

PlaybookPurpose
Version Control DisciplineAtomic commits, trunk-based flow, clean history
Pipeline AutomationCI/CD with quality gates and fast feedback
Sunset & EvolutionManaged deprecation and migration paths
Knowledge CaptureADRs, API docs, and living documentation
Release OrchestrationStaged rollouts, feature flags, and go-live checklists

Stage 7: OPERATE

Monitor, learn, and improve after deployment.

PlaybookPurpose
Observability & OpsPost-deploy monitoring, alerting, and incident response

Cross-Cutting: Meta

PlaybookPurpose
Meta - How To UseThe 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.

SkillCapability
Codebase NavigationEfficiently explore, map, and understand unfamiliar codebases
Requirement ExtractionTransform vague inputs into structured, testable requirements
Safe RefactoringRestructure code without changing behavior, verified by tests
Dependency AssessmentEvaluate packages on maintenance, security, size, and licensing
Error InterpretationRead error messages and stack traces systematically
Context Window ManagementLoad the right information and omit the noise
Multi-Agent CollaborationCoordinate when multiple agents work on the same codebase
Human EscalationKnow when to stop and involve a human decision-maker
Incremental VerificationVerify work at every step, not just at the end
Production AwarenessThink 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.

AgentIntegration
CursorCopy into .cursor/rules/
GitHub CopilotAdd to .github/copilot-instructions.md
Gemini CLILoad as context files
WindsurfAdd to Windsurf rules

See the docs/ folder for platform-specific guides.

Guardians

Specialist review personas that bring focused expertise:

GuardianRoleUse When
Architecture GuardianPrincipal EngineerReviewing system design, API contracts, data flow
Quality GuardianQA LeadAssessing test coverage, test strategy, edge cases
Security GuardianAppSec EngineerAuditing auth, input handling, secrets, dependencies
Operations GuardianSRE LeadEvaluating deployability, observability, runbooks

Runbooks

Operational checklists loaded on demand:

RunbookCovers
Testing PatternsTest structure, mocking, component and E2E patterns
Security BaselineOWASP Top 10, auth, input validation, headers
Performance BaselineCore Web Vitals, frontend/backend optimization
Accessibility BaselineWCAG 2.1 AA, keyboard nav, screen readers
Incident ResponseTriage, communication, resolution, postmortem

Recommended Starting Set

If you're new, start with these:

  1. Meta - How To Use - Routes you to the right playbook for what you're doing
  2. Specification Authoring - Forces clear requirements before code
  3. Test-First Engineering - Ensures correctness through tests
  4. Peer Review Protocol - Catches issues before merge

Design Principles

  1. Workflows, not wikis - Each playbook is a step-by-step process, not a knowledge article
  2. Guardrails over guidelines - Exit criteria must be met with evidence, not promises
  3. Anti-pattern inoculation - Every playbook documents common shortcuts and why they fail
  4. Progressive loading - Core playbook stays focused; runbooks load only when needed
  5. Agent-agnostic - Plain Markdown works with any AI agent or IDE
  6. 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

Strategy & decisions

Go-to-market

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.

Ver o original no GitHub

Bom para

Relacionados