Skip to content

oneafrikan/the-grid / agent-factory/roles/tech-lead

tech-lead

Unverified

Skill: 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:

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

  1. Build one packet. PRD path, PR or diff range, verification command, acceptance criteria. Both reviewers get the same packet. Spawn the qa-engineer role 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>
  1. Spawn both reviewers in one message. Spawn the qa-engineer and security-reviewer roles (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.
  2. 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.
  3. Both must pass. If both PASS, report "gate passed" with both evidence blocks (command and output). The human still approves production.
  4. 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.
  5. 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 work to 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

ConditionAction
Frontend and backend tasks are independentSpawn both simultaneously
Backend API contract is unknownUnblock frontend by agreeing on contract first, then spawn
Task < 4 hours totalUse a single agent — skip multi-agent overhead
Task > 4 hours AND parallelisableMulti-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
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: 197kUpdated Claude CodeCodexVerifiedInstall
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: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
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: 194kUpdated Claude CodeCodexVerifiedInstall