Guides Overview

The guides are the engineering handbook inside the handbook: opinionated, concrete references for how to run a real software project. Each one explains a practice and the reasons for it, with sources, so you can adapt it to your project instead of following it step by step. Reach for a guide when your team hits the problem it covers, or better, one sprint before.

Working Together

• Working Agreement: what the agreement settles (roles, decisions, communication, AI tool norms), how to write it together, and how to keep it current.
• Sprint: how a two-week sprint runs from planning to retrospective, what “done” has to mean, estimating and protecting the plan, and when Kanban fits better.
• Planning and Prioritization: ideation techniques, prioritization methods, and how to pick a success metric you can actually measure.
• Project Risks: finding what could stop the project, writing and ranking each risk, the four responses, and keeping docs/risks.md current.
• Retrospectives: formats and facilitation for sprint, milestone, and project retrospectives, and the postmortem after an incident.
• Conflict and Performance Conversations: conflict-handling modes, raising a contribution problem, and when to escalate.

Building

• Git and GitHub: a branching workflow, the pull request cycle from branch to merge, merge conflicts, and the repository settings that enforce the workflow.
• Requirements: writing testable requirements for your repo’s living docs/requirements.md.
• Technical Design: what docs/design.md has to decide (architecture, interfaces, data), spikes for the risky parts, design review, and keeping the document true as the code moves.
• ADR: which decisions deserve an architecture decision record, what goes in one, and how to review, store, and replace it.
• Generative AI: where to spend your attention, how to question and learn from what a tool gives you, how to choose a model, what not to paste into a tool, and what the research says about how much these tools help.
• AI Project Setup: AGENTS.md and its per-tool equivalents, hooks and gates, MCP servers, and skills, all checked into the repository.

Verifying and Shipping

• Testing Strategy: what to test automatically and in what proportion, how to keep the suite trustworthy, and how to check with real users that you’re building the right thing.
• Accessibility Testing: the automated gates, the keyboard and screen-reader pass, and testing with a daily assistive-technology user.
• Security: STRIDE, secrets, dependencies, and managed auth.
• DevOps: CI/CD, environments, deployment platforms, and rollbacks.
• Shipping: how to measure shipped, the processes outside the team that the top rungs wait on, and the clocks each one needs started early.
• Documentation: which documents to write for which reader, from the README to the API reference, and how to keep them accurate as the code changes.

Communicating

• Presentations: sprint demos, stakeholder presentations, design reviews, and public demonstrations such as a showcase or a conference demo.