An open-source operating system for shipping production-grade software.
Built for humans. Aligned for AI.
Protocol · AI Agent Rules · Templates · Examples · Skills
This is not a code framework, a design system, or a collection of random templates. It is a complete operating system for shipping software.
It defines exactly how to:
- Plan before coding — written plans, not mental models
- Execute with precision — branch strategy, commit conventions, code standards
- Verify before merging — pre-merge checklists, build checks, visual QA
- Test with discipline — test pyramid, coverage targets, naming conventions
- Deploy safely — environment ladder, rollback strategy, monitoring
- Recover when things break — incident response, postmortems, root cause analysis
- Collaborate with AI — strict guardrails for LLM copilots with earned trust levels
Drop it into any project — solo founder, startup team, or enterprise squad — to enforce professional standards from day one.
| Audience | What PWP Gives You | |
|---|---|---|
| 🧑💻 | Solo Builders | The discipline of a senior engineer review — without the overhead |
| 🚀 | Startup Teams | Async alignment — new hires read the protocol and know the rules |
| 🏢 | Enterprise Squads | Traceability from business requirement → plan → commit → deployment |
| 🤖 | AI-Native Builders | Strict protocol to keep copilots from generating legacy code |
# 1. Clone the repo
git clone https://github.com/shandarjunaid/Project-Workflow-Protocol.git
# 2. Copy into your project
cp -r protocol/ templates/ skills/ /path/to/your/project/
# 3. Align your AI (Cursor, Windsurf, Gemini CLI, etc.)
# Drop skills/project-workflow-protocol.skill.md into your AI's knowledge base- Before writing code → Write a plan using
templates/plan-template.md - While coding → Follow the branch strategy in
templates/branch-strategy.md - Before merging → Run the checklist in
templates/verification-checklist.md - New to PWP? → Start with the
templates/quick-reference.mdone-page summary
Solo builder? Use the lightweight
solo-plan-template.mdandsolo-verification-checklist.mdfor faster iteration. The protocol docs include> Solo Mode:callouts throughout.
Project-Workflow-Protocol/
├── protocol/ # Core protocol modules
│ ├── 00-mindset.md # Philosophy & non-negotiable standards
│ ├── 01-planning.md # Plan before coding
│ ├── 02-execution.md # Branch, commit, and code standards
│ ├── 03-verification.md # Pre-merge checklists & QA
│ ├── 04-documentation.md # Living docs & traceability
│ ├── 05-communication.md # Collaboration standards
│ ├── 06-recovery.md # Incident response & postmortems
│ ├── 07-testing.md # Testing discipline & test pyramid
│ ├── 08-deployment.md # Deployment lifecycle & rollback
│ ├── 09-dependency-management.md # Dependency evaluation & audits
│ └── ai-agents/ # AI-specific constraints
│ ├── 00-agent-mindset.md # How AI should think
│ ├── 01-scope-and-authority.md # What AI can & cannot do
│ ├── 02-planning-with-ai.md # AI planning requirements
│ ├── 03-execution-rules.md # Code standards for AI
│ ├── 04-verification-duties.md # AI verification duties
│ ├── 05-communication-contract.md # How AI reports status
│ ├── 06-failure-and-recovery.md # AI failure handling
│ ├── 07-evaluation-and-trust.md # Trust levels (L0-L3) & earned autonomy
│ ├── 08-context-management.md # Context window budget strategy
│ ├── 09-tool-selection.md # Tool selection decision trees
│ └── 10-multi-session-continuity.md # Session handoff protocol
├── templates/ # Copy-paste-ready templates
│ ├── plan-template.md # Implementation plan structure
│ ├── solo-plan-template.md # ⚡ 5-line plan for solo devs
│ ├── branch-strategy.md # Git branching reference
│ ├── commit-convention.md # Commit message format
│ ├── verification-checklist.md # Pre-merge QA checklist
│ ├── solo-verification-checklist.md # ⚡ Two-tier solo checklist
│ ├── changelog-template.md # Structured release notes
│ ├── adr-template.md # Architecture Decision Record
│ ├── incident-postmortem.md # Blameless postmortem template
│ ├── deployment-checklist.md # Pre/post deploy checklist
│ ├── dependency-audit.md # Periodic dependency audit
│ └── quick-reference.md # One-page protocol summary
├── examples/ # Real-world adoption scenarios
│ ├── solo-builder.md # Solo dev workflow
│ ├── startup-team.md # 3-8 person team workflow
│ └── enterprise-team.md # Large org adoption (RACI, phased rollout)
├── skills/ # Drop-in AI agent skill files
│ ├── project-workflow-protocol.skill.md # Full PWP skill
│ ├── ai-agent-protocol.skill.md # AI constraints skill
│ ├── code-review.skill.md # Code review checklist & severity levels
│ ├── debugging.skill.md # Systematic debugging protocol
│ ├── refactoring.skill.md # Safe refactoring patterns
│ ├── security-audit.skill.md # Security audit checklist (OWASP)
│ ├── performance-optimization.skill.md # Performance investigation protocol
│ ├── api-design.skill.md # REST API design standards
│ ├── migration.skill.md # Database & platform migration protocol
│ └── project-bootstrap.skill.md # New project initialization protocol
├── .github/
│ ├── pull_request_template.md # PR template
│ └── ISSUE_TEMPLATE/ # Issue templates
│ ├── feedback.md
│ ├── improvement.md
│ └── usage-report.md
├── CONTRIBUTING.md
├── CODE_OF_CONDUCT.md
├── SECURITY.md
├── CHANGELOG.md
├── roadmap.md
└── LICENSE (MIT)
This repository includes a specialized extension for AI agents. Located in protocol/ai-agents/, it defines hard constraints for LLMs participating in your project:
- No hallucinated authority — AI suggests, humans decide
- No silent failures — skipped steps must be announced
- Full traceability — every line of code traces back to a plan
- Earned autonomy — trust levels L0 → L3, promoted by clean deliveries
- Context discipline — budget-aware context window management
- Session continuity — structured handoffs between ephemeral AI sessions
To install: drop skills/ai-agent-protocol.skill.md into your AI's knowledge base.
Beyond the core protocol, PWP includes drop-in skill files for common engineering tasks:
| Skill | What It Covers |
|---|---|
| Code Review | Review checklist, severity levels, comment format |
| Debugging | 7-step systematic debugging protocol |
| Refactoring | Safe refactoring patterns with verification |
| Security Audit | OWASP-aligned security checklist |
| Performance | Measure → identify → fix → verify workflow |
| API Design | REST conventions, status codes, pagination |
| Migration | Safe schema and data migration protocol |
| Project Bootstrap | New project initialization in 30 minutes |
Drop any skill file into your AI's knowledge base for instant task-specific alignment.
We treat this protocol like a product — versioned, changelogged, and evolved intentionally.
| Version | Status | Focus |
|---|---|---|
| v0.1 | ✅ Released | Founder Edition — core protocol, templates, AI rules, examples |
| v0.2 | ✅ Released | Solo Builder Feedback — solo mode callouts, simplified verification |
| v0.3 | ✅ Released | Professional Edition — testing, deployment, dependencies, 8 task skills, enterprise patterns |
| v1.0 | ⬜ Planned | Community Stable — frozen core, semantic versioning, migration guide |
See roadmap.md for the full vision.
We welcome contributions, but we are extremely strict about what gets merged.
Accepted: Clarifications, real-world examples, edge cases, tooling adaptations, battle-tested learnings.
Rejected: Anything that lowers the quality bar, optional shortcuts, unproven opinions.
See CONTRIBUTING.md before opening a PR.
MIT © Shandar Junaid | Affordance Design