The operating manual for Razorpay's AI builder program. A belt-progression curriculum, seven reusable Claude Code skill definitions, and a Starlight hub — all built on one Markdown source of truth.
v0.73 alpha · updated 2026-09-10 · source of truth: Markdown
Master Index · Changelog · Roadmap · Contributing
A playbook for AI-native engineering at Razorpay. It starts before tools — before Terminal, before "what's an API" — and climbs through Foundation, four belts (White, Yellow, Green, Black), and a Staff+ Council layer for senior contributors. A reader who finishes can ship code with AI, lead a team adoption sprint, or contribute back to the org's internal skills and knowledge-base layer.
The content is Markdown-first, written to be outside-readable at the lower belts and fintech-real at the upper ones. Belts are earned by shipping, not by reading — every belt has required modules, hands-on quests, and a boss-fight capstone.
The same Markdown layer powers three consumption surfaces. Pick the one that fits how you want to read.
| Door | Best for | How to use it |
|---|---|---|
| Read on GitHub | Skimming, linking, and reading in the same place you work. | Start at INDEX.md. Every chapter is a flat Markdown file. |
| Browse the hub | The polished web experience with search, sidebar, and progress markers. | The Astro Starlight site under hub/. See Run the hub below. |
| Inspect a reusable workflow | Understanding how a bounded skill should behave before it is distributed. | Start in the Skills Library. The seven reference definitions live under skills/; confirm the current runnable distribution in #ai-help rather than assuming Compass ships them. |
- New to software. → Part 0 — Foundation. Tech 101 + Ops 101. Pre-tools, pre-AI, fully outside-readable.
- Already know what an API, database, and deploy are. → Prologue. A twelve-chapter mental-model warmup.
- Reviewing the whole playbook as a sponsor or maintainer. → Master Index.
- Looking for templates, cards, glossary, or certification policy. → Appendices.
- Senior IC interested in the Council layer. → Staff+ Council.
If you want a guided walk, use the index or hub today. The repo contains a playbook-course reference definition for a stateful Claude Code walk, but it is not currently shipped through Compass; confirm a supported runnable route in #ai-help.
.
├── README.md # you are here
├── INDEX.md # reader-facing master TOC
├── CHANGELOG.md # what shipped, when
├── CONTRIBUTING.md # design principles, content rules, voice
├── ROADMAP.md # open questions and the v1.0 path
├── manifest.yml # machine-readable course manifest
├── slugs.yml # stable URL + skill ID map
│
├── foundation/ # Part 0 — Tech 101 + Ops 101
├── prologue/ # 12-chapter mental-model warmup
├── belts/ # 01-white → 02-yellow → 03-green → 04-black → 05-council
├── appendices/ # A tool atlas · B setup · C skills · D issues · E roles
│ # F slack · G glossary · H cards · I templates
│ # J reading · L certification · N methodologies
├── case-studies/ # Boss Fight B-B case studies seed here
│
├── skills/ # 7 Claude Code reference definitions
├── diagrams/ # 9 signature SVG diagrams + 2 legacy aliases
├── excalidraw/ # 7 hand-drawn companion illustrations
├── hub/ # Astro Starlight source — regenerated from above
└── scripts/ # build + polish tooling
cd hub
npm install
npm run dev
# open http://127.0.0.1:4321/Production build:
cd hub
npm run build # static output → hub/dist/
npm run preview # serve hub/dist/ locallyThe hub regenerates hub/src/content/docs/ from the root Markdown on every build. Edit the root Markdown — never the generated files, which are overwritten.
The hub is published to GitHub Pages on every merge to master and is accessible at:
| Trigger | What happens | URL |
|---|---|---|
Push to master |
Site builds and deploys automatically (~2 min) | https://razorpay.github.io/ai-playbook/ |
| PR opened / updated | Preview build deploys automatically | https://razorpay.github.io/ai-playbook/pr-preview/pr-{N}/ |
| PR closed / merged | Preview is automatically removed | — |
The bot posts a comment on every PR with the preview URL so you can verify the rendered output before merging.
Go to Actions → Deploy to GitHub Pages → Run workflow → master.
The in-repo playbook-course definition specifies how a stateful Claude Code walk should pace the curriculum, read curriculum.json, and track progress in a local LEARNER.md. It is a reference implementation, not a Compass command currently available to learners.
Use the Master Index or hub for a guided reading route today. Maintainers can inspect the course-skill notes; confirm any supported runnable distribution in #ai-help before sharing invocation guidance. A future implementation may record quest and boss-fight claims, but belt awards still follow Appendix L's reviewer protocol.
Foundation, Prologue, all four belts, the Staff+ Council section, thirteen drafted appendices plus one planned appendix, seven Claude Code reference definitions, seven quick-reference cards, nine signature SVG diagrams, and seven hand-drawn companion illustrations. Appendix E (Roles & Forums) remains a drafted skeleton, and Appendix F (Slack Channels) is a living directory; named holders refresh quarterly. Appendix K is the root CHANGELOG.md, and Appendix M remains planned. Every other appendix is drafted end-to-end. The reading order is coherent end-to-end from first commit to Council membership.
Version history is in CHANGELOG.md. What's coming next is in ROADMAP.md.
Read CONTRIBUTING.md before opening a PR. It covers the seven review principles, the content rules (Razorpay-term tiering, no PII, no personal names), the voice commitments, and the link-and-lint sweep that gates merges.
For substantial changes (a belt restructure, a new track, a voice change), write an AI RFC using the template in Appendix I. The RFC is reviewed by the Staff+ Council per C.3.
Next: → Master Index · → Part 0 — Foundation · → Prologue