The definitive guide to building quality software at OneSyntax
Version: 1.0
Last Updated: November 2025
Owner: Kalpa (CEO)
This playbook contains everything you need to know about how we develop software at OneSyntax:
- Why we exist and what we stand for
- Standards for DDD, Clean Architecture, and testing
- Processes for code review, enforcement, and quality
- People development - training and career growth
- Execution plans for implementing our system
- Tools and automation we use
This is not optional reading. Your success at OneSyntax depends on understanding and following this playbook.
🆕 I'm new here → 2-minute overview then onboarding checklist
💻 I need to code something → Development standards | Code review checklist
📚 I want deep understanding → Reference library (comprehensive guides)
🎯 Looking for something specific?
- Why DDD/Clean Architecture/TDD? → Why These Practices?
- Code review checklist → Code Review
- Pair programming guide → Pair Programming
- When to refactor? → Refactoring Decisions
- Sprint planning → Planning Game
- Work-life balance → Sustainable Pace
- Career growth → Career Framework
- Quality initiative → 90-Day Plan
- Setting up tools → Enforcement Setup
- Architecture patterns → Architecture Guide
- Rewards & recognition → Rewards Program
Why OneSyntax exists and what we believe
- Why We Exist - Our Golden Circle (WHY, HOW, WHAT)
- Our Values - 7 core values that guide our work
Start here to understand our purpose and principles
How we build software
- Why These Practices? - First principles reasoning:
- From trust problems to technical solutions
- Why DDD, Clean Architecture, and TDD specifically
- Trade-offs we accept and when NOT to use these practices
- Development System - Complete guide to:
- Domain-Driven Design (DDD)
- Clean Architecture
- Test-Driven Development (TDD)
- Simple Design - Balancing YAGNI with architectural standards
- Acceptance Tests - Customer tests and Given-When-Then format
The technical foundation of everything we do
How we maintain quality
- Enforcement - 3-layer quality system
- Code Review - Review checklist and process
- Collective Ownership - Shared code responsibility with individual accountability
- Pair Programming - When and how to pair effectively
- Planning Game - Sprint planning and story estimation
- Small Releases - CI/CD and deployment strategy
Systems that keep us honest
How we learn and grow
- Training - 12-week deliberate practice program
- Career - Career progression from IC1 to IC5/M4
- Sustainable Pace - 40-hour work week and burnout prevention
- Whole Team - Cross-functional collaboration and Three Amigos
Your path to excellence
How we implement change
- 90-Day Plan - Complete quality initiative rollout
- Week-by-week execution
- Client communication
- Risk management
- Success metrics
Ready-to-launch implementation guide
Automation and enforcement
- Enforcement Setup - ArchUnit, linters, CI/CD
Making good architecture the default path
One-page guides to print and keep at your desk
Your daily tools for excellence:
- DDD Checklist - Entities, Value Objects, Aggregates quick reference
- Code Review Checklist - Author and reviewer checklists
- Clean Architecture Cheatsheet - Layer structure and dependency rules
- XP Practices Checklist - Collaboration and planning practices
- Refactoring Checklist - Safe tidyings and when to refactor
- Sprint Planning Template - Complete sprint planning guide
Print these! Keep them visible! Use them daily!
Pro tip: Review the appropriate checklist before every PR.
Comprehensive guides for deep understanding
When practical guides aren't enough and you need complete context:
- Architecture Guide - Complete Laravel Clean Architecture reference
- System Deep Dive - Full DDD + Clean Architecture + TDD system (1,647 lines)
- Enforcement Deep Dive - Complete enforcement & accountability system (2,698 lines)
- Execution Complete - Full 6-month execution plan with budget details
- Promotion Framework - Comprehensive career progression guide
- Rewards Program - Complete rewards & recognition program
- Refactoring Decisions - When to refactor: decision framework and cost-benefit analysis
- Safe Refactorings - 15 micro-tidyings you can do anytime
- Technical Debt Management - Debt ledger and prioritization framework
These are your "deep dive" resources when you need full context and philosophy
Pro tip: Start with practical guides in numbered directories, then consult reference library when you need more detail.
onesyntax-playbook/
├── README.md # You are here (start here!)
├── SETUP.md # Setup instructions
├── setup.sh # Quick setup script
│
├── 1-mission/ # Why we exist
│ ├── why-we-exist.md # Golden Circle (WHY, HOW, WHAT)
│ └── our-values.md # Core values
│
├── 2-standards/ # What we build
│ ├── why-these-practices.md # First principles reasoning
│ ├── development-system.md # DDD + Clean Architecture + TDD
│ ├── simple-design.md # YAGNI vs architecture balance
│ └── acceptance-tests.md # Given-When-Then format
│
├── 3-processes/ # How we work
│ ├── enforcement.md # Quality enforcement
│ ├── code-review.md # Code review process
│ ├── collective-ownership.md # Shared code responsibility
│ ├── pair-programming.md # Pairing guidelines
│ ├── planning-game.md # Sprint planning
│ └── small-releases.md # CI/CD deployment
│
├── 4-people/ # How we grow
│ ├── training.md # 12-week program
│ ├── career.md # Career framework
│ ├── sustainable-pace.md # 40-hour work week
│ └── whole-team.md # Cross-functional collaboration
│
├── 5-execution/ # How we implement
│ └── 90-day-plan.md # Quality initiative
│
├── 6-tools/ # What we use
│ └── enforcement-setup.md # ArchUnit, linters, CI/CD
│
├── quick-reference/ # Printable cheat sheets
│ ├── ddd-checklist.md # DDD patterns quick reference
│ ├── code-review-checklist.md # Code review guide
│ └── clean-architecture-cheatsheet.md # CA layers & rules
│
└── reference/ # Deep dive guides
├── architecture-guide.md # Laravel Clean Architecture
├── system-deep-dive.md # Complete DDD/CA/TDD guide
├── enforcement-deep-dive.md # Full enforcement system
├── execution-complete.md # 6-month execution plan
├── promotion-framework.md # Complete career guide
├── rewards-program.md # Rewards & recognition
├── refactoring-decisions.md # When to refactor framework
├── safe-refactorings.md # Micro-tidyings catalog
└── technical-debt-management.md # Debt ledger & prioritization
📌 Navigation:
- Numbers (1-6) → Recommended reading order for practical guides
- quick-reference/ → Printable cheat sheets for daily use
- reference/ → Deep dives when you need comprehensive coverage
This playbook is a living document. If you find:
- Unclear explanations
- Outdated information
- Missing content
- Better examples
Process:
- Create a branch
- Make your changes
- Submit PR to Kalpa or senior developers
- Get approval
- Merge to main
See our Code Review process for details.
Week 1:
- Read Why We Exist
- Read Our Values
- Skim Development System
Week 2:
- Deep dive Development System
- Start Training Program
- Review Code Review checklist
Week 3:
- Complete first training exercises
- Participate in code reviews
- Apply standards in real work
Week 4+:
- Continue deliberate practice
- Master the standards
- Help onboard others
If you're part of the quality initiative:
Week -1:
- Read entire playbook
- Review 90-Day Plan
- Prepare questions for launch meeting
Week 1:
- Attend all-hands kickoff
- Start training program
- Set up enforcement tools
Weeks 2-13:
- Follow 90-Day Plan
- Complete training exercises
- Apply standards to projects
"This playbook exists to support OneSyntax's mission of true partnership through accountable, professional development."
Our standards aren't about perfection - they're about partnership. When we build software right, we honor our clients' trust and investment.
Every standard connects to our WHY:
- DDD → Understanding client's business (true partnership)
- Clean Architecture → Systems that last (honoring trust)
- TDD → Quality from day one (professional delivery)
- Enforcement → Discipline that protects (accountability)
- Slack: #architecture
- Owner: Kalpa
- Email: kalpa@onesyntax.com
Want to discuss a standard? Weekly architecture review meetings (Thursdays)
Need clarification? Ask in #architecture or your 1:1s
Found an issue? Open a PR or bring it up in retrospectives
To push this playbook to GitHub:
-
Run the setup script:
./setup.sh
-
Or manually:
git init git add . git commit -m "feat: Initial OneSyntax Playbook" git remote add origin https://github.com/YOUR_USERNAME/onesyntax-playbook.git git branch -M main git push -u origin main
-
Set up branch protection (Settings → Branches → Add rule)
See full setup instructions in comments at top of setup.sh
Let's build software that matters. Together. 💪
This playbook is your guide to excellence at OneSyntax. Use it. Share it. Improve it.