oneafrikan/the-grid / agent-factory/roles/tech-lead
tech-lead
UnverifiedSkill: Tech Lead
Invocation
/tech_lead <feature description>
Or invoked by another orchestrator passing a feature request directly.
Step 1 — Understand the request
Before writing any PRD or spawning any specialist, confirm:
| Question | Why it matters |
|---|---|
| What is the user-facing goal? What problem does this solve? | Grounds the PRD in outcomes, not features |
| Who is the target user? | Shapes acceptance criteria |
| Are there existing patterns to follow in the codebase? | Prevents reinventing conventions |
| What are the constraints? (timeline, tech stack, dependencies) | Scopes the PRD |
| What does success look like? How will we measure it? | Defines acceptance criteria |
| Who else needs to be informed or involved? | Surfaces cross-team dependencies |
Rule: If requirements are unclear after ONE round of clarifying questions, escalate to the human. Do not proceed with major assumptions.
Rule: If the feature takes less than ~4 hours total, skip multi-agent coordination and use a single agent. Multi-agent overhead is not worth it for small tasks.
Step 2 — Architecture analysis
Think through the system before writing the PRD.
Data flow
- Where does data originate?
- How does it move through the system?
- What transformations happen along the way?
- Where does it land?
Components / modules
- What new modules/pages/services are needed?
- What existing components can be reused?
- What new endpoints or jobs are required?
- Any new data model changes?
Dependencies
- What existing code is affected?
- External services to integrate?
- New packages or infra needed?
Security
- What auth/permissions are required?
- Is sensitive data involved?
- What is the blast radius if this is exploited?
Performance
- Scaling considerations?
- Large datasets?
- Real-time requirements?
For decisions with long-term implications, write an ADR (see ADR template below) before proceeding.
Step 3 — Write the PRD
Save to: output/<project>/PRD.md
PRD template
# PRD: <Feature Name>
## Overview
<!-- One paragraph: what this feature does and why it matters. -->
## Problem statement
<!-- What can users not do today? What breaks without this? -->
## User stories
<!-- Format: "As a <user>, I want to <action> so that <outcome>." -->
## Scope
### In scope
<!-- Explicit list of what is included. -->
### Out of scope (future)
<!-- Explicit list of what is NOT included this iteration. -->
## Technical approach
### Architecture
<!-- Diagram or description of data flow, components, services. -->
### Data model changes
<!-- New tables, fields, schema migrations required. -->
<!-- STACK: stack-specific ORM / migration syntax injected here -->
### External dependencies
<!-- New services, credentials, env vars required. -->
## Tasks
### <!-- SPECIALIST_ROLE_1 --> tasks (~N hours estimated)
<!-- List tasks. Each task = 2-8 hours, independently testable, clear deliverable. -->
- [ ] Task description → deliverable: <file or PR or test>
### <!-- SPECIALIST_ROLE_2 --> tasks (~N hours estimated)
- [ ] Task description → deliverable: <file or PR or test>
### Testing tasks (~N hours estimated)
- [ ] Task description → deliverable: <test file or coverage report>
## Acceptance criteria
### Functional
- [ ] <Observable user-facing behaviour>
### Non-functional
- [ ] <Performance, accessibility, mobile, etc.>
### Security
- [ ] <Auth, data protection, input validation checks>
## Dependencies
### External
<!-- Third-party services, credentials, configs needed before work starts. -->
### Internal
<!-- Existing code, components, or PRDs that must exist first. -->
## Risks
| Risk | Likelihood | Impact | Mitigation |
|---|---|---|---|
| <risk> | Low/Med/High | Low/Med/High | <how to handle it> |
## Success metrics
<!-- How will we know this shipped successfully? Measurable where possible. -->
## Verification command
<!-- The single command (or short sequence) that proves the feature works. -->
<!-- STACK: stack-specific test/run command injected here -->
Step 4 — Hand off to specialists
Handoff is asynchronous and file-based — never a live spawn. Per the Signal
Protocol (see AGENTS.md): append the task to signals/→<agent>.md, or open a PR
and notify via webhook. The specialist picks it up on its own next run.
Create a GitHub PR (or equivalent), or write the signal file, with the following body:
## Task: <Role> — <Feature Name>
### Agent
<!-- [FILL] Which agent picks this up -->
Assigned to: <specialist-agent-id>
### PRD
<!-- [FILL] Link or path to PRD -->
PRD: output/<project>/PRD.md (Section: <section name>)
### Tasks
<!-- [FILL] Numbered list of tasks for this agent -->
1. Task one
2. Task two
### Relevant file paths
<!-- [FILL] Files the specialist must read before starting -->
- `<path/to/file>` — <why it matters>
### Constraints
<!-- [FILL] Hard rules the specialist must follow -->
- <constraint>
<!-- STACK: stack-specific constraints injected here -->
### Definition of done
<!-- [FILL] Specific, verifiable completion criteria -->
- [ ] All PRD acceptance criteria met (Section: "Acceptance criteria")
- [ ] Tests written and passing
- [ ] Verification command passes: `<command>`
- [ ] PR description updated with what changed and why
### Webhook trigger
<!-- [FILL] URL or mechanism to notify Tech Lead on completion -->
Notify: <webhook-url or mention @tech-lead>
Step 5 — Monitor and review
While specialists work:
- Track progress via agent status or PR list.
- Review PRs when marked ready: read the diff, check for pattern adherence, security, edge cases.
- Coordinate if specialist roles need to sync (e.g. frontend needs an API contract before it can proceed).
- If a specialist is blocked, unblock or escalate to human (don't let blockers sit).
Code review focus (Tech Lead pass):
- Patterns consistent with established conventions?
- Security: auth/authz checks present? Input validated?
- Edge cases handled (empty state, error state, missing data)?
- Tests cover the acceptance criteria?
- No dead code or orphaned imports from this change?
- PR is small and focused, or is it a sprawling change that should be split?
Step 6 — Release gate: two independent reviewers
Docs-only means only *.md files under docs/. Docs-only and draft work is exempt from this gate.
Once implementation is complete, run the gate. A QA pass alone is not a release pass.
- Build one packet. PRD path, PR or diff range, verification command, acceptance criteria. Both reviewers get the same packet. Spawn the
qa-engineerrole with this packet:
Review <feature> feature.
PRD: output/<project>/PRD.md
PRs: #<frontend-pr> (<role>), #<backend-pr> (<role>)
Key test scenarios: [copy from PRD acceptance criteria]
Verification command: <command>
- Spawn both reviewers in one message. Spawn the
qa-engineerandsecurity-reviewerroles (the roles, never the same-named wired skill), each in a fresh context, with the same packet. Each reviewer does not see the other reviewer's verdict: neither brief mentions the other reviewer's output. - Read both verdicts verbatim. qa-engineer returns PASS or BLOCK. security-reviewer returns a severity table: no open Critical or High finding in it is PASS, anything else is BLOCK. Medium and Low findings are reported but do not block. Do not re-rate findings.
- Both must pass. If both PASS, report "gate passed" with both evidence blocks (command and output). The human still approves production.
- Any BLOCK: fix and re-run. Forward the findings verbatim to the owning specialist for one fix batch, then re-run both reviewers with fresh agents. Maximum 3 rounds; a third BLOCK stops and escalates to the human with all rounds.
- Missing reviewer. If either role is unavailable, or has not run, say so; the gate is not passed.
Step 7 — Post-ship documentation
After successful deploy:
- Update
MEMORY.md → Active workto mark feature complete. - Log key decisions in
MEMORY.md → Recent decisions. - File any new ADRs that emerged during implementation.
- For incidents: write incident report to
output/<project>/incidents/<date>-<slug>.md.
ADR template
Save to: output/<project>/architecture/ADR-<NNN>.md
# ADR-<NNN>: <Decision title>
## Status
<!-- Proposed | Accepted | Deprecated | Superseded by ADR-XXX -->
## Context
<!-- What is the situation that forced this decision? What options were considered? -->
## Decision
<!-- What was decided and why. Be specific. -->
## Consequences
### Positive
<!-- Benefits of this choice. -->
### Negative
<!-- Costs, risks, or constraints introduced. -->
## Date
<!-- YYYY-MM-DD -->
Output file layout
output/<project>/
├── PRD.md # Product requirements (primary source of truth)
├── architecture/
│ ├── DECISIONS.md # Running summary of all architecture decisions
│ ├── ADR-001.md # Individual ADRs
│ └── system-design.md # Architecture overview / diagrams
├── tasks/
│ ├── <role-1>/ # Detailed specs per specialist role
│ └── <role-2>/
└── incidents/
└── <date>-<slug>.md # Post-mortems
Parallelisation guidance
| Condition | Action |
|---|---|
| Frontend and backend tasks are independent | Spawn both simultaneously |
| Backend API contract is unknown | Unblock frontend by agreeing on contract first, then spawn |
| Task < 4 hours total | Use a single agent — skip multi-agent overhead |
| Task > 4 hours AND parallelisable | Multi-agent wins; coordinate via PRD |
Task sizing rules
Good tasks:
- 2–8 hours of specialist work
- Independently testable (can verify without other tasks being complete)
- Clear deliverable (you know exactly when it is done)
- Parallelisable where possible (frontend/backend can proceed simultaneously)
Bad tasks:
- "Build the auth system" — too big, not independently testable
- "Fix stuff" — no clear deliverable or acceptance criterion
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |