Tech lead
Use this skill whenever the user wants to orchestrate a whole feature end-to-end across the harness skills — ba-pitch-analyzer (planner), task-executor (generator), spec-evaluator (judge) — acting as the tech lead that owns the run and reports to the PO at round boundaries. Trigger on: "run the full harness", "act as tech lead", "ship this feature end to end", "from pitch to ship", "orchestrate the build", "plan build evaluate". Use it even when the user describes a multi-step build flow without naming the skills.From its SKILL.md
npx -y skills add nguyenvanphituoc/shapeup-sdlc-plugin --skill tech-leadAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
One thing to look at
- 3 stars3 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.
SKILL.md
10.2 KB, as published. Nobody here has run it
Tech Lead (harness orchestrator)
▶ RUN THIS FIRST — do not summarise this file
Your first output must be a tool call, not a plan. Everything you emit before the first tool
call is narration, and a narrated run is a failed run — it reads like a clean success and leaves
escaped defects behind it. hooks/gate-zerowork.mjs (Stop) blocks a session
that reached the orchestrator and left no receipt — where "reached the orchestrator" means
dispatching this skill or launching a shapeup-* workflow by either surface, and the receipt is
what harness init run writes. Working around the harness is not an exemption: a busy session used to
switch this gate off and no longer does. Loading these instructions is not running them.
Step 1 — open the run. Write the requirement to a file first, then pass the path — a multi-line requirement inlined into a shell argument is where this step goes wrong (measured: six turns fighting shell quoting):
node "${CLAUDE_PLUGIN_ROOT}/kernel/harness.mjs" init run \
--slug <slug-from-the-request> --intake-file <path/to/the/requirement.md> \
--auto-level <interactive|auto|unattended> \
[--dimensions <a,b>] [--gate-answers <ci|guarded|path.json>] [--wall-clock-budget <seconds>] [--max-rounds 3]
After a compaction, or in a fresh session over an open run, re-derive before you act. One command answers where the run stands, from artifacts and never from memory:
node "${CLAUDE_PLUGIN_ROOT}/kernel/harness.mjs" reduce graph --slug <slug> --subgraph run
Exit 3 means a run is ALREADY OPEN. Resume it; do not re-open it. The refusal prints the
derived RESUME STATE (slug, status, round, board counts) — read it and go straight to Step 2;
shapeup-run.js's own fast-forward will re-derive exactly where to continue from disk, never from
this session's memory. --force re-opens deliberately and discards the round history the breaker
counts.
If this command comes back "requires approval", stop and say so. These scripts ship with the
plugin and need a one-time permission grant (npx shapeup-sdlc init writes it). Do not route
around it, and do not silently hand-build the feature instead.
Language gate (delegated to translator, not this skill): at GATE L0, before Step 2, dispatch
an Agent (model: exec) that calls Skill(shapeup-sdlc-plugin:translator) --check <intake>.
English → proceed as-is. Non-English → dispatch a second Agent (--auto under auto/unattended)
and orchestrate against the produced <name>.en.md. The tech lead detects and sequences; it never
translates itself.
Step 2 — pin GATE L0, then launch. Collect the L0.1–L0.9 config (spec folder, lens, stack,
eval dims, max_rounds, the model/budget matrix — see references/gates.md GATE L0 for the full
collect-list), write the SHARED project-profile.md yourself ({schema_version:1, archetype, entry_point} — shapeup-run.js has no filesystem of its own), emit the ⏸ GATE L0 block, then
check the lane:
--tiny, or the spec has no committedscopes/*.mdyet (pre-v0.3.0 spec):shapeup-run.jsis out of scope for this lane by design (it targets scope-contract specs). Run the unchanged legacy loop instead —references/protocol.md(BUILD(r)/EVAL) +references/protocol.mdcarry the full step-by-step for both the tiny lane and a scope-less BUILD loop, verbatim, non- regression. Stop reading this file here for that run.- Otherwise (the common case — a scoped spec, any auto level): build
RunArgs(domain.schema.json$defs/RunArgs—{slug, runId, autoLevel, answers, lane, models:{exec,eval,qa}, budgets:{maxRounds,attemptBudget,wallClockS}, pluginRoot, startedAt}, plus every switch the operator typed —references/gates.mdGATE L0.9 has the flag→field table, and a flag that stops here is a flag that was accepted and ignored). Write that exact object to.shapeup/<slug>/run-args.jsonbefore launching, fresh on every launch and relaunch: the flags reach the workflow as a value in memory, so it is the run's only evidence of what it was launched with, and a run that cannot state its own configuration cannot have a claim about it checked. Then launch the run script with theWorkflowtool:
Workflow({
scriptPath: "${CLAUDE_PLUGIN_ROOT}/skills/tech-lead/workflows/shapeup-run.js",
args: <the RunArgs object>
})
shapeup-run.js (domain.schema.json $defs/RunArgs/RunReturn) owns everything from ORIENT
through GATE H and the ship report — every gate inside that range resolves via harness gate's
exit code, in code, not by this skill's own reading of a paragraph. The RunReturn is the script's
return value, and it arrives as the workflow's result.
Why the tool and not a Bash launcher. The native runtime is what gives the run
resume-from-journal, worktree isolation, and sub-agents that share this session's prompt cache
instead of paying a cold start each. npx shapeup-sdlc init writes the "Workflow" grant the
launch needs. That grant is UNSCOPED — it authorises every dynamic workflow script in the project,
not only this one — so an install may decline it with --no-native-workflow, in which case the
launch prompts for approval once per session and the unattended lane is unavailable. If the launch
comes back "requires approval" in a headless session, stop and say so — do not hand-build the
feature instead.
Step 3 — the pause protocol: branch on RunReturn.status
status | What the workflow is telling you | What you do |
|---|---|---|
paused | A gate resolved "ask" — paused_at names it, block is composed and ready | Emit block verbatim (never re-summarise it — that is the paraphrase channel this design exists to close). Put it to the PO, get a decision. Write it to .shapeup/<slug>/gate-answers.json ({"version":1,"preset":"custom","answers":{"<paused_at>":{"decision":"<answer>"}}}, merging with any prior gate's answer already there). Relaunch the SAME Workflow call, same args — the fast-forward re-derives from disk and re-dispatches nothing already done (verify: orders/ minus results/ is empty before it proceeds) |
aborted | A gate resolved "abort", or a hard stop (spec-lint red, scope-hammer CANNOT SHIP) | Report aborted_at + reason to the PO. Do not relaunch without a human decision — --force on harness init run if truly restarting |
gate_h | A circuit breaker tripped (breaker: outer | inner | deadline) — green_scopes shipped nothing, hammer_proposals needs a census | Dispatch a fresh Agent (model: exec): Skill(shapeup-sdlc-plugin:scope-hammer) --slug <slug> --breaker <breaker> [--scope <id>] for the census + cut list, put the PO's decision to references/gates.md GATE H, then close out via Step 4 below |
shipped | The board's final round passed EVAL, QA ran, GATE H accepted the cut list, report names the frozen shapeup/<slug>/REPORT.md | Go straight to Step 4 |
Never treat a paused return as a stall to work around, and never invent an answer this skill
did not actually receive from the PO — an unattended lane with no answer for a gate is meant to
abort (see harness gate's on_missing), not silently proceed.
Step 4 — GATE L4 — Ship Sign-Off (this skill's own gate; the workflow never sees it)
FIRST freeze the evidence — run state is gitignored, so shapeup/<slug>/REPORT.md (already
written by shapeup-run.js via harness reduce ship, or write it now on a gate_h close) is all a
teammate sees. Then emit:
⏸ GATE L4 — Ship Sign-Off
Feature : [slug] — [SHIPPED (deployed) | BUILT & VERIFIED — deploy pending (PO)]
Rounds : [rounds_used]
Verdict : [verdict] (dims: [spec-conformance]; not evaluated: [dims_not_evaluated])
QA : [qa_findings] findings | skipped
Ledger : harness-run.md
Ask (max 1): "Anything to record before I close the run?" On substantive feedback, delegate
Skill(shapeup-sdlc-plugin:coach) for RLHF (its own GATE COACH-1 — the tech lead never
categorizes feedback itself). Then output the final ✅ [slug] … line.
Scope boundary
Owns the Shape Up Building phase (steps 7–11) only. Shaping (1–4), Betting (5) and Kick-off
(6) are PO-personal and upstream: intake is a kicked-off pitch, never a raw idea. The tech lead
never orients, plans, builds, or judges itself — shapeup-run.js sequences the skills that do
and returns to the PO at every gate.
Gate collect-lists + output-block formats →
references/gates.mdHow each sub-skill is invoked + handoff files (the envelope port) →references/protocol.mdThe round loop, stop conditions, three-level breaker rationale →references/protocol.mdRun ledger format + Hill report →references/protocol.md(Part 4 — State) State ownership, the central domain registry, two-ledger split →references/protocol.md(Part 4 — State) Hard rules this design enforces, and why →references/protocol.mdFull invocation examples + the complete flag table → The small-change lane (--tiny) →references/tiny-lane.md
Invocation
/tech-lead --pitch <shaping.md> --spec <spec/> --lens standard for an interactive run; --auto
(pause only at L1a/L1b/L3/L4), --unattended (headless/CI), --from build (resume), --no-eval/
--no-qa to skip passes, --parallel-scopes N to set how many scopes build at once (default 4,
1 = sequential), --adversarial-verify to refute each FAIL finding before it costs a fix round. --tiny stays a prose-only lane (references/tiny-lane.md) —
shapeup-run.js targets specs with committed scope contracts; a tiny change or a pre-scope-
contract spec runs the unchanged v0.2.6 flow this file's Hard Rules already describe.
What ships with it: 31 files
417.3 KB alongside SKILL.md, 18 of them executable
evals/
- trigger-evals.json1.4 KB
references/
- delegation.md16.8 KB
- gates.md23.8 KB
- invocation.md2.3 KB
- ledger-schema.md10.5 KB
- round-protocol.md10.7 KB
- state-model.md3.7 KB
- tiny-lane.md2.4 KB
schemas/
- domain.schema.json88.5 KB
- gate-answers.schema.json4.2 KB
- work-order.schema.json1.5 KB
- work-result.schema.json2.2 KB
scripts/
- aegis-digest.mjsruns4.7 KB
- budget-check.mjsruns7.1 KB
- compile-order.mjsruns26.2 KB
- fit-check.mjsruns9.0 KB
- gate-answers.mjsruns16.2 KB
- ingest-result.mjsruns13.3 KB
- init-run.mjsruns15.6 KB
- lib/argv.mjsruns9.1 KB
- lib/contract-md.mjsruns22.5 KB
- lib/is-main.mjsruns4.6 KB
- lib/paths.mjsruns14.4 KB
- lib/ratchet-tree.mjsruns5.7 KB
- run-snapshot.mjsruns11.6 KB
- ship-report.mjsruns11.0 KB
- stats.mjsruns18.4 KB
- t0-verify.mjsruns22.8 KB
- trace-lint.mjsruns18.8 KB
- validate-envelope.mjsruns14.2 KB
- README.md4.0 KB
Gives 0 of the 12 instructions most plan spec skills give
Counted across 1,360 of the 2,617 authors here whose files we hold, read 2026-09-06
- Ask one question at a timein 73 of 1360
- Write the spec using the templatein 22 of 1360
- Ask clarifying questions if neededin 19 of 1360, across 18 files
- Wait for user confirmation before proceedingin 19 of 1360
- Save plans to the plans directoryin 17 of 1360, across 13 files
- Check for product marketing context firstin 16 of 1360, across 5 files
- Read the plan file completelyin 16 of 1360
- Order tasks by dependencyin 16 of 1360
- Gather context from the conversationin 15 of 1360, across 9 files
- Explore the codebase instead of askingin 15 of 1360, across 13 files
- Wait for explicit user approvalin 14 of 1360, across 13 files
- Quiz the user on the breakdownin 13 of 1360, across 7 files
Said here and by no other author read
- Open the run first
- Re-derive before you act
- Pin GATE L0 and then launch
- Write RunArgs to run-args.json
- Branch on RunReturn status
- Emit block verbatim
Grouped from the skills themselves: near-identical wordings counted once, and counted by distinct author, so one author publishing three of these counts once.