Skip to content

README.md

Latest commit

 

History

History
355 lines (261 loc) · 12.3 KB

README.md

File metadata and controls

355 lines (261 loc) · 12.3 KB

OneSyntax Playbook

The definitive guide to building quality software at OneSyntax

Version: 1.0
Last Updated: November 2025
Owner: Kalpa (CEO)

What This Is

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.

🚀 Quick Start - Choose Your Path

🆕 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?

What's Inside

🎯 Mission

Why OneSyntax exists and what we believe

Start here to understand our purpose and principles

📐 Standards

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

⚙️ Processes

How we maintain quality

Systems that keep us honest

👥 People

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

🚀 Execution

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

🛠️ Tools

Automation and enforcement

Making good architecture the default path

📋 Quick Reference (Cheat Sheets)

One-page guides to print and keep at your desk

Your daily tools for excellence:

Print these! Keep them visible! Use them daily!

Pro tip: Review the appropriate checklist before every PR.

📖 Reference Library (Deep Dives)

Comprehensive guides for deep understanding

When practical guides aren't enough and you need complete context:

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.

Repository Structure

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

Contributing

This playbook is a living document. If you find:

  • Unclear explanations
  • Outdated information
  • Missing content
  • Better examples

Process:

  1. Create a branch
  2. Make your changes
  3. Submit PR to Kalpa or senior developers
  4. Get approval
  5. Merge to main

See our Code Review process for details.

Getting Started

For New Team Members

Week 1:

Week 2:

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

For Existing Team Members

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

Philosophy

"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)

Questions?

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

Setup Instructions

To push this playbook to GitHub:

  1. Run the setup script:

    ./setup.sh

  2. 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

  3. Set up branch protection (Settings → Branches → Add rule)

See full setup instructions in comments at top of setup.sh

Remember

Let's build software that matters. Together. 💪

This playbook is your guide to excellence at OneSyntax. Use it. Share it. Improve it.