Version: 0.2.0
A team collaboration guide for AI-assisted development that prevents massive PRs through structured planning.
When teams use AI agents (Claude Code, Cursor, Cline, Bolt) for "vibe coding," the PRs get massive. A single feature request can generate 5,000+ lines of changes that are impossible to review effectively. This creates:
- Review bottlenecks - No one wants to review a 10k line PR
- Hidden bugs - Large diffs hide issues in the noise
- Merge conflicts - Big PRs sit open longer, increasing conflict risk
- Knowledge silos - Reviewers skim instead of understanding
When using AI agents for development, you need a strategy to prevent massive, unreviewable PRs. This repo presents two complementary approaches:
- Choose Solution 1 (Spec Kit) if you want automated guardrails built into your AI coding workflow.
- Choose Solution 2 (Manual Templates) if you prefer human-driven planning with more explicit control.
Both solutions aim for the same outcome: small, reviewable PRs in the 200-400 line range.
| Aspect | Solution 1: Spec Kit | Solution 2: Manual Templates |
|---|---|---|
| Approach | Automated spec-driven development with slash commands | Human-driven planning with templates and documentation |
| Setup Complexity | Medium - requires CLI installation and project initialization | Low - copy templates and start using |
| Automation Level | High - AI agent executes commands that generate specs, plans, and tasks | Low - humans write PRDs, specs, and create tickets manually |
| Best For | Teams using AI agents extensively; greenfield projects; developers wanting guardrails built into tooling | Teams preferring manual control; existing projects; organizations with established planning processes |
| Pros | - Automated task generation - Built-in workflow guardrails - Consistent structure across projects - Works with multiple AI agents |
- Full human control over planning - No external dependencies - Easy to customize for your team - Familiar documentation-based workflow |
| Cons | - Requires tooling setup - Learning curve for commands - May feel opinionated |
- More manual effort required - Relies on team discipline - No automated enforcement |
| Learning Curve | Moderate - need to learn slash commands and workflow | Low - familiar documentation and planning process |
Spec Kit is GitHub's open-source toolkit that automates the spec-to-code workflow using AI agent commands.
What it does:
- Provides slash commands (
/speckit.specify,/speckit.plan,/speckit.tasks,/speckit.implement) that guide AI agents through structured development - Automatically generates specifications, technical plans, and task breakdowns from natural language requirements
- Executes implementations in a controlled, step-by-step manner
- Works with Claude Code, Cursor, Copilot, Windsurf, and other AI coding agents
Quick start:
# Install Spec Kit
uv tool install specify-cli --from git+https://github.com/github/spec-kit.git
# Initialize your project
specify init my-project --ai claude
# In your AI agent, use these commands:
/speckit.constitution # Define project principles
/speckit.specify # Describe what to build (requirements)
/speckit.plan # Define tech stack and architecture
/speckit.tasks # Generate task breakdown
/speckit.implement # Execute tasks systematicallyBest for:
- Teams already using AI coding agents extensively
- Projects where AI agents do most of the implementation work
- Greenfield projects where you can establish the workflow from day one
- Developers who want automation and guardrails built into their AI tooling
Demo: See it in action at citadelgrad/restart-heroku
Learn more: Spec Kit Documentation
A human-driven process using templates and documentation to plan before coding.
This approach provides templates and structured workflows for teams who prefer more manual control over the planning process.
PRD (What/Why) → Spec (How) → Task Breakdown → Small PRs
Learn about visual diagrams: See Visuals & Diagrams Guide to understand how C4 diagrams and task graphs help decompose features and communicate architecture.
-
Write a PRD using
templates/prd-template.md- Define the problem, user stories, and non-goals
- Get stakeholder alignment before technical work
-
Write a Technical Spec using
templates/spec-template.md- Add C4 architecture diagrams (Mermaid)
- Break work into tasks targeting ~200-400 lines each
- Map dependencies between tasks
-
Create Jira Tickets from the spec's task breakdown
- One task = one PR
- Link each ticket back to the spec
- Check PR size - Warn if >400 lines, block if >800
- Verify spec link - Every feature PR must link to its spec
- Review architecture first - Look at C4 diagrams before code
- Use the PR template from
templates/pull-request-template.md
┌─────────────────────────────────────────────────────────────────────┐
│ TICKET PLANNING │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ PRD │───▶│ Spec │───▶│ Tasks │───▶│ Jira │ │
│ │ (What) │ │ (How) │ │ (Work) │ │ Tickets │ │
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ User Stories C4 Diagrams ~200-400 lines │
│ Non-Goals Data Model per task │
│ Success KPIs API Design │
│ │
└─────────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────────┐
│ PR REVIEW │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ Size │───▶│ Spec │───▶│ C4 │───▶│ Code │ │
│ │ Check │ │ Link │ │ Diagram │ │ Review │ │
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
│ │ │ │ │ │
│ ▼ ▼ ▼ ▼ │
│ < 400 lines? Context for Architecture Implementation │
│ reviewer changes first details second │
│ │
└─────────────────────────────────────────────────────────────────────┘
Let's walk through planning a "Custom Chatbot Workflows" feature.
See full example: examples/prd-chatbot-workflows.md
Key sections:
## Problem Statement
Users need to customize how the chatbot responds to different scenarios,
but currently all conversation logic is hardcoded. This forces engineering
involvement for every business logic change.
## User Stories
As a conversation designer, I want to create and modify chatbot workflows
visually, so that I can launch new conversation patterns without engineering support.
## Non-Goals (Scope Fence)
- Version history / diff view - Track later based on usage
- Workflow analytics - Separate initiative after MVP
- A/B testing workflows - Requires experimentation platformSee full example: examples/spec-chatbot-workflows.md
C4 Container Diagram:
C4Container
title Container Diagram: Chatbot Workflow System
Person(designer, "Conversation Designer")
System_Boundary(platform, "Our Platform") {
Container(web_app, "Web Application", "React", "Workflow editor UI")
Container(api, "API Service", "Node.js/Express", "Workflow CRUD + management")
Container(executor, "Workflow Executor", "Node.js", "Runtime execution engine")
Container(chatbot, "Chatbot Service", "Node.js", "Conversation handling")
ContainerDb(db, "Database", "PostgreSQL", "Workflow definitions")
ContainerDb(cache, "Cache", "Redis", "Active workflow cache")
}
Rel(designer, web_app, "Uses", "HTTPS")
Rel(web_app, api, "Calls", "HTTPS/JSON")
Rel(api, db, "Reads/Writes", "SQL")
Rel(chatbot, executor, "Executes workflow", "Internal")
Rel(executor, cache, "Reads active workflows", "Redis")
Task Breakdown:
| ID | Task | Est. Lines | Dependencies |
|---|---|---|---|
| T1 | Database migrations | ~100 | None |
| T2 | Workflow repository layer | ~200 | T1 |
| T3 | Workflow validation service | ~150 | T2 |
| T4 | List/Search API endpoint | ~150 | T2 |
| T5 | CRUD API endpoints | ~200 | T3 |
| T6 | Publish/Unpublish API | ~150 | T5 |
| T7 | Redis cache layer | ~100 | T6 |
| T8 | Workflow Matcher | ~150 | T7 |
| T9 | Execution Engine core | ~250 | T8 |
| T10 | Message node handler | ~80 | T9 |
| ... | ... | ... | ... |
Total: 25 tasks, ~4,000 lines across 25 PRs (~160 lines average)
Each task becomes a ticket:
Epic: Custom Chatbot Workflows
├── Story: Workflow Storage & Management
│ ├── Task: [T1] Create database migrations for workflows
│ ├── Task: [T2] Implement workflow repository layer
│ └── Task: [T3] Add workflow validation service
├── Story: Workflow API
│ ├── Task: [T4] Build list/search API endpoint
│ └── ...
When a PR comes in for task T5 (CRUD APIs), the reviewer should:
✓ PR is 187 lines (target: 200-400)
The PR links to /docs/specs/chatbot-workflows.md#task-breakdown
From the spec, the reviewer sees:
- This task builds on T3 (validation) and T2 (repository)
- It's part of the API layer in the C4 diagram
- It should not touch the Executor or Cache layers yet
Now with full context, the reviewer can verify:
- Does it follow the patterns established in T2-T4?
- Does it use the validation service from T3?
- Does it stay within its architectural boundary?
## Summary
Implements CRUD endpoints for workflow management.
## Spec Reference
**Spec**: `/docs/specs/chatbot-workflows.md`
**Task**: Completes task T5
## Changes Made
- POST /api/v1/workflows - Create workflow
- GET /api/v1/workflows/:id - Get workflow
- PUT /api/v1/workflows/:id - Update workflow
- DELETE /api/v1/workflows/:id - Archive workflow
## Checklist
- [x] PR is ≤ 400 lines
- [x] Spec link included
- [x] Tests added for all endpoints
- [x] Validation service used for all mutationsvibe-ship-small/
├── README.md # This file
├── TEAM-WORKFLOW-STANDARD.md # Full process documentation
├── docs/
│ ├── visuals-and-diagrams.md # Guide to C4 diagrams, task graphs, and LLM diagram generation
│ └── architecture-tools.md # Alternative architecture tools reference
├── templates/
│ ├── prd-template.md # PRD template
│ ├── spec-template.md # Technical spec template
│ └── pull-request-template.md # PR template for GitHub
├── examples/
│ ├── prd-chatbot-workflows.md # Complete PRD example
│ ├── spec-chatbot-workflows.md # Complete spec example
│ └── pr-example-chatbot-workflows.md # PR examples with task references
└── research/
├── Agent Communication Tools for Code.md
├── AI Planning and Architecture Prompt Search.md
├── Creating a Developer Cheat Sheet.md
├── PR-orchestration.md
└── PRD-Task-Graph.md
Git AI is an open-source Git extension that tracks AI-generated code throughout your development lifecycle - from prompts to production.
Why use it:
- Multi-agent attribution - Works with Claude Code, Cursor, Copilot, Gemini, and other AI coding tools
- Line-by-line tracking - See which AI model and prompt generated each line of code
- Git native - Uses Git Notes, preserving attribution through rebases and merges
- Team insights - Understand AI adoption, acceptance rates, and code durability
Quick start:
# Install Git AI
curl -fsSL https://gitai.sh/install.sh | sh
# Initialize in your project
git ai init
# Your AI coding agents automatically mark generated code
# Attribution data saved on commit - no workflow changes neededBest for:
- Teams using multiple AI coding agents (Claude Code, Cursor, etc.)
- Organizations wanting visibility into AI-assisted development
- Projects needing to track prompt effectiveness and code rationale
Learn more: Git AI Documentation
| PR Size | Action |
|---|---|
| < 200 lines | Good - might combine with related task |
| 200-400 lines | Ideal - reviewable in one sitting |
| 400-800 lines | Warning - consider splitting |
| > 800 lines | Block - must decompose further |
Not every team needs the full process. See TEAM-WORKFLOW-STANDARD.md for:
- Lightweight Option: Single "Design Doc" instead of PRD + Spec
- ADR-Driven: Document decisions as you go instead of upfront specs
- Stacked PRs: Accept large features, use PR chains for review
- Phased Adoption: Start with PR size limits, add specs gradually
| Week | Focus | Action |
|---|---|---|
| 1 | PR Size | Add CI warnings for PRs > 400 lines |
| 2 | Specs | Require specs for features with 3+ tasks |
| 3 | PRDs | Require PRDs for new epics |
| 4 | Full Process | C4 diagrams reviewed at grooming |
This is a living document. If you find improvements:
- Open an issue describing the problem
- Propose changes via PR
- Get team buy-in before merging process changes
MIT - Use freely, adapt for your team.