Skip to content
Back to search

claude-code-staff-engineer

Building a Senior Staff Engineer with Sub-Agent Teams in Claude Code

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/fareedkhan-dev--claude-code-staff-engineer/badge.svg)](/listings/fareedkhan-dev--claude-code-staff-engineer)

HTML

<a href="/listings/fareedkhan-dev--claude-code-staff-engineer"><img src="/api/listings/fareedkhan-dev--claude-code-staff-engineer/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 2,433 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Building a Senior Staff Engineer Agent with Claude Code
  2. The difference between a Junior and a Senior engineer isn’t syntax, it’s predictability, risk management, and discipline under pressure. AI agents struggle with exactly this: **they skip reviews, rationalize shortcuts, and ship work they are proud of but nobody actually verified**. [Anthropic shows agents collaborate well](https://www.anthropic.com/engineering/building-c-compiler) but without structure, more agents just mean more chaos and wasted compute. What you need is what real companies have: **a Staff Engineer orchestrating specialized sub-agents** through a disciplined pipeline from design to deployment, and that is exactly what we are going to build …
  3. ![Senior Staff Engineer with teams of sub-agents](https://miro.medium.com/v2/resize:fit:2400/1*I08rZPc6O6w_3guzssUfHw.png)
  4. *Senior Staff Engineer with teams of sub-agents (Created by [Fareed Khan](https://medium.com/u/b856005e5ecd))*
  5. The system works like a real engineering organization with clear separation of responsibilities:
  6. * **Discovery & Design**: The Architect asks questions one at a time, explores 2–3 approaches with trade-offs, and produces a design spec committed to git. No code before human approval.
  7. * **Planning & Review**: The Tech Lead breaks the spec into 2–5 minute tasks with exact file paths and complete code. A fresh sub-agent audits the plan against the spec to catch gaps and scope creep.
  8. * **Execution Engine**: The Manager dispatches a fresh sub-agent per task with isolated context. Stuck agents escalate. Bad work gets terminated and re-dispatched.
  9. * **Quality Gates**: Two sequential reviews: spec compliance (right thing?) then code quality (built well?). A verification gate demands fresh terminal output before any completion claim.
  10. * **Engineering Discipline**: TDD enforced as iron law. Debugging follows a four-phase forensic process. Root cause tracing goes five levels deep. Skills themselves are pressure-tested against real agents before deployment.
  11. In this blog we are going to …
  12. > visually walk through each stage of this workflow, build every component step by step from hooks to skills to agents, and see how they work together as a disciplined engineering team using Claude Code.
  13. ## Table of Contents
  14. * [Creating the Team Codebase](#creating-the-team-codebase)
  15. * [Hooks (The Management Layer)](#hooks-the-management-layer)
  16. * [Brainstorming & Design (Planning Phase)](#brainstorming--design-planning-phase)
  17. * [Finding Logical Loopholes (Spec Review)](#finding-logical-loopholes-spec-review)
  18. * [Visual Companion (Whiteboarding Sessions)](#visual-companion-whiteboarding-sessions)
  19. * [Writing Plans (Backlog Grooming)](#writing-plans-backlog-grooming)
  20. * [Plan Review (The Grooming Gatekeeper)](#plan-review-the-grooming-gatekeeper)
  21. * [Subagent-Driven Development (Delegation)](#subagent-driven-development-delegation)
  22. * [The Implementer Prompt (Developer Job Description)](#the-implementer-prompt-developer-job-description)
  23. * [Spec & Code Quality Reviewers (Compliance Officers)](#spec--code-quality-reviewers-compliance-officers)
  24. * [Test-Driven Development (The Iron Law)](#test-driven-development-the-iron-law)
  25. * [Testing Anti-Patterns (Lazy QA Training)](#testing-anti-patterns-lazy-qa-training)
  26. * [Systematic Debugging (Forensic Engineering)](#systematic-debugging-forensic-engineering)
  27. * [Root Cause Tracing & Defense in Depth](#root-cause-tracing--defense-in-depth)
  28. * [Verification Before Completion (Final Sign-off)](#verification-before-completion-final-sign-off)
  29. * [The Peer Review Meeting (Code Review)](#the-peer-review-meeting-code-review)
  30. * [Using Git Worktrees (Bio-hazard Containment)](#using-git-worktrees-bio-hazard-containment)
  31. * [Writing Skills (The Academy)](#writing-skills-the-academy)
  32. * [Agents & Commands (Team Directory)](#agents--commands-team-directory)
  33. * [**Testing the Senior Staff Engineer**](#testing-the-senior-staff-engineer)
  34. * [How to Improve It Further](#how-to-improve-it-further)
  35. ---
  36. ## Creating the Team Codebase
  37. In every engineering organization, before the first line of product code is written, someone has to set up the infrastructure. At companies like Spotify, Shopify, and Stripe, this is the staff engineer’s first job on a new initiative.
  38. ![Team Codebase](https://miro.medium.com/v2/resize:fit:2000/1*YCdwfyYvk7208Y1-qHeieQ.png)
  39. *Team Codebase (Created by [Fareed Khan](https://medium.com/u/b856005e5ecd))*
  40. They don’t start coding features. They establish the project structure, the development workflows, the CI/CD pipelines, and the team norms. **They build the organizational scaffolding that makes everyone else’s work possible.**
  41. **When you work with Claude Code normally, you might use a few skills, an MCP server, maybe some tool scripts, or even start from scratch and let Claude figure it out**.
  42. But we are not building a solo developer. We are building a **team** of agents that need to collaborate, follow processes, and hold each other accountable. That requires structure, the same way a 10 person engineering team requires structure that a solo freelancer doesn’t.
  43. So before we write any skills or define any agents, we need to create the organizational scaffolding:
  44. ```bash
  45. senior_staff_engineer/
  46. ├── agents/ # agent + sub-agent definitions
  47. ├── commands/ # custom CLI-style agent commands
  48. ├── hooks/ # lifecycle hooks (events, workflow control)
  49. ├── skills/ # core capability modules
  50. │ ├── design-and-discovery/ # idea generation & design
  51. │ │ └── scripts/ # visual/interactive brainstorming
  52. │ ├── delegation/ # delegate to sub-agents
  53. │ ├── evidence-verification/ # final validation before completion
  54. │ ├── execution-engine/ # step-by-step plan execution
  55. │ ├── forensic-debugging/ # root-cause analysis
  56. │ ├── orchestration/ # coordinate multiple agents
  57. │ ├── planning-and-backlog/ # plan creation
  58. │ ├── release-engineering/ # finalize work before merge
  59. │ ├── review-reception/ # process feedback & iterate
  60. │ ├── review-requesting/ # prepare PRs + request reviews
  61. │ ├── skill-academy/ # authoring new skills
  62. │ ├── tdd-discipline/ # write tests → implement → validate
  63. │ ├── using-senior-staff-engineer/ # configure & optimize this system
  64. │ └── worktree-management/ # isolate work via worktrees
  65. ```
  66. It might seem complex at first, but each directory maps to a role or function in a real engineering organization.
  67. 1. The `agents/` directory is the team roster, defining who does what.
  68. 2. The `skills/` directory is the employee handbook, containing the processes and standards every team member follows.
  69. 3. The `hooks/` directory is the management layer, controlling the flow of information and ensuring everyone starts aligned.
  70. We will build each of these one by one and make them act as a cohesive team that handles complex development tasks from planning through deployment.
  71. ## Hooks (The Management Layer)
  72. In every company, there’s a layer of management infrastructure that operates invisibly. **Before the first meeting of the day, the office is already open**, the coffee machine is running, the shared calendar is synced, and the team’s Slack channels are populated with overnight updates. Nobody thinks about this infrastructure until it breaks.
  73. > In our system, `hooks/` is this management layer.
  74. ![Hooks Management](https://miro.medium.com/v2/resize:fit:2000/1*eYulFW1w5whqPlukc_cOmA.png)
  75. *Hooks Management (Created by [Fareed Khan](https://medium.com/u/b856005e5ecd))*
  76. In Claude Code, hooks let you control what happens at specific lifecycle events, like when a session starts, when context is cleared, or when the agent compacts its memory. For a single developer, hooks are optional. For a team of agents that need to start every session with shared context and consistent rules, hooks are essential.
  77. We start with three files:
  78. ```bash
  79. hooks/
  80. ├── hooks.json # main configuration file
  81. ├── run-hook.cmd # cross-platform script executor
  82. ├── session-start # session initialization logic
  83. ```
  84. The `hooks.json` is simple. It defines one rule: every time a session starts, run the initialization script.
  85. ```json
  86. {
  87. "hooks": {
  88. "SessionStart": [
  89. {
  90. "matcher": "startup|clear|compact",
  91. "hooks": [
  92. {
  93. "type": "command",
  94. "command": "\"${PROJECT_ROOT_DIR}/hooks/run-hook.cmd\" session-start",
  95. "async": false
  96. }
  97. ]
  98. }
  99. ]
  100. }
  101. }
  102. ```
  103. The `matcher` triggers on three scenarios:
  104. 1. `startup` (fresh session), `clear` (context reset), and `compact` (memory compression).
  105. 2. In organizational terms, this is like having an onboarding checklist that runs not just on day one, but every time someone context-switches back to this project.
  106. > Because in AI agent terms, every session IS day one. The agent has no memory of yesterday's session. It needs to be re-onboarded every time.
  107. The `async: false` flag ensures the hook completes before the agent starts responding. This is the equivalent of saying "the morning standup must finish before anyone opens their laptop." You can learn more about how [Claude automates workflows with hooks](https://code.claude.com/docs/en/hooks-guide).
  108. In real companies, not everyone runs the same OS. **The engineering team might have Mac users, Linux servers, and the occasional Windows machine**. We need to create `run-hook.cmd` script that handles this by being a polyglot, a script that works on both Windows and Unix:
  109. ```bash
  110. if "%~1"=="" (
  111. echo run-hook.cmd: missing script name >&2
  112. exit /b 1
  113. )
  114. set "HOOK_DIR=%~dp0"
  115. REM Try Git for Windows bash in standard locations
  116. if exist "C:\Program Files\Git\bin\bash.exe" (
  117. "C:\Program Files\Git\bin\bash.exe" "%HOOK_DIR%%~1" %2 %3 %4 %5 %6 %7 %8 %9
  118. exit /b %ERRORLEVEL%
  119. )
  120. ```
  121. On Windows, it searches for bash in common Git installation paths. If bash isn’t found anywhere, it exits silently rather than crashing. On Unix, it simply executes the script directly:
  122. ```bash
  123. # Unix: run the named script directly
  124. SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
  125. SCRIPT_NAME="$1"
  126. shift
  127. exec bash "${SCRIPT_DIR}/${SCRIPT_NAME}" "$@"
  128. ```
  129. The agent doesn’t need to know what OS it’s running on. The gateway script figures it out and routes accordingly. **It’s the same principle behind Docker and Kubernetes: abstract away the environment so the application logic doesn’t need to care**.
  130. The `session-start` script is where the actual onboarding happens. When a new session begins, this script loads the squad's core skill file and injects it into the agent's context.
  131. > Think of it as the morning standup where the staff engineer reminds everyone of the team's operating principles before work begins.
  132. The script starts by resolving paths and checking for legacy configurations:
  133. ```bash
  134. #!/usr/bin/env bash
  135. set -euo pipefail
  136. SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
  137. PLUGIN_ROOT="$(cd "${SCRIPT_DIR}/.." && pwd)"
  138. # Legacy config check
  139. warning_message=""
  140. legacy_skills_dir="${HOME}/.config/staff_engineer/skills"
  141. if [ -d "$legacy_skills_dir" ]; then
  142. warning_message="\n\n<important-reminder>⚠️ **WARNING:**
  143. staff_engineer now uses Claude Code's skills system.
  144. Move custom skills to ~/.claude/skills instead.</important-reminder>"
  145. fi
  146. ```
  147. Then it loads the core skill file, which is the employee handbook every agent must read:
  148. ```bash
  149. using_staff_engineer_content=$(
  150. cat "${PLUGIN_ROOT}/skills/using-staff_engineer/SKILL.md" 2>&1 \
  151. || echo "Error reading using-staff_engineer skill"
  152. )
  153. ```
  154. The content gets escaped for JSON and wrapped in a context payload:
  155. ```bash
  156. session_context="<EXTREMELY_IMPORTANT>\nYou have staff_engineer.
  157. \n\n**Below is the full content of your 'staff_engineer:using-
  158. staff_engineer' skill - your introduction to using skills. For
  159. all other skills, use the 'Skill' tool:**\n\n
  160. \n${using_staff_engineer_escaped}\n\n${warning_escaped}\n
  161. </EXTREMELY_IMPORTANT>"
  162. ```
  163. Finally, the script outputs the payload in a format specific to whichever platform is running it:
  164. ```bash
  165. if [ -n "${CURSOR_PLUGIN_ROOT:-}" ]; then
  166. printf '{\n "additional_context": "%s"\n}\n' "$session_context"
  167. elif [ -n "${CLAUDE_PLUGIN_ROOT:-}" ] && [ -z "${COPILOT_CLI:-}" ]; then
  168. printf '{\n "hookSpecificOutput": {\n "hookEventName":
  169. "SessionStart",\n "additionalContext": "%s"\n }\n}\n' \
  170. "$session_context"
  171. else
  172. printf '{\n "additionalContext": "%s"\n}\n' "$session_context"
  173. fi
  174. ```
  175. Claude Code, Cursor, and Copilot CLI each expect context in a slightly different JSON format. Our script handles all three, which means the same squad can operate across different AI coding platforms without modification.
  176. **This is the kind of cross-platform thinking that staff engineers bring to infrastructure work**, building things that work everywhere instead of just on their own machine.
  177. #### The Employee Handbook (The 1% Rule)
  178. In every organization, there’s a founding document that establishes culture. At Amazon, it’s the Leadership Principles. At Netflix, it’s the Culture Deck. At Bridgewater, it’s the Principles. **These documents don’t just describe what the company does. They describe how every person in the company should think.**
  179. ![Employee handbook](https://miro.medium.com/v2/resize:fit:2400/1*7t7NhEoIWqhu0B2OqIpjZw.png)
  180. *Employee handbook (created by [Fareed Khan](https://medium.com/u/b856005e5ecd))*
  181. `skills/using-senior-staff-engineer/SKILL.md` is our culture deck. It's the first thing loaded into every agent's context at session start, and it establishes the single most important rule of the entire system:
  182. ```bash
  183. <EXTREMELY-IMPORTANT>
  184. If you think there is even a 1% chance a skill might apply to
  185. what you are doing, you ABSOLUTELY MUST invoke the skill.
  186. IF A SKILL APPLIES TO YOUR TASK, YOU DO NOT HAVE A CHOICE.
  187. YOU MUST USE IT.
  188. This is not negotiable. This is not optional. You cannot
  189. rationalize your way out of this.
  190. </EXTREMELY-IMPORTANT>
  191. ```
  192. This is the **1% Rule**, and it’s the foundation everything else is built on. Without it, agents treat skills as suggestions. They skip the brainstorming phase because the task “seems simple”. They skip TDD because “this is just a config change.” They skip code review because “it’s only two lines”.
  193. > Every senior engineer has watched a team slowly abandon their processes through exactly these rationalizations, and the result is always the same: quality degrades, bugs ship, and everyone wonders what happened.
  194. The skill must also includes an escape valve for sub-agents. When the main agent dispatches a focused sub-agent to implement a specific task, that sub-agent doesn’t need to go through the full skill discovery flow:
  195. ```bash
  196. <SUBAGENT-STOP>
  197. If you were dispatched as a subagent to execute a specific task,
  198. skip this skill.
  199. </SUBAGENT-STOP>
  200. ```
  201. This is the organizational equivalent of telling a contractor **“you don’t need to attend our all-hands meetings, just do the work you were hired for”**. The main agent follows the full process. Sub-agents stay focused.
  202. #### Instruction Priority (Chain of Command)
  203. Every organization has a chain of command, and conflicts between levels must have clear resolution rules. The skill defines three levels:
  204. ```bash
  205. ## Instruction Priority
  206. 1. **Users explicit instructions** (CLAUDE.md, direct requests)
  207. - highest priority
  208. 2. **senior_tech_engineers skills** - override default system
  209. behavior where they conflict
  210. 3. **Default system prompt** - lowest priority
  211. If CLAUDE.md says "don't use TDD" and a skill says "always use
  212. TDD," follow the users instructions. The user is in control.
  213. ```
  214. The human (the VP, the founder, the product owner) always has final authority. In real companies, this is the difference between a process-driven culture and a bureaucracy.
  215. 1. Process-driven cultures follow processes because they produce better outcomes, but they override processes when the situation demands it.
  216. 2. Bureaucracies follow processes blindly, even when they’re producing bad outcomes.
  217. #### The Skill Discovery Flow
  218. The handbook includes a flowchart that defines exactly how the agent should check for and invoke skills before responding to any message. The flow is: receive message, check if any skill might apply (even 1% chance), invoke the skill if so, announce what skill is being used, follow the skill’s checklist or instructions, and only then respond.
  219. ![Skill discovery](https://miro.medium.com/v2/resize:fit:2400/1*bFGgPZvMh-cPaZvng4BiIg.png)
  220. *Skill discovery (Created by [Fareed Khan](https://medium.com/u/b856005e5ecd))*
  221. What makes this effective is the **red flags table**, a list of thoughts that indicate the agent is rationalizing its way out of following the process:
  222. ```bash
  223. | Thought | Reality |
  224. |---------|---------|
  225. | "This is just a simple question" | Questions are tasks. Check for skills. |
  226. | "I need more context first" | Skill check comes BEFORE clarifying questions. |
  227. | "Let me explore the codebase first" | Skills tell you HOW to explore. Check first. |
  228. | "This doesn't need a formal skill" | If a skill exists, use it. |
  229. | "I remember this skill" | Skills evolve. Read current version. |
  230. | "The skill is overkill" | Simple things become complex. Use it. |
  231. | "This feels productive" | Undisciplined action wastes time. |
  232. ```
  233. Every item in this table came from actual testing where agents tried to skip skills. “This is just a simple question” is the most common one. The agent decides the task is trivial, skips the skill, and misses something important.
  234. > In real teams, this is the developer who says “it’s just a one-line change” and deploys without testing, only to take down production because that one line had a side effect nobody anticipated.
  235. The handbook also defines **skill priority** when multiple skills could apply:
  236. ```bash
  237. ## Skill Priority
  238. 1. **Process skills first** (brainstorming, debugging) - these
  239. determine HOW to approach the task
  240. 2. **Implementation skills second** (frontend-design, mcp-builder)
  241. - these guide execution
  242. "Let's build X" → brainstorming first, then implementation skills.
  243. "Fix this bug" → debugging first, then domain-specific skills.
  244. ```
  245. And a distinction between **rigid** and **flexible** skills:
  246. ```bash
  247. **Rigid** (TDD, debugging): Follow exactly. Dont adapt away
  248. discipline.
  249. **Flexible** (patterns): Adapt principles to context.
  250. The skill itself tells you which.
  251. ```
  252. You adapt brainstorming techniques to the problem at hand. The key insight is that the skill itself declares which category it belongs to, removing the agent’s ability to reclassify a rigid skill as flexible when it wants to cut corners.
  253. Finally, the handbook addresses a subtle rationalization that agents (and humans) use constantly:
  254. ```bash
  255. ## User Instructions
  256. Instructions say WHAT, not HOW. "Add X" or "Fix Y" doesnt
  257. mean skip workflows.
  258. ```
  259. 1. When a user says “add a login page”, the agent might think “they told me what to build, so I should just build it.”
  260. 2. But “add a login page” is the WHAT. The HOW is still brainstorm, design, plan, implement with TDD, review, and deploy. The user’s instruction doesn’t override the process. It feeds into it.
  261. Now that we have set up the management infrastructure, the onboarding flow, and the cultural handbook, we can start building the actual skills that will allow our senior staff engineer agent to perform its tasks effectively.
  262. ## Brainstorming & Design (Planning Phase)
  263. There is a moment before any code exists where the most important work happens. At Amazon, they write the press release before building the product. At Basecamp, they write the pitch document. At Google, they write design docs that get reviewed by three levels of engineers before a single function is defined.
  264. > The common thread is that **thinking happens before building**.
  265. ![Brainstorm and ideas](https://miro.medium.com/v2/resize:fit:2000/1*rkFzhXBl9Uq3wDYHzydOwA.png)
  266. *Brainstorm and ideas (Created by [Fareed Khan](https://medium.com/u/b856005e5ecd))*
  267. The reason is simple and expensive to learn. **Every senior staff engineer has a story about the project that skipped the design phase**. Someone said “this is straightforward, let’s just start coding”. Three weeks later, the team is halfway through an implementation that doesn’t match what the stakeholders wanted, the architecture can’t support the requirements nobody asked about, and the rewrite costs more than the original estimate for the entire project.
  268. At companies like Stripe, staff engineers are explicitly expected to be the person who says **“stop typing and start thinking.”** Not because thinking is fun (engineers want to code), but because an hour of design prevents a week of rework. The brainstorming skill encodes this discipline.
  269. `skills/brainstorming/SKILL.md` opens with the design equivalent of the TDD Iron Law:
  270. ```sql
  271. <HARD-GATE>
  272. Do NOT invoke any implementation skill, write any code, scaffold
  273. any project, or take any implementation action until you have
  274. presented a design and the user has approved it. This applies to
  275. EVERY project regardless of perceived simplicity.
  276. </HARD-GATE>
  277. ```
  278. **This is a hard gate, not a suggestion**. The agent physically cannot proceed to coding until a design exists and the human has approved it. In organizational terms, this is the staff engineer standing between the developers and the codebase saying **“show me the design doc first”**.
  279. #### The “Too Simple” Trap
  280. We need to have a skill to address the most dangerous rationalization in all of software engineering:
  281. ```bash
  282. ## Anti-Pattern: "This Is Too Simple To Need A Design"
  283. Every project goes through this process. A todo list, a
  284. single-function utility, a config change — all of them. "Simple"
  285. projects are where unexamined assumptions cause the most wasted
  286. work. The design can be short (a few sentences for truly simple
  287. projects), but you MUST present it and get approval.
  288. ```
  289. Every senior engineer has learned this lesson the hard way. The “simple” config change that turned out to affect three services.
  290. 1. The “quick” utility function that needed to handle seven edge cases nobody mentioned.
  291. 2. The “trivial” todo app that actually needed offline sync, conflict resolution, and multi-user support.
  292. Simple projects are where unexamined assumptions hide, precisely because nobody stops to examine them.
  293. The design can be proportional to the complexity. A config change might get a two-sentence design. A payment system gets a multi-page spec. But the process of stopping, thinking, and getting approval happens every time.
  294. #### The Design Checklist
  295. The skill provides a nine-step checklist that mirrors how real product teams operate. In a company, this would be the flow from kickoff meeting through design review to sprint planning:
  296. ```bash
  297. ## Checklist
  298. 1. **Explore project context** - check files, docs, recent commits
  299. 2. **Offer visual companion** (if topic will involve visual
  300. questions)
  301. 3. **Ask clarifying questions** - one at a time, understand
  302. purpose/constraints/success criteria
  303. 4. **Propose 2-3 approaches** - with trade-offs and your
  304. recommendation
  305. 5. **Present design** - in sections scaled to complexity, get
  306. user approval after each section
  307. 6. **Write design doc** - save to docs/senior-staff-engineer/specs/ and commit
  308. 7. **Spec self-review** - check for placeholders, contradictions,
  309. ambiguity
  310. 8. **User reviews written spec** - ask user to review before
  311. proceeding
  312. 9. **Transition to implementation** - invoke writing-plans skill
  313. ```
  314. Step 1 is what a staff engineer does before any meeting. They don’t walk into the design discussion cold. They read the existing code, check recent commits, look at documentation. They build context so their questions are informed, not redundant.
  315. Steps 3 and 4 mirror the actual product design meeting. The architect asks questions one at a time (not a wall of 15 questions that overwhelms the stakeholder), proposes multiple approaches with trade-offs, and leads with a recommendation. This is how senior engineers run meetings.
  316. > They don’t ask “what do you want?” They say “here are three options, I recommend option B because of X and Y, what do you think?”
  317. The skill is specific about question design:
  318. ```bash
  319. - Ask questions one at a time to refine the idea
  320. - Prefer multiple choice questions when possible
  321. - Only one question per message
  322. - Focus on understanding: purpose, constraints, success criteria
  323. ```
  324. One question per message. Not five. **Not “here are a few things I’m wondering about.”** One. This mirrors how the product managers run stakeholder interviews. Each question gets full attention, full context, and a complete answer before moving to the next topic.
  325. #### Scope Detection
  326. Before looking into detailed questions, the skill requires a scope assessment that separates staff-level thinking from junior-level thinking:
  327. ```bash
  328. Before asking detailed questions, assess scope: if the request
  329. describes multiple independent subsystems (e.g., "build a platform
  330. with chat, file storage, billing, and analytics"), flag this
  331. immediately.
  332. Dont spend questions refining details of a project that needs to be decomposed first.
  333. ```
  334. **A junior engineer hears “build a platform with chat, file storage, billing, and analytics”** and starts asking about chat message formatting. A staff engineer hears that same request and says **“that’s four separate systems. Let’s figure out which one to build first and how they relate before we design any of them.”**
  335. > This is **decomposition**, the ability to recognize when a project is actually multiple projects wearing a trenchcoat.
  336. #### Design for Isolation
  337. The skill includes architectural guidance that reflects how senior engineers think about system design:
  338. ![Isolation Design](https://miro.medium.com/v2/resize:fit:2400/1*f6SabTkhBVRhr_UGOYCq0g.png)
  339. *Isolation Design (Created by [Fareed Khan](https://medium.com/u/b856005e5ecd))*
  340. ```bash
  341. - Break the system into smaller units that each have one clear
  342. purpose, communicate through well-defined interfaces, and can
  343. be understood and tested independently
  344. - For each unit, you should be able to answer: what does it do,
  345. how do you use it, and what does it depend on?
  346. - Can someone understand what a unit does without reading its
  347. internals? Can you change the internals without breaking
  348. consumers? If not, the boundaries need work.
  349. ```
  350. These are the questions a staff engineer asks during every architecture review.
  351. 1. “Can I understand this component without reading its source code?” is the test for good abstraction.
  352. 2. “Can I change the internals without breaking consumers?” is the test for good encapsulation.
  353. If either answer is no, the design needs work before anyone starts implementing.
  354. There’s also a practical note about working in existing codebases that separates experienced engineers from idealistic ones:
  355. ```bash
  356. Where existing code has problems that affect the work (e.g., a
  357. file thats grown too large, unclear boundaries), include targeted
  358. improvements as part of the design — the way a good developer
  359. improves code they are working in.
  360. Dont propose unrelated refactoring. Stay focused on what serves
  361. the current goal.
  362. ```
  363. A junior engineer sees messy code and wants to rewrite everything. A staff engineer improves what they’re touching and leaves the rest alone. Targeted improvement, not crusade-driven refactoring.
  364. #### After the Design
  365. Once the design is verbally approved, it gets written down, reviewed, and committed. This mirrors how mature engineering organizations handle design documents. The design isn’t just a conversation that happened in a meeting room and lives in everyone’s imperfect memory. It’s a document that lives in version control:
  366. ```bash
  367. - Write the validated design (spec) to
  368. `docs/senior-staff-engineer/specs/YYYY-MM-DD-<topic>-design.md`
  369. - Commit the design document to git
  370. ```
  371. The spec then goes through a self-review that catches the most common documentation failures:
  372. ```bash
  373. **Spec Self-Review:**
  374. 1. **Placeholder scan:** Any "TBD", "TODO", incomplete sections?
  375. 2. **Internal consistency:** Do any sections contradict each other?
  376. 3. **Scope check:** Focused enough for a single implementation plan?
  377. 4. **Ambiguity check:** Could any requirement be interpreted two
  378. different ways? If so, pick one and make it explicit.
  379. ```
  380. And then a **user review gate** that prevents the system from proceeding without explicit human approval:
  381. ```bash
  382. "Spec written and committed to `<path>`. Please review it and
  383. let me know if you want to make any changes before we start
  384. writing out the implementation plan."
  385. Wait for the users response. Only proceed once the user approves.
  386. ```
  387. This is the design review sign-off. **At companies like Microsoft and Google, design docs require explicit approval from reviewers before implementation begins**. Not implicit approval (“nobody objected, so I guess we are good”). Explicit. “I reviewed this and it’s ready.” Our system follows the same standard.
  388. The terminal state of the brainstorming skill is always the same: invoke `writing-plans` to create the implementation plan. Not jump to coding. Not start building. Create the plan. The design flows into planning, planning flows into implementation. Each phase feeds the next. No shortcuts.
  389. ```vbnet
  390. **Implementation:**
  391. - Invoke the writing-plans skill to create a detailed
  392. implementation plan
  393. - Do NOT invoke any other skill. writing-plans is the next step.
  394. ```
  395. #### Visual Option
  396. Some design conversations need more than words. When the discussion involves UI layouts, architecture diagrams, or visual comparisons, the agent can offer a browser-based companion for showing mockups and diagrams:
  397. ```bash
  398. "Some of what we're working on might be easier to explain if I
  399. can show it to you in a web browser. I can put together mockups,
  400. diagrams, comparisons, and other visuals as we go. Want to try it?"
  401. ```
  402. The skill is careful about how this offer is made:
  403. ```bash
  404. **This offer MUST be its own message.** Do not combine it with
  405. clarifying questions, context summaries, or any other content.
  406. Wait for the users response before continuing. If they decline,
  407. proceed with text-only brainstorming.
  408. ```
  409. And even after the user accepts, the agent decides per-question whether to use visuals or text:
  410. ```bash
  411. A question about a UI topic is not automatically a visual question.
  412. "What does personality mean in this context?" is a conceptual
  413. question — use the terminal.
  414. "Which wizard layout works better?"
  415. is a visual question — use the browser.
  416. ```
  417. This is the senior engineer’s instinct for communication medium. Some things are better explained with words. Some things need a whiteboard. The skill teaches the agent to make that judgment call on every question, not default to one medium for the entire conversation.
  418. ## Finding Logical Loopholes (Spec Review)
  419. In any engineering org, the architect doesn’t just design a system and walk away. There’s always that one senior who sits in the design review and says **“what happens when the database is down and the user retries three times?”** the person whose job is to poke holes before a single line of code gets written.
  420. ![Logical Loopholes](https://miro.medium.com/v2/resize:fit:2000/1*Hw-iGaQ_oJun0lNPPbv8eA.png)
  421. *Logical Loopholes (Created by [Fareed Khan](https://medium.com/u/b856005e5ecd))*
  422. We replicate this role with `skills/brainstorming/spec-document-reviewer-prompt.md`. This isn't a skill the main agent uses directly, it's a **prompt template that gets dispatched to a separate sub-agent**. Think of it as hiring a freelance auditor to review the architect's blueprints.
  423. The key insight is **separation of concerns**.
  424. > The agent that wrote the design is biased, it’s proud of its work. So we spin up a *completely fresh* Claude with one job: tear the spec apart.
  425. ```bash
  426. Task tool (general-purpose):
  427. description: "Review spec document"
  428. prompt: |
  429. You are a spec document reviewer. Verify this spec is complete
  430. and ready for planning.
  431. **Spec to review:** [SPEC_FILE_PATH]
  432. ```
  433. The reviewer checks against a focused set of categories:
  434. ```vbnet
  435. | Category | What to Look For |
  436. |---------------|------------------|
  437. | Completeness | TODOs, placeholders, "TBD", incomplete sections |
  438. | Consistency | Internal contradictions, conflicting requirements |
  439. | Clarity | Requirements ambiguous enough to cause someone to build the wrong thing |
  440. | Scope | Focused enough for a single plan — not covering multiple independent subsystems |
  441. | YAGNI | Unrequested features, over-engineering |
  442. ```
  443. Notice how each category maps to a real-world design review concern. Completeness is **“did you finish the design?”** Consistency is **“does page 3 contradict page 7?”** Clarity is **“could two developers read this and build two different things?”** And YAGNI You Ain’t Gonna Need It is the senior engineer saying **“why are we designing a plugin system when we have one client?”**
  444. What makes this reviewer disciplined rather than nitpicky is the **calibration** section:
  445. ```bash
  446. Only flag issues that would cause real problems during
  447. implementation planning.
  448. A missing section, a contradiction, or a requirement so ambiguous
  449. it could be interpreted two different ways — those are issues.
  450. Minor wording improvements, stylistic preferences, and "sections
  451. less detailed than others" are not.
  452. Approve unless there are serious gaps that would lead to a
  453. flawed plan.
  454. ```
  455. This is critical. In real orgs, the worst reviewers are the ones who block a design over comma placement. Our reviewer is calibrated to only flag things that would **actually cause problems downstream**, a missing error handling strategy, a contradiction between two requirements, a scope so broad it can’t be planned in a single sprint.
  456. > This mirrors the real design review flow: the auditor reviews, files their report, and the architect decides what to act on before moving to planning.
  457. ## Visual Companion (Whiteboarding Sessions)
  458. Every senior engineer knows that some problems can’t be solved with words alone. When you are debating whether to use a sidebar layout or a top-nav, nothing beats drawing it on a whiteboard. In our system, we bring this to the agent with `skills/brainstorming/visual-companion.md` and the supporting `scripts/` directory.
  459. ![Visual Understanding](https://miro.medium.com/v2/resize:fit:2000/1*7HgzkuYGEgHkuubVdXMF2A.png)
  460. *Visual Understanding (Created by [Fareed Khan](https://medium.com/u/b856005e5ecd))*
  461. The visual companion isn’t always-on it’s offered per-question during brainstorming. The decision rule is simple:
  462. ```kotlin
  463. Decide per-question, not per-session. The test: **would the user
  464. understand this better by seeing it than reading it?**
  465. ```
  466. The file draws a clear line between what belongs in the browser and what belongs in the terminal:
  467. ```markdown
  468. **Use the browser** when the content itself is visual:
  469. - UI mockups wireframes, layouts, navigation structures
  470. - Architecture diagrams system components, data flow
  471. - Side-by-side visual comparisons two layouts, two color schemes
  472. - Spatial relationships state machines, flowcharts, entity relationships
  473. **Use the terminal** when the content is text or tabular:
  474. - Requirements and scope questions
  475. - Conceptual A/B/C choices described in words
  476. - Tradeoff lists pros/cons, comparison tables
  477. - Technical decisions API design, data modeling
  478. ```
  479. There’s a simple but important distinction here. A question *about* a UI topic isn’t automatically a visual question. **“What kind of wizard do you want?”** is conceptual terminal. **“Which of these wizard layouts feels right?”** is visual browser.
  480. > In a real team, the senior engineer knows when to keep talking and when to stand up and walk to the whiteboard. This skill teaches the agent the same instinct.
  481. #### How It Works
  482. The technology is a lightweight local server that watches a directory for HTML files and serves the newest one to your browser.
  483. ```shell
  484. # Start server with persistence
  485. scripts/start-server.sh --project-dir /path/to/project
  486. # Returns: {"type":"server-started","port":52341,
  487. # "url":"http://localhost:52341",
  488. # "screen_dir":"...content", "state_dir":"...state"}
  489. ```
  490. 1. The agent writes HTML content fragments to `screen_dir`.
  491. 2. User sees them in their browser and can click to select options, and those selections are recorded to `state_dir/events` as JSON lines that the agent reads on its next turn.
  492. The key design decision is **content fragments vs full documents**. The agent doesn’t need to write full HTML pages it writes just the content, and the server wraps it in a frame template with theming, CSS, and interactive infrastructure automatically:
  493. ```xml
  494. <h2>Which layout works better?</h2>
  495. <p class="subtitle">Consider readability and visual hierarchy</p>
  496. <div class="options">
  497. <div class="option" data-choice="a" onclick="toggleSelect(this)">
  498. <div class="letter">A</div>
  499. <div class="content">
  500. <h3>Single Column</h3>
  501. <p>Clean, focused reading experience</p>
  502. </div>
  503. </div>
  504. <div class="option" data-choice="b" onclick="toggleSelect(this)">
  505. <div class="letter">B</div>
  506. <div class="content">
  507. <h3>Two Column</h3>
  508. <p>Sidebar navigation with main content</p>
  509. </div>
  510. </div>
  511. </div>
  512. ```
  513. No `<html>`, no CSS, no `<script>` tags. The server provides all of that. This is important because it keeps the agent focused on **_what to show_, not on boilerplate.**
  514. #### The Feedback Loop
  515. The interaction follows a loop that mirrors real whiteboarding sessions draw, discuss, revise:
  516. ![Feedback loop](https://miro.medium.com/v2/resize:fit:2400/1*8H71NUljflZONfWhL59eMQ.png)
  517. *Feedback loop (Created by [Fareed Khan](https://medium.com/u/b856005e5ecd))*
  518. 1. **Write HTML** to a new file in `screen_dir` with a semantic name like `layout.html`
  519. 2. **Tell the user** what’s on screen and ask for feedback
  520. 3. **Read `state_dir/events`** on the next turn to see what they clicked
  521. 4. **Iterate or advance** if feedback changes current screen, write `layout-v2.html`. Only move to the next question when this step is validated.
  522. When the user clicks options in the browser, their full exploration path is captured:
  523. ```json
  524. {"type":"click","choice":"a","text":"Option A","timestamp":1706000101}
  525. {"type":"click","choice":"c","text":"Option C","timestamp":1706000108}
  526. {"type":"click","choice":"b","text":"Option B","timestamp":1706000115}
  527. ```
  528. The pattern of clicks reveals hesitation they tried A, jumped to C, then settled on B. A good senior engineer would notice that and ask “you seemed drawn to A initially, what made you switch?” The agent can do the same.
  529. There’s one more detail that shows real engineering discipline when the conversation moves back to the terminal for a non-visual question, the agent pushes a waiting screen:
  530. ```xml
  531. <div style="display:flex;align-items:center;justify-content:center;min-height:60vh">
  532. <p class="subtitle">Continuing in terminal...</p>
  533. </div>
  534. ```
  535. This prevents the user from staring at a resolved choice while the conversation has moved on. It’s a small thing, but it’s the kind of polish that separates a senior engineer’s tooling from a junior’s hack.
  536. ## Writing Plans (Backlog Grooming)
  537. In agile teams, there is a term called **“backlog grooming”** where the tech lead takes the approved architecture and breaks it down into tickets so clear that any developer could pick one up and start working without asking a single question. This is exactly what `skills/writing-plans/SKILL.md` does.
  538. ![Writing Plans](https://miro.medium.com/v2/resize:fit:2000/1*yVox0dQpkyNrxmBTOfRdpQ.png)
  539. *Writing Plans (Created by [Fareed Khan](https://medium.com/u/b856005e5ecd))*
  540. The opening line sets the philosophy:
  541. ```vbnet
  542. Write comprehensive implementation plans assuming the engineer has
  543. zero context for our codebase and questionable taste. Document
  544. everything they need to know: which files to touch for each task,
  545. code, testing, docs they might need to check, how to test it.
  546. ```
  547. **“Zero context and questionable taste”** that’s how a senior tech lead thinks about ticket writing. You don’t assume the developer has been in the standup for the last three weeks. You don’t assume they will make good decisions about error handling on their own.
  548. > You write the ticket so a skilled developer who just joined the team today could execute it perfectly.
  549. Before defining any tasks, the skill requires a **file structure mapping** deciding which files will be created or modified and what each one is responsible for:
  550. ```bash
  551. ## File Structure
  552. - Design units with clear boundaries and well-defined interfaces.
  553. Each file should have one clear responsibility.
  554. - Files that change together should live together. Split by
  555. responsibility, not by technical layer.
  556. - In existing codebases, follow established patterns.
  557. ```
  558. This is the tech lead saying **“before we write tickets, let’s agree on where things live.”** No developer should be guessing whether the validation logic goes in the controller or the service layer.
  559. #### The 2–5 Minute Rule
  560. The granularity requirement is where this gets disciplined:
  561. ```bash
  562. ## Bite-Sized Task Granularity
  563. **Each step is one action (2-5 minutes):**
  564. - "Write the failing test" - step
  565. - "Run it to make sure it fails" - step
  566. - "Implement the minimal code to make the test pass" - step
  567. - "Run the tests and make sure they pass" - step
  568. - "Commit" - step
  569. ```
  570. 1. If a task takes longer than 5 minutes for a sub-agent, it means the task is too broad and the agent will start making assumptions or losing focus.
  571. 2. This mirrors the real-world practice of keeping tickets small enough to complete in a single sitting without context-switching.
  572. Every task must include exact file paths, complete code blocks, exact commands with expected output, and a commit step. No hand-waving:
  573. ```bash
  574. ### Task N: [Component Name]
  575. **Files:**
  576. - Create: `exact/path/to/file.py`
  577. - Modify: `exact/path/to/existing.py:123-145`
  578. - Test: `tests/exact/path/to/test.py`
  579. - [ ] **Step 1: Write the failing test**
  580. ```python
  581. def test_specific_behavior():
  582. result = function(input)
  583. assert result == expected
  584. ```
  585. - [ ] **Step 2: Run test to verify it fails**
  586. Run: `pytest tests/path/test.py::test_name -v`
  587. Expected: FAIL with "function not defined"
  588. ```
  589. The skill enforces a strict **no-TBD policy** and it’s specific about what counts as a placeholder:
  590. ```bash
  591. These are **plan failures** — never write them:
  592. - "TBD", "TODO", "implement later", "fill in details"
  593. - "Add appropriate error handling" / "add validation"
  594. - "Write tests for the above" (without actual test code)
  595. - "Similar to Task N" (repeat the code — the engineer may be
  596. reading tasks out of order)
  597. - References to types, functions, or methods not defined in any task
  598. ```
  599. That last one is subtle. If Task 7 calls `clearFullLayers()` but Task 3 defined it as `clearLayers()`, that's a bug in the plan and the self-review step catches it:
  600. ```sql
  601. **3. Type consistency:** Do the types, method signatures, and
  602. property names you used in later tasks match what you defined in
  603. earlier tasks?
  604. ```
  605. Plans are saved to `docs/senior-staff-engineer/plans/` and once complete, the agent offers two execution paths, subagent-driven (recommended) or inline execution.
  606. > Think of this as the tech lead asking "do we want specialists on each ticket, or one developer doing a marathon?"
  607. ## Plan Review (The Grooming Gatekeeper)
  608. Just as we had a spec reviewer for designs, we have a plan reviewer for implementation plans. The `skills/writing-plans/plan-document-reviewer-prompt.md` dispatches a fresh sub-agent to answer one question: **could an engineer actually follow this plan without getting stuck?**
  609. ![Plan review](https://miro.medium.com/v2/resize:fit:2000/1*ZjAoH4t1vmxHuUr1KSBqqg.png)
  610. *Plan review (Created by [Fareed Khan](https://medium.com/u/b856005e5ecd))*
  611. ```bash
  612. You are a plan document reviewer. Verify this plan is complete
  613. and ready for implementation.
  614. **Plan to review:** [PLAN_FILE_PATH]
  615. **Spec for reference:** [SPEC_FILE_PATH]
  616. ```
  617. Notice it takes both the plan AND the spec as inputs. The reviewer checks four things:
  618. ```bash
  619. | Category | What to Look For |
  620. |--------------------|------------------|
  621. | Completeness | TODOs, placeholders, incomplete tasks |
  622. | Spec Alignment | Plan covers spec requirements, no scope creep |
  623. | Task Decomposition | Tasks have clear boundaries, steps actionable |
  624. | Buildability | Could an engineer follow this without getting stuck? |
  625. ```
  626. **“Buildability”** is the one that matters most.
  627. 1. A plan can be complete, aligned with the spec, and well-decomposed but if Step 4 assumes something that Step 3 didn’t produce, the developer is stuck.
  628. 2. This is the moment in a real sprint planning meeting where the project manager opens the requirements doc side-by-side with the ticket board and says **“show me which ticket covers requirement #7.”**
  629. Same calibration philosophy as the spec reviewer only flag things that would cause real problems:
  630. ```bash
  631. Approve unless there are serious gaps — missing requirements
  632. from the spec, contradictory steps, placeholder content, or
  633. tasks so vague they cant be acted on.
  634. ```
  635. The reviewer returns a clean `Approved` or `Issues Found` status, with issues tied to specific tasks and steps. If the plan has gaps, the tech lead goes back and fills them before any developer starts working.
  636. ## Subagent-Driven Development (Delegation)
  637. In a engineering org, a manager doesn’t write all the code themselves. They hire specialists, give them clear instructions, check their work, and manage handoffs. `skills/subagent-driven-development/SKILL.md` is exactly this workflow encoded as a system.
  638. ![Subagent delegation](https://miro.medium.com/v2/resize:fit:2000/1*wL-1GWdoP8eLvl2IrYjf1Q.png)
  639. *Subagent delegation (Created by [Fareed Khan](https://medium.com/u/b856005e5ecd))*
  640. The opening principle:
  641. ```vbnet
  642. **Why subagents:** You delegate tasks to specialized agents with
  643. isolated context. By precisely crafting their instructions and
  644. context, you ensure they stay focused and succeed at their task.
  645. They should never inherit your sessions context or history you
  646. construct exactly what they need.
  647. ```
  648. This is **context isolation**. When a human developer picks up a ticket, they don’t need the entire company history they need the ticket, the relevant code, and the coding standards. Same here. Fresh agent, clean mind, focused task.
  649. > This prevents the “confused senior” problem where an agent that’s been working for an hour starts mixing up requirements from different features.
  650. The process follows a per-task loop: **dispatch implementer → spec review → code quality review → mark complete**. The skill lays this out as a digraph, but in human terms it’s the daily rhythm of any well-run team: assign work, check it was built to spec, check it was built well, move on.
  651. #### Model Selection (Hiring the Right Level)
  652. This is where the manager metaphor gets practical. You don’t send a principal engineer to rename a variable:
  653. ```bash
  654. ## Model Selection
  655. **Mechanical implementation tasks** (isolated functions, clear specs,
  656. 1-2 files): use a fast, cheap model.
  657. **Integration and judgment tasks** (multi-file coordination, pattern
  658. matching, debugging): use a standard model.
  659. **Architecture, design, and review tasks**: use the most capable
  660. available model.
  661. ```
  662. This is the difference between assigning a ticket to a junior, a mid-level, or a senior. The manager matches task complexity to capability and to cost. A well-specified plan means most tasks are “mechanical,” which means cheap and fast.
  663. #### Handling Failure
  664. The most revealing part of any management system is how it handles failure. The skill defines four statuses an implementer can return:
  665. ![Handling Failure](https://miro.medium.com/v2/resize:fit:2000/1*UJdnMA_0ZPa1iK_K46512A.png)
  666. *Handling Failure (Created by [Fareed Khan](https://medium.com/u/b856005e5ecd))*
  667. ```bash
  668. **DONE:** Proceed to spec compliance review.
  669. **DONE_WITH_CONCERNS:** The implementer completed the work but
  670. flagged doubts. Read the concerns before proceeding.
  671. **NEEDS_CONTEXT:** The implementer needs information that wasnt
  672. provided. Provide the missing context and re-dispatch.
  673. **BLOCKED:** The implementer cannot complete the task.
  674. ```
  675. And the critical rule:
  676. ```vbnet
  677. **Never** ignore an escalation or force the same model to retry
  678. without changes. If the implementer said it's stuck, something
  679. needs to change.
  680. ```
  681. The worst managers are the ones who respond to **“I’m stuck”** with **“just try harder.”** Our system explicitly forbids this. If the agent is stuck, the manager has three options: provide more context, upgrade the model, or break the task down further. **If the plan itself is wrong, escalate to the human. This is mature management.**
  682. ## The Implementer Prompt (Developer Job Description)
  683. When a company hires a developer, there’s an onboarding document, coding standards, and a first task. `skills/subagent-driven-development/implementer-prompt.md` is exactly this the job description every sub-agent receives.
  684. ![Developer Job agent](https://miro.medium.com/v2/resize:fit:2000/1*xzQFBTVV_eHm9pAjEobqxw.png)
  685. *Developer Job agent (Created by [Fareed Khan](https://medium.com/u/b856005e5ecd))*
  686. The prompt starts with something most AI systems skip entirely:
  687. ```bash
  688. ## Before You Begin
  689. If you have questions about:
  690. - The requirements or acceptance criteria
  691. - The approach or implementation strategy
  692. - Dependencies or assumptions
  693. - Anything unclear in the task description
  694. **Ask them now.** Raise any concerns before starting work.
  695. ```
  696. And reinforced during implementation:
  697. ```bash
  698. **While you work:** If you encounter something unexpected or
  699. unclear, **ask questions**. Its always OK to pause and clarify.
  700. Dont guess or make assumptions.
  701. ```
  702. The “don’t guess” rule is perhaps the most important line in the entire codebase.
  703. > **In orgs, the most expensive mistakes come from developers who *assumed* they knew what was needed**.
  704. A sub-agent that stops and says “I’m unclear on null handling” costs five minutes. One that guesses wrong costs an hour of rework.
  705. There’s also an explicit permission to fail:
  706. ```bash
  707. ## When You're in Over Your Head
  708. It is always OK to stop and say "this is too hard for me."
  709. Bad work is worse than no work. You will not be penalized
  710. for escalating.
  711. ```
  712. This mirrors the psychological safety that good engineering cultures build.
  713. > A junior who says “I don’t understand this” on day two is far more valuable than one who silently builds the wrong thing for a week.
  714. Before reporting back, the implementer runs a **self-review** across four dimensions completeness, quality, discipline, and testing. Then reports with a structured status. **No ambiguity about what was done, what was tested, or what concerns remain.**
  715. ## Spec & Code Quality Reviewers (Compliance Officers)
  716. After the implementer finishes, work goes through two separate review sub-agents. The order matters spec compliance first, code quality second. You don’t polish code that builds the wrong thing.
  717. ![Code Quality Review](https://miro.medium.com/v2/resize:fit:2000/1*B11xN8I4bhzpCF6qwfFYHw.png)
  718. *Code Quality Review (Created by [Fareed Khan](https://medium.com/u/b856005e5ecd))*
  719. #### Spec Compliance Reviewer
  720. The `spec-reviewer-prompt.md` opens with a line that tells you everything about how this system thinks:
  721. ```bash
  722. ## CRITICAL: Do Not Trust the Report
  723. The implementer finished suspiciously quickly. Their report may be
  724. incomplete, inaccurate, or optimistic. You MUST verify everything
  725. independently.
  726. **DO NOT:**
  727. - Take their word for what they implemented
  728. - Trust their claims about completeness
  729. - Accept their interpretation of requirements
  730. **DO:**
  731. - Read the actual code they wrote
  732. - Compare actual implementation to requirements line by line
  733. ```
  734. This is the compliance officer who doesn’t accept self-reported audit results. They check three things: **missing requirements (did they skip something?), extra work (did they over-engineer?), and misunderstandings (did they solve the wrong problem?).** Every finding comes with `file:line` references no vague feedback.
  735. #### Code Quality Reviewer
  736. The `code-quality-reviewer-prompt.md` only fires **after spec compliance passes**. It uses the standard code review template but adds implementation-specific checks:
  737. ![Code check](https://miro.medium.com/v2/resize:fit:2400/1*ud89CDsTt8aP4HMUFbLCzg.png)
  738. *Code check (Created by [Fareed Khan](https://medium.com/u/b856005e5ecd))*
  739. ```bash
  740. - Does each file have one clear responsibility with a well-defined
  741. interface?
  742. - Are units decomposed so they can be understood and tested
  743. independently?
  744. - Is the implementation following the file structure from the plan?
  745. - Did this implementation create new files that are already large?
  746. ```
  747. This two-pass review mirrors how real orgs separate functional review (“does it do the right thing?”) from technical review (“is it built the right way?”).
  748. > A feature can be functionally correct but architecturally terrible. You need both lenses.
  749. If either reviewer finds issues, the implementer fixes them and the reviewer checks again. The loop repeats until approved. No **“close enough”**. No skipping the re-review. This is how disciplined teams ship.
  750. ## Test-Driven Development (The Iron Law)
  751. In every serious engineering organization Google, Microsoft, Stripe, Shopify there’s one rule that separates the professionals from the hobbyists.
  752. > It’s not about which framework you use or how clever your algorithms are. It’s about **discipline under pressure**.
  753. ![Test-driven](https://miro.medium.com/v2/resize:fit:2000/1*rq5leQylpXPZYqkXmBOjCQ.png)
  754. *Test-driven (Created by [Fareed Khan](https://medium.com/u/b856005e5ecd))*
  755. At Google, they call it “testing culture.” At Stripe, they call it “production readiness.” In our system, we call it the Iron Law:
  756. ```bash
  757. NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST
  758. ```
  759. `skills/test-driven-development/SKILL.md` is the most uncompromising file in the entire codebase. **It's the grumpy senior who's been burned by production outages at 3 AM and refuses to let anyone ship untested code ever again.**
  760. The core principle is one line:
  761. ```bash
  762. **Core principle:** If you didnt watch the test fail, you dont
  763. know if it tests the right thing.
  764. ```
  765. Think about that. If you write a test after the code and it passes immediately, what did you prove? Nothing. The test might be testing the wrong thing entirely.
  766. You never know because you never saw it catch anything. It’s like installing a smoke detector and never checking if the battery works.
  767. #### The Cycle
  768. The skill enforces the classic Red-Green-Refactor cycle, but with verification gates that most teams skip:
  769. **RED** write one minimal failing test:
  770. ```javascript
  771. test('retries failed operations 3 times', async () => {
  772. let attempts = 0;
  773. const operation = () => {
  774. attempts++;
  775. if (attempts < 3) throw new Error('fail');
  776. return 'success';
  777. };
  778. const result = await retryOperation(operation);
  779. expect(result).toBe('success');
  780. expect(attempts).toBe(3);
  781. });
  782. ```
  783. Then **verify it fails** and not just fails, fails *for the right reason*. A test that errors because of a typo is not a failing test. A test that fails because the feature doesn’t exist yet that’s what we want.
  784. **GREEN** write the simplest code that passes:
  785. ```javascript
  786. async function retryOperation<T>(fn: () => Promise<T>): Promise<T> {
  787. for (let i = 0; i < 3; i++) {
  788. try {
  789. return await fn();
  790. } catch (e) {
  791. if (i === 2) throw e;
  792. }
  793. }
  794. throw new Error('unreachable');
  795. }
  796. ```
  797. The skill is explicit about what “minimal” means by showing the anti-pattern over-engineering with configurable backoff strategies and retry callbacks when all the test asked for was “retry 3 times.” This is YAGNI enforced at the code level.
  798. #### The Delete Rule
  799. Here’s where the skill gets truly hardcore. Most TDD guides say “write tests first.” This one says:
  800. ```rust
  801. Write code before the test? Delete it. Start over.
  802. **No exceptions:**
  803. - Don't keep it as "reference"
  804. - Don't "adapt" it while writing tests
  805. - Don't look at it
  806. - Delete means delete
  807. ```
  808. In real companies, this is the moment where junior engineers push back. “But I spent three hours on that!” The skill addresses this directly:
  809. ```bash
  810. | Excuse | Reality |
  811. |--------|---------|
  812. | "Deleting X hours is wasteful" | Sunk cost fallacy. Keeping unverified code is technical debt. |
  813. | "Keep as reference, write tests first" | You will adapt it. Thats testing after. Delete means delete. |
  814. | "TDD will slow me down" | TDD faster than debugging. Pragmatic = test-first. |
  815. ```
  816. At Amazon, they have a saying: **“the most expensive bug is the one you ship.”** The time you **“save”** by skipping TDD, you pay back tenfold in production debugging, customer escalations, and 3 AM pages. Every senior staff engineer who’s been through a major outage knows this in their bones.
  817. #### Why Tests-After Isn’t The Same
  818. The most dangerous rationalization the skill fights against is “I’ll write tests after same result, right?” Wrong:
  819. ```bash
  820. Tests-after answer "What does this do?"
  821. Tests-first answer "What should this do?"
  822. Tests-after are biased by your implementation. You test what you
  823. built, not whats required. You verify remembered edge cases, not
  824. discovered ones.
  825. ```
  826. This is a profound insight about cognitive bias. When you write code first, your tests are shaped by what you built. You test the happy path you implemented, not the edge cases you forgot.
  827. Tests-first forces you to think about behavior before implementation **“what *should* happen when the email is empty?”** which surfaces edge cases you’d otherwise miss.
  828. ## Testing Anti-Patterns (Lazy QA Training)
  829. If TDD is the Iron Law, `skills/test-driven-development/testing-anti-patterns.md` is the training video every new hire watches on day one. It documents the specific ways engineers write tests that look good but prove nothing patterns that a senior staff engineer has seen destroy confidence in test suites across entire organizations.
  830. ![Anti-Patterns](https://miro.medium.com/v2/resize:fit:2000/1*MCX936lJPXtFEelibNYTCQ.png)
  831. *Anti-Patterns (Created by [Fareed Khan](https://medium.com/u/b856005e5ecd))*
  832. The file opens with three iron laws of its own:
  833. ```bash
  834. 1. NEVER test mock behavior
  835. 2. NEVER add test-only methods to production classes
  836. 3. NEVER mock without understanding dependencies
  837. ```
  838. #### Testing The Mock, Not The Code
  839. The first anti-pattern is the most common and most dangerous:
  840. ```javascript
  841. // ❌ BAD: Testing that the mock exists
  842. test('renders sidebar', () => {
  843. render(<Page />);
  844. expect(screen.getByTestId('sidebar-mock')).toBeInTheDocument();
  845. });
  846. ```
  847. You’re verifying the mock works, not that the component works. This test will pass forever even if the sidebar is completely broken in production because you’re testing the fake, not the real thing. It’s like testing your car by checking that the cardboard cutout of your car exists.
  848. The fix is straightforward test real behavior:
  849. ```javascript
  850. // ✅ GOOD: Test real component
  851. test('renders sidebar', () => {
  852. render(<Page />);
  853. expect(screen.getByRole('navigation')).toBeInTheDocument();
  854. });
  855. ```
  856. #### Polluting Production With Test Code
  857. The second anti-pattern is subtle and insidious. An engineer needs to clean up resources in tests, so they add a `destroy()` method to a production class:
  858. ```csharp
  859. // ❌ BAD: destroy() only used in tests
  860. class Session {
  861. async destroy() { // Looks like production API!
  862. await this._workspaceManager?.destroyWorkspace(this.id);
  863. }
  864. }
  865. ```
  866. The skill explains why this is dangerous **“Production class polluted with test-only code. Dangerous if accidentally called in production.”** The fix is to move cleanup logic to test utilities where it belongs:
  867. ```javascript
  868. // ✅ GOOD: Test utilities handle test cleanup
  869. export async function cleanupSession(session: Session) {
  870. const workspace = session.getWorkspaceInfo();
  871. if (workspace) {
  872. await workspaceManager.destroyWorkspace(workspace.id);
  873. }
  874. }
  875. ```
  876. In large organizations Netflix, Uber, Meta production code with test-only methods has caused real outages. Someone calls a method they thought was part of the API, and it tears down a live session.
  877. > The boundary between test code and production code must be absolute.
  878. #### The Gate Functions
  879. We need to make this file exceptional using the **gate functions** decision trees that the agent runs before every potentially dangerous action:
  880. ```bash
  881. BEFORE mocking any method:
  882. STOP - Dont mock yet
  883. 1. Ask: "What side effects does the real method have?"
  884. 2. Ask: "Does this test depend on any of those side effects?"
  885. 3. Ask: "Do I fully understand what this test needs?"
  886. IF depends on side effects:
  887. Mock at lower level (the actual slow/external operation)
  888. NOT the high-level method the test depends on
  889. IF unsure what test depends on:
  890. Run test with real implementation FIRST
  891. Observe what actually needs to happen
  892. THEN add minimal mocking at the right level
  893. ```
  894. This is how senior QA engineers at companies like **Thoughtworks** actually think. They don’t reach for mocks reflexively they understand the dependency chain first, then mock the minimum necessary. **The skill codifies this experienced judgment into a repeatable process**.
  895. ## Systematic Debugging (Forensic Engineering)
  896. Every engineering organization has two types of debuggers.
  897. 1. There’s the developer who sees an error, guesses the fix, tries it, and when that doesn’t work, guesses again thrashing for hours.
  898. 2. And there is the senior staff engineer who says **“stop. Let me read the error message first.”**
  899. ![Debugging](https://miro.medium.com/v2/resize:fit:2000/1*N3EcDhInmLO7B21ZeC1z9w.png)
  900. *Debugging (Created by [Fareed Khan](https://medium.com/u/b856005e5ecd))*
  901. At companies like Cloudflare, when a production incident hits, they don’t allow random fixes. There’s a formal incident response process observe, hypothesize, test, fix.
  902. The worst thing you can do during an outage is apply random patches. Each failed fix changes the system state, making the next investigation harder. You’re literally destroying evidence.
  903. `skills/systematic-debugging/SKILL.md` encodes this forensic approach:
  904. ```bash
  905. Random fixes waste time and create new bugs. Quick patches mask
  906. underlying issues.
  907. **Core principle:** ALWAYS find root cause before attempting fixes.
  908. Symptom fixes are failure.
  909. ```
  910. And the Iron Law:
  911. ```bash
  912. NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST
  913. If you havent completed Phase 1, you cannot propose fixes.
  914. ```
  915. #### The Four Phases
  916. The skill defines a four-phase investigation process that mirrors how real incident response teams operate:
  917. **Phase 1: Root Cause Investigation** before touching anything:
  918. ```markdown
  919. 1. **Read Error Messages Carefully**
  920. - Don't skip past errors or warnings
  921. - They often contain the exact solution
  922. - Read stack traces completely
  923. 2. **Reproduce Consistently**
  924. - Can you trigger it reliably?
  925. - If not reproducible → gather more data, don't guess
  926. 3. **Check Recent Changes**
  927. - What changed that could cause this?
  928. - Git diff, recent commits
  929. 4. **Gather Evidence in Multi-Component Systems**
  930. ```
  931. That fourth point is where the skill gets sophisticated. In multi-component systems which is most real-world software, the bug might manifest in component C but originate in component A. The skill requires diagnostic instrumentation at every component boundary before proposing any fix:
  932. ```bash
  933. # Layer 1: Workflow
  934. echo "=== Secrets available in workflow: ==="
  935. echo "IDENTITY: ${IDENTITY:+SET}${IDENTITY:-UNSET}"
  936. # Layer 2: Build script
  937. echo "=== Env vars in build script: ==="
  938. env | grep IDENTITY || echo "IDENTITY not in environment"
  939. # Layer 3: Signing script
  940. echo "=== Keychain state: ==="
  941. security list-keychains
  942. ```
  943. > This reveals exactly _where_ in the pipeline things break “secrets → workflow ✓, workflow → build ✗” instead of guessing.
  944. **Phase 3: Hypothesis and Testing** the scientific method applied to code:
  945. ```bash
  946. 1. **Form Single Hypothesis**
  947. - State clearly: "I think X is the root cause because Y"
  948. - Write it down
  949. - Be specific, not vague
  950. 2. **Test Minimally**
  951. - Make the SMALLEST possible change to test hypothesis
  952. - One variable at a time
  953. - Dont fix multiple things at once
  954. ```
  955. #### The Three-Fix Rule
  956. The most unique insight in the entire debugging skill is the **three-fix rule**:
  957. ```bash
  958. - Count: How many fixes have you tried?
  959. - If < 3: Return to Phase 1, re-analyze with new information
  960. - **If ≥ 3: STOP and question the architecture**
  961. - DONT attempt Fix # 4 without architectural discussion
  962. **Pattern indicating architectural problem:**
  963. - Each fix reveals new shared state/coupling/problem
  964. - Fixes require "massive refactoring" to implement
  965. - Each fix creates new symptoms elsewhere
  966. ```
  967. In organizational terms, this is the staff engineer recognizing **“we are not dealing with a bug, we’re dealing with a design flaw.”** Every experienced engineer has been in a debugging session where fix after fix keeps revealing new problems.
  968. That’s not a series of bugs, it’s a system telling you its architecture is wrong. A junior keeps patching. A staff engineer stops and says “we need to redesign this.”
  969. The skill captures common rationalizations and their realities:
  970. ```bash
  971. | "Emergency, no time for process" | Systematic debugging is FASTER than guess-and-check thrashing. |
  972. | "I see the problem, let me fix it" | Seeing symptoms ≠ understanding root cause. |
  973. | "One more fix attempt" (after 2+) | 3+ failures = architectural problem. Question pattern. |
  974. ```
  975. Real-world impact from the codebase’s own debugging sessions:
  976. ```bash
  977. - Systematic approach: 15-30 minutes to fix
  978. - Random fixes approach: 2-3 hours of thrashing
  979. - First-time fix rate: 95% vs 40%
  980. - New bugs introduced: Near zero vs common
  981. ```
  982. ## Root Cause Tracing & Defense in Depth
  983. These two supporting techniques `root-cause-tracing.md` and `defense-in-depth.md` are the toolkit and the safety regulations that complete the forensic engineering lab.
  984. ![Root cause tracing](https://miro.medium.com/v2/resize:fit:2000/1*mRIrB8DcGKfvbKjjlT8SmQ.png)
  985. *Root cause tracing (Created by [Fareed Khan](https://medium.com/u/b856005e5ecd))*
  986. #### The Detective’s Toolkit
  987. > Root cause tracing answers one question: **the error is here, but where did the bad data come from?**
  988. In organizations, this is the difference between a Level 1 support engineer who restarts the server and a staff engineer who traces the crash back to a misconfigured upstream service. The skill shows a real 5-level trace:
  989. ```bash
  990. 1. `git init` runs in `process.cwd()` ← empty cwd parameter
  991. 2. WorktreeManager called with empty projectDir
  992. 3. Session.create() passed empty string
  993. 4. Test accessed `context.tempDir` before beforeEach
  994. 5. setupCoreTest() returns `{ tempDir: '' }` initially
  995. ```
  996. The error appeared at level 1 git running in the wrong directory. A junior would fix it there, maybe adding a fallback directory. **But the actual bug was at level 5 a variable accessed before initialization. Fixing at level 1 would mask the bug. Fixing at level 5 eliminates it.**
  997. #### Making Bugs Structurally Impossible
  998. `defense-in-depth.md` takes a concept from military and cybersecurity strategy and applies it to code. The principle:
  999. ```bash
  1000. Single validation: "We fixed the bug"
  1001. Multiple layers: "We made the bug impossible"
  1002. ```
  1003. After finding that empty `projectDir` bug, the team didn't just fix the source. They added four layers of validation:
  1004. ```markdown
  1005. - Layer 1: `Project.create()` validates not empty/exists/writable
  1006. - Layer 2: `WorkspaceManager` validates projectDir not empty
  1007. - Layer 3: `WorktreeManager` refuses git init outside tmpdir in tests
  1008. - Layer 4: Stack trace logging before git init
  1009. ```
  1010. The environment guard at Layer 3 is particularly clever:
  1011. ```javascript
  1012. if (process.env.NODE_ENV === 'test') {
  1013. const normalized = normalize(resolve(directory));
  1014. const tmpDir = normalize(resolve(tmpdir()));
  1015. if (!normalized.startsWith(tmpDir)) {
  1016. throw new Error(
  1017. `Refusing git init outside temp dir during tests: ${directory}`
  1018. );
  1019. }
  1020. }
  1021. ```
  1022. Even if Layers 1 and 2 are bypassed (through mocking, through a new code path nobody anticipated), Layer 3 makes it physically impossible for tests to run git operations outside of temp directories. The bug can’t come back.
  1023. The result: all 1847 tests passed, zero pollution. This is what a staff engineer’s debugging looks like not just fixing the bug, but engineering a system where the entire *category* of bug becomes impossible.
  1024. ## Verification Before Completion (Final Sign-off)
  1025. In regulated industries aerospace, medical devices, finance there’s a concept called **evidence-based verification**. Boeing doesn’t ship an aircraft because an engineer says **“I’m pretty sure the wing stress tests passed.”**
  1026. > They ship because there’s a signed document with test results, timestamps, and the engineer’s name on it. “Trust me” is not a verification strategy
  1027. ![Verification Step](https://miro.medium.com/v2/resize:fit:2000/1*w2p97CZhp8OikSJ5SC6ykg.png)
  1028. *Verification Step (Created by [Fareed Khan](https://medium.com/u/b856005e5ecd))*
  1029. In software organizations, the equivalent failure mode is everywhere. A developer says **“tests pass”** in the PR description, but they last ran the tests two hours ago before three more changes. A sub-agent reports “task complete” but nobody checked the actual diff. A CI pipeline shows green, but it was running against the wrong branch.
  1030. `skills/verification-before-completion/SKILL.md` is the final sign-off policy the quality gate that prevents claims without evidence. It opens with a line that would make any auditor proud:
  1031. ```bash
  1032. Claiming work is complete without verification is dishonesty,
  1033. not efficiency.
  1034. **Core principle:** Evidence before claims, always.
  1035. ```
  1036. And the Iron Law:
  1037. ```bash
  1038. NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE
  1039. If you havent run the verification command in this message,
  1040. you cannot claim it passes.
  1041. ```
  1042. That word **fresh** is doing heavy lifting. Not **“I ran it earlier.”** Not **“it passed last time.”** Fresh. Now. In this message. This is the difference between a company that has quality processes and a company that follows them.
  1043. #### The Gate Function
  1044. Before the agent can say anything positive about work status, it must pass through a gate:
  1045. ```bash
  1046. BEFORE claiming any status or expressing satisfaction:
  1047. 1. IDENTIFY: What command proves this claim?
  1048. 2. RUN: Execute the FULL command (fresh, complete)
  1049. 3. READ: Full output, check exit code, count failures
  1050. 4. VERIFY: Does output confirm the claim?
  1051. - If NO: State actual status with evidence
  1052. - If YES: State claim WITH evidence
  1053. 5. ONLY THEN: Make the claim
  1054. Skip any step = lying, not verifying
  1055. ```
  1056. The skill provides a table of what counts as evidence versus what doesn’t:
  1057. ```bash
  1058. | Claim | Requires | Not Sufficient |
  1059. |-------|----------|----------------|
  1060. | Tests pass | Test command output: 0 failures | Previous run, "should pass" |
  1061. | Build succeeds | Build command: exit 0 | Linter passing, logs look good |
  1062. | Bug fixed | Test original symptom: passes | Code changed, assumed fixed |
  1063. | Agent completed | VCS diff shows changes | Agent reports "success" |
  1064. ```
  1065. That last row is critical for our system. When a sub-agent reports **“task complete, all tests pass”**, the manager doesn’t take their word for it. They check the VCS diff.
  1066. > They run the tests independently. In organizational terms, this is the audit function you don’t trust self-reported compliance.
  1067. #### Rationalization Prevention
  1068. The skill anticipates every excuse an engineer (or an AI) might use to skip verification:
  1069. ![Prevent errors](https://miro.medium.com/v2/resize:fit:2400/1*JjM5tVzUTvOHujLp2wUY7A.png)
  1070. *Prevent errors (Created by [Fareed Khan](https://medium.com/u/b856005e5ecd))*
  1071. ```bash
  1072. | Excuse | Reality |
  1073. |--------|---------|
  1074. | "Should work now" | RUN the verification |
  1075. | "I'm confident" | Confidence ≠ evidence |
  1076. | "Just this once" | No exceptions |
  1077. | "Agent said success" | Verify independently |
  1078. | "I'm tired" | Exhaustion ≠ excuse |
  1079. | "Different words so rule doesn't apply" | Spirit over letter |
  1080. ```
  1081. That last one **“different words so rule doesn’t apply”** is subtle and important. It catches the agent trying to say **“the implementation looks correct”** instead of **“tests pass”** to avoid triggering the verification gate.
  1082. > Through creative rewording that technically doesn’t violate the letter of the policy while completely violating its spirit.
  1083. We need to create skill to flags specific language patterns as red flags:
  1084. ```bash
  1085. - Using "should", "probably", "seems to"
  1086. - Expressing satisfaction before verification ("Great!", "Perfect!")
  1087. - About to commit/push/PR without verification
  1088. - **ANY wording implying success without having run verification**
  1089. ```
  1090. At companies like Stripe and Square, where financial transactions are involved, this level of verification discipline isn’t optional it’s regulatory. Our system applies the same standard to every task, because the cost of shipping broken code is always higher than the cost of running one more command.
  1091. ## The Peer Review Meeting (Code Review)
  1092. Code review is where most engineering organizations either build or destroy their culture. Done well, it’s the single most effective quality practice in software engineering. Done poorly, it becomes either a rubber-stamp formality or a political battlefield.
  1093. ![Review in Meeting](https://miro.medium.com/v2/resize:fit:2000/1*ybVe4Q29GPPBMv-f4GvsUg.png)
  1094. *Review in Meeting (Created by [Fareed Khan](https://medium.com/u/b856005e5ecd))*
  1095. In organizations like Google, code review is mandatory for every change no exceptions, not even for senior staff engineers. The philosophy is that every pair of eyes catches different classes of bugs.
  1096. But there’s a deeper purpose:
  1097. > code review is how engineering culture propagates. Juniors learn standards by reading review feedback. Seniors stay honest because someone is always checking.
  1098. Our system splits the code review process into three files that mirror three distinct organizational roles: the **reviewer** (`agents/code-reviewer.md`), the **request process** (`skills/requesting-code-review/SKILL.md`), and the **reception process** (`skills/receiving-code-review/SKILL.md`).
  1099. #### The Reviewer (Senior Peer Reviewer Persona)
  1100. `agents/code-reviewer.md` defines the reviewer as a Senior Code Reviewer sub-agent an architect-level persona that evaluates completed work across five dimensions:
  1101. ```bash
  1102. 1. **Plan Alignment Analysis** - Compare implementation against
  1103. original planning document
  1104. 2. **Code Quality Assessment** - Patterns, error handling, type
  1105. safety, test coverage
  1106. 3. **Architecture and Design Review** - SOLID principles,
  1107. separation of concerns, coupling
  1108. 4. **Documentation and Standards** - Comments, file headers,
  1109. conventions
  1110. 5. **Issue Identification** - Critical (must fix), Important
  1111. (should fix), Suggestions (nice to have)
  1112. ```
  1113. The three-tier issue categorization is how mature engineering organizations run reviews. At companies like Microsoft and Meta, code review comments are tagged by severity.
  1114. A critical issue blocks the merge. An important issue should be fixed but doesn’t block. A suggestion is advisory. Without this categorization, every review becomes an argument about whether a comment is a blocker or a nitpick.
  1115. The reviewer’s communication protocol includes a principle that separates good reviewers from toxic ones:
  1116. ```bash
  1117. - Always acknowledge what was done well before highlighting issues
  1118. ```
  1119. **In organizational psychology, this is called the “feedback sandwich”** and while it’s often mocked, the principle behind it is sound. Engineers who only hear criticism stop submitting code for review. Engineers who hear “this architecture is clean, AND here’s what needs fixing” stay engaged and improve.
  1120. #### Requesting Review (The Pull Request SOP)
  1121. `skills/requesting-code-review/SKILL.md` defines when and how to ask for review. The "when" is structured around workflow integration:
  1122. ```bash
  1123. **Mandatory:**
  1124. - After each task in subagent-driven development
  1125. - After completing major feature
  1126. - Before merge to main
  1127. **Optional but valuable:**
  1128. - When stuck (fresh perspective)
  1129. - Before refactoring (baseline check)
  1130. - After fixing complex bug
  1131. ```
  1132. The “how” is precise the reviewer sub-agent gets exactly the git SHAs, the task description, and the plan requirements. No session history, no conversation context. Just the work product and the spec:
  1133. ```bash
  1134. **Placeholders:**
  1135. - `{WHAT_WAS_IMPLEMENTED}` - What you just built
  1136. - `{PLAN_OR_REQUIREMENTS}` - What it should do
  1137. - `{BASE_SHA}` - Starting commit
  1138. - `{HEAD_SHA}` - Ending commit
  1139. - `{DESCRIPTION}` - Brief summary
  1140. ```
  1141. This mirrors how pull requests work at well-run companies. The reviewer doesn’t need to know about the three hours of debugging that led to the fix.
  1142. > They need to see the change, understand what it’s supposed to do, and evaluate whether it does it well.
  1143. The skill also addresses what to do with feedback and critically, when to push back:
  1144. ```bash
  1145. - Fix Critical issues immediately
  1146. - Fix Important issues before proceeding
  1147. - Note Minor issues for later
  1148. - Push back if reviewer is wrong (with reasoning)
  1149. ```
  1150. That last point matters. In toxic engineering cultures, nobody pushes back on review feedback because they’re afraid of conflict. In healthy cultures, pushback is expected and respected as long as it’s technical, not personal.
  1151. #### Receiving Review (Collaboration Etiquette)
  1152. This is the most psychologically sophisticated file in the entire codebase. `skills/receiving-code-review/SKILL.md` addresses a problem that plagues both human and AI engineers: **sycophancy under review pressure**.
  1153. ![Review Viewer](https://miro.medium.com/v2/resize:fit:2400/1*6RdDVw3lqLkgzX0YpGWkUA.png)
  1154. *Review Viewer (Created by [Fareed Khan](https://medium.com/u/b856005e5ecd))*
  1155. The forbidden responses list reads like a manual for authentic professional communication:
  1156. ```bash
  1157. **NEVER:**
  1158. - "You are absolutely right!"
  1159. - "Great point!" / "Excellent feedback!"
  1160. - "Let me implement that now" (before verification)
  1161. **INSTEAD:**
  1162. - Restate the technical requirement
  1163. - Ask clarifying questions
  1164. - Push back with technical reasoning if wrong
  1165. - Just start working (actions > words)
  1166. ```
  1167. In real organizations, performative agreement during code review is a cultural disease. The engineer who says “great catch!” to every comment isn’t learning they’re performing.
  1168. They implement the suggestion without understanding it, introduce a new bug, and the cycle repeats. The skill enforces a different pattern:
  1169. ```bash
  1170. WHEN receiving code review feedback:
  1171. 1. READ: Complete feedback without reacting
  1172. 2. UNDERSTAND: Restate requirement in own words (or ask)
  1173. 3. VERIFY: Check against codebase reality
  1174. 4. EVALUATE: Technically sound for THIS codebase?
  1175. 5. RESPOND: Technical acknowledgment or reasoned pushback
  1176. 6. IMPLEMENT: One item at a time, test each
  1177. ```
  1178. The verification step is where this gets real. Before implementing any suggestion, the agent must check whether the suggestion actually makes sense for this codebase:
  1179. ```bash
  1180. BEFORE implementing:
  1181. 1. Check: Technically correct for THIS codebase?
  1182. 2. Check: Breaks existing functionality?
  1183. 3. Check: Reason for current implementation?
  1184. 4. Check: Works on all platforms/versions?
  1185. 5. Check: Does reviewer understand full context?
  1186. ```
  1187. The real-world examples show what this looks like in practice:
  1188. ```bash
  1189. **Performative Agreement (Bad):**
  1190. Reviewer: "Remove legacy code"
  1191. ❌ "You're absolutely right! Let me remove that..."
  1192. **Technical Verification (Good):**
  1193. Reviewer: "Remove legacy code"
  1194. ✅ "Checking... build target is 10.15+, this API needs 13+.
  1195. Need legacy for backward compat. Current impl has wrong
  1196. bundle ID - fix it or drop pre-13 support?"
  1197. ```
  1198. The second response demonstrates real engineering. The developer didn’t blindly agree OR defensively refuse. They checked the facts, found the nuance (backward compatibility requirement), and presented options.
  1199. > This is what senior staff engineers do in code review they bring context that the reviewer might not have.
  1200. The YAGNI check is another component we must include …
  1201. ```kotlin
  1202. IF reviewer suggests "implementing properly":
  1203. grep codebase for actual usage
  1204. IF unused: "This endpoint isn't called. Remove it (YAGNI)?"
  1205. IF used: Then implement properly
  1206. ```
  1207. And then there’s the organizational hierarchy principle:
  1208. ```bash
  1209. "You and reviewer both report to me. If we don't need this
  1210. feature, don't add it."
  1211. ```
  1212. This is a staff engineer’s perspective on code review. The reviewer and the implementer are peers neither has authority over the other. The human (the VP, the product owner) has authority. If a reviewer suggests building something the product doesn’t need, the right answer is “let’s check with the stakeholder,” not “yes sir.”
  1213. When acknowledging correct feedback, the skill enforces action over words:
  1214. ```sql
  1215. ✅ "Fixed. [Brief description of what changed]"
  1216. ✅ "Good catch - [specific issue]. Fixed in [location]."
  1217. ✅ [Just fix it and show in the code]
  1218. ❌ "You're absolutely right!"
  1219. ❌ "Thanks for catching that!"
  1220. ❌ ANY gratitude expression
  1221. **Why no thanks:** Actions speak. Just fix it. The code itself
  1222. shows you heard the feedback.
  1223. ```
  1224. **This might seem harsh, but it reflects a deep truth about professional communication.**
  1225. In high-performing engineering teams at places like Cloudflare, Linear, or Vercel the best code reviews are terse, technical, and action-oriented. “Fixed” is a complete sentence. The fix itself is the acknowledgment.
  1226. ## Using Git Worktrees (Bio-hazard Containment)
  1227. **In biology labs, there’s a concept called containment levels.** When researchers work with dangerous pathogens, they don’t do it on the same bench where they eat lunch. They work in isolated chambers with negative air pressure, separate ventilation, and airlocks.
  1228. > The principle is simple: dangerous work happens in isolated environments so that if something goes wrong, the damage is contained.
  1229. ![Git worktree](https://miro.medium.com/v2/resize:fit:2000/1*klvBdRAhY1AOlXHFqr3p_g.png)
  1230. *Git worktree (Created by [Fareed Khan](https://medium.com/u/b856005e5ecd))*
  1231. Software engineering has the same problem. When a developer is building a new authentication system, they are essentially handling a **pathogen** code that could infect the main codebase if it escapes prematurely.
  1232. **At companies like GitLab, Shopify, and Netflix, the solution is branch isolation.** But traditional git branches have a flaw: you can only have one branch checked out at a time.
  1233. 1. Switch branches mid-task, and you lose your mental context. Stash changes, and you forget what you stashed.
  1234. 2. It’s like an airlock that requires you to decontaminate every time you want to check something in the clean room.
  1235. Git worktrees solve this by creating **physically separate directories** that share the same repository. You can have `main` in one folder and `feature/auth` in another, both live, both independent. It's multiple containment chambers sharing the same lab.
  1236. `skills/using-git-worktrees/SKILL.md` systematizes this for the squad:
  1237. ```bash
  1238. Git worktrees create isolated workspaces sharing the same
  1239. repository, allowing work on multiple branches simultaneously
  1240. without switching
  1241. **Core principle:** Systematic directory selection + safety
  1242. verification = reliable isolation.
  1243. ```
  1244. #### Directory Selection (Office Space Assignment)
  1245. In a software house, when a new team spins up, they don’t just grab any empty desk. There’s a process check if there’s an assigned area, check the office map, ask facilities management. The skill mirrors this with a priority chain:
  1246. ```bash
  1247. ### 1. Check Existing Directories
  1248. ls -d .worktrees 2>/dev/null # Preferred (hidden)
  1249. ls -d worktrees 2>/dev/null # Alternati
  1250. **If found:** Use that directory. If both exist, `.worktrees/` wins.
  1251. ### 2. Check CLAUDE.md
  1252. grep -i "worktree.*director" CLAUDE.md 2>/dev/null
  1253. **If preference specified:** Use it without asking.
  1254. ### 3. Ask User
  1255. ```
  1256. This hierarchy which is existing convention → documented preference → ask is how well-run organizations make decisions. You don’t reinvent the wheel every time someone needs a workspace. You check what’s already established, check the documentation, and only escalate to a human when neither exists.
  1257. #### Safety Verification (The Airlock Check)
  1258. Here’s where the containment metaphor gets literal. Before creating a worktree in a project-local directory, the skill **must verify** that directory is git-ignored:
  1259. ```bash
  1260. **MUST verify directory is ignored before creating worktree:
  1261. git check-ignore -q .worktrees 2>/dev/null || \
  1262. git check-ignore -q worktrees 2>/dev/null
  1263. **If NOT ignored:**
  1264. 1. Add appropriate line to .gitignore
  1265. 2. Commit the change
  1266. 3. Proceed with worktree creation
  1267. **Why critical:** Prevents accidentally committing worktree
  1268. contents to repository.
  1269. ```
  1270. 1. Imagine the disaster scenario without this check. A developer creates a worktree, does experimental work in it, and because the worktree directory isn’t gitignored, all that experimental code shows up in `git status` on the main branch.
  1271. 2. They accidentally commit it. They push. Now the experimental code is in production.
  1272. 3. At companies like Cloudflare and Figma, where a single bad deploy can affect millions of users, this kind of accident triggers a post-mortem.
  1273. **The skill prevents it structurally not by trusting the developer to remember, but by checking every time and fixing the problem if it finds one**. This is defense-in-depth applied to DevOps.
  1274. #### Clean Baseline (The Calibration Step)
  1275. In manufacturing, before a production line starts a new run, the equipment is calibrated. You don’t start making parts and hope the machine is aligned correctly. You verify first. The skill applies the same principle to worktrees:
  1276. ```bash
  1277. ### 4. Verify Clean Baseline
  1278. Run tests to ensure worktree starts clean:
  1279. npm test / cargo test / pytest / go test ./...
  1280. **If tests fail:** Report failures, ask whether to proceed
  1281. or investigate.
  1282. **If tests pass:** Report ready.
  1283. ```
  1284. This is critical because it establishes what “working” looks like *before* the developer makes any changes. **Without a clean baseline, when tests fail later, you can’t tell whether your code broke something or it was already broken**.
  1285. > In real organizations, this is why CI/CD pipelines run tests on the base branch before the PR branch to establish a known-good state.
  1286. The setup is also smart about auto-detection, it doesn’t hardcode `npm install`. It checks what kind of project it's in:
  1287. ```bash
  1288. # Node.js
  1289. if [ -f package.json ]; then npm install; fi
  1290. # Rust
  1291. if [ -f Cargo.toml ]; then cargo build; fi
  1292. # Python
  1293. if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
  1294. # Go
  1295. if [ -f go.mod ]; then go mod download; fi
  1296. ```
  1297. This is the DevOps equivalent of a lab that can handle multiple types of specimens. The containment procedure adapts to what’s being contained, rather than forcing everything through the same protocol.
  1298. The final report is structured and clear:
  1299. ```bash
  1300. Worktree ready at /Users/jesse/myproject/.worktrees/auth
  1301. Tests passing (47 tests, 0 failures)
  1302. Ready to implement auth feature
  1303. ```
  1304. Location, baseline status, readiness. Everything a manager needs to know before dispatching developers into the workspace.
  1305. #### Finishing a Development Branch (Release Engineering)
  1306. **In every engineering organization, there’s a moment that’s simultaneously the most satisfying and the most dangerous, the moment when the feature is “done” and it’s time to ship.**
  1307. This is where more things go wrong than any other phase of development. The code works on the developer’s machine. The tests pass in the feature branch. But the merge conflicts with main, the integration tests fail, and the deploy breaks because someone forgot to update the config.
  1308. At companies like Google, this phase has its own role the **Release Engineer**. Their job isn’t to write features.
  1309. 1. It’s to manage the process of getting completed code from a development branch into production safely.
  1310. 2. They verify, merge, tag, deploy, and clean up. It’s a separate discipline because the skills required caution, thoroughness, communication are different from the skills required to build features.
  1311. `skills/finishing-a-development-branch/SKILL.md` encodes this entire release engineering workflow:
  1312. ```markdown
  1313. **Core principle:** Verify tests → Present options → Execute
  1314. choice → Clean up.
  1315. ```
  1316. Four steps. Simple in concept, rigorous in execution.
  1317. #### Step 1: Verify Before Anything
  1318. The first rule of release engineering is **never ship broken code**. The skill enforces this absolutely:
  1319. ```bash
  1320. ### Step 1: Verify Tests
  1321. **Before presenting options, verify tests pass:**
  1322. npm test / cargo test / pytest / go test ./...
  1323. **If tests fail:**
  1324. Tests failing (<N> failures). Must fix before completing:
  1325. [Show failures]
  1326. Cannot proceed with merge/PR until tests pass.
  1327. Stop. Dont proceed to Step 2.
  1328. ```
  1329. **This is a hard gate. Not “tests should pass.”** Not **“we’ll fix them after merge.”** Tests must pass *now*, or nothing else happens. In organizational terms, this is the QA department having veto power over releases. The product manager can’t override it. The CEO can’t override it. If tests fail, the code doesn’t ship. Period.
  1330. #### Step 2: Structured Options (Not Open-Ended Questions)
  1331. Here’s a subtle but important design decision. When the feature is ready, the skill doesn’t ask **“what should we do next?”** an open-ended question that leads to confusion and scope creep. Instead, it presents exactly four structured options:
  1332. ```bash
  1333. Implementation complete. What would you like to do?
  1334. 1. Merge back to <base-branch> locally
  1335. 2. Push and create a Pull Request
  1336. 3. Keep the branch as-is (I will handle it later)
  1337. 4. Discard this work
  1338. Which option?
  1339. ```
  1340. **In organizations, this is the difference between a junior release engineer who asks “so… are we deploying?”** and a senior one who says **“code is ready. Here are your options. Pick one.”** The structured options prevent scope creep **(“well, maybe we should also add…”)**, prevent analysis paralysis **(“let me think about it…”)**, and make the decision traceable **(“stakeholder chose Option 2 on Tuesday”)**.
  1341. The skill is explicit about keeping these concise:

Lines 2,001–2,433 are not shown. The link to the file on GitHub has every line.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.