Startup Guide · v2.6

Are you ready to STRAP-IN?

01 · Claude Pipeline Orchestrator

CPO

You. The human at the keyboard. Owns priority, approval, and merge authority. Cannot be impersonated by an agent. STRAP works for you, not around you.

02 · Agent Dev-Lead

Loyal Wingman

The top-level Claude session — the CPO's working partner. Coordinates the 15-agent stack, runs every STRAP skill, curates rules and memory, talks to no one but the CPO.

03 · The Agent Stack

Force Multiplier

Fourteen specialists organized into two teams — agent-ops for planning, agent-devs for implementation. Dispatched in parallel via CreateTeam or serially via Task. Where the 5x-10x lives.

Velocity gain 5x – 10x+
Agents 15
Skills 30+
Connection starters 5
Onboard time ~1 hr
Section 01

Getting Started

A 90-second orientation, then the four commands that take you from a freshly-cloned project to a STRAP-aware workspace ready to ship Requirements end-to-end.

01.1

What is STRAP?

STRAP — the Spec-To-Release Agentic Pipeline — is built to be installed. Drop it into any software project, run a single skill, and a complete software-development team comes online: a planning side that turns ideas into specifications, an implementation side that builds against those specifications, a review side that holds the line on security and infrastructure, and a documentation side that captures it all for the audiences who need to read it.

The point of STRAP is not to remove the human. The point is to give one human the leverage of a small team. The human stays in control: they decide priority, they approve work, they merge pull requests. The agents do the work the human directs them to do, in parallel, with discipline, and with memory that grows alongside the codebase.

And the leverage compounds when more humans join. Multiple humans can each operate their own STRAP super-pair in parallel — N orchestrators, N dev-leads, N agent teams — all working against the same source-controlled persistence stack. The output multiplier scales with the orchestrator count, not just the agent count. One human gets a small team's velocity; N humans get N teams in coordinated motion against shared context.

01.2

Executive Summary

STRAP turns a codebase you don't fully understand into one your team can move on — in an hour, not a quarter.

The moment you install STRAP into a project, it spends about an hour reading the entire codebase the way a senior engineer would on their first week. It captures three things that normally take months to surface:

01 · Orientation

What the project is and who it serves

A plain-language project orientation. Where the code lives, who built it, who it's for, what's in production today — the document new contributors usually have to assemble over their first sprint.

02 · Architecture

How the system is built

A real architectural map. System topology, the major boundaries, where data flows, which patterns recur, where the smells are. The kind of artifact that typically takes weeks of senior-engineer effort or an external consulting engagement.

03 · Security

The risk picture

Concrete findings with file:line citations. Exposed credentials, hardcoded keys, missing auth, injection surfaces, cross-tenant leaks. Not theoretical — specific lines in your binaries today. Two-to-four-week security-audit equivalent, same day.

Then it stays. STRAP doesn't deliver an orientation document and walk away. It installs a coordinated team of 15 AI agents into your project. From the moment onboarding finishes, your team uses STRAP to take ideas through the full software lifecycle:

  • Idea to specification — the requirements lead interviews you, refines the idea, and the spec lead produces an implementable specification with technical depth.
  • Specification to work plan — decomposes into features, stories, and tasks in your existing tracker (Azure DevOps / Jira / GitHub Issues — STRAP connects to what you already use).
  • Work plan to PR-ready code — implementation specialists work in parallel against the codebase; security review runs as a gate; tests are authored alongside the code; the result is a pull request your developers review and merge.

What's different is the leverage shape. Traditional development optimizes for time-to-first-commit. Cost shows up later as rework: ambiguous specs produce ambiguous implementations, cross-layer issues surface late, PRs cycle through five rounds of review. STRAP inverts the curve — it invests deeply upfront in understanding the codebase and refining specifications, then runs implementation in parallel against that prepared ground. By the time a developer reviews a PR, the ambiguity is already gone.

The economic shape is unusual too. STRAP runs inside Anthropic's Claude Code using a per-developer subscription. No separate infrastructure, no API keys to juggle, no SaaS tier. The cost scales with usage. Within that subscription, STRAP enforces explicit token budgets at workflow and session level: every onboarding, feature decomposition, sprint execution runs against a budget the CPO sets and the pipeline holds to. Per-project and per-team usage is forecastable in a way that ad-hoc AI tool use isn't.

The bar

Validation runs to date have shown a force multiplier in feature velocity in the 5x to 10x+ range. The variance reflects how deeply a team integrates STRAP into their daily workflow and how mature the codebase is going in. Older codebases with significant accumulated context get more leverage from the discovery pass; greenfield projects get more leverage from the specification + decomposition pass — teams running STRAP at the pipeline level (not occasional use) routinely sit at the top of the range.

01.3

What's in the Box?

A quick tour of what makes STRAP distinctive. Each item has a deeper treatment further down; here is the shape in one pass.

Discipline over cleverness

STRAP refuses several patterns that other agent setups treat as features. The discipline pays compounding returns.

01

Non-destructive Onboarding

Specialists run read-only during /strap-in and /strap-refresh. Your production code cannot be modified during persistence-stack curation.

02

Centralized Test Execution

Only the dev-lead runs the test suite, in a single pass at PR preparation. Specialists author tests but never run them.

03

Token Budgets

Explicit per-agent + session-aggregate ceilings, set by the CPO once. Tune any time via /revise-token-budget.

04

CPO Authority

Every state transition requires explicit human approval. No agent merges PRs. The leverage is in what you can confidently delegate.

Persistence as Code (PaC)

Context lives where code lives. The persistence stack is source-controlled, PR-reviewable, branch-aware, and shared across every session, developer, and hand-off. STRAP doesn't get smarter by growing more agents; it gets smarter by growing what the agents read.

PaC 01

Agent Context as Code

project-profile.md records what your project IS — stack, conventions, active domains, build commands, sensitivities. Every agent reads it on every invocation.

PaC 02

Agent Memory as Code

Per-agent memory captures project-specific tradecraft; per-agent rules capture guardrails. Soft learnings vs hard constraints, both source-controlled.

PaC 03

Single-Curator Rule

Only the dev-lead writes to rules and memory. Specialists report findings; the dev-lead decides what gets persisted. No drift, no contradictions.

PaC 04

Auto-Discovery

/strap-in reads your codebase at shallow scope, infers the stack, dispatches relevant specialists for read-only deep-dive, and synthesizes findings.

Drop-in integration

Your work-tracking host. Your source-control host. Your existing docs directory. STRAP probes each at connect time and persists per-project profiles that the pipeline reads at runtime.

DI 01

DevOps Integration

Azure DevOps Boards / Jira / GitHub Issues / Local strap-agile / Other. Probes, models, validates, persists. Graceful degradation for unsupported operations.

DI 02

Source Control Integration

Azure Repos / GitHub / Bitbucket / Local Git / Other. Code-immutability invariant releases when wired. Throwaway-branch probes validate end-to-end auth.

DI 03

Work-Tracking as Code

Optional Local (strap-agile) mode — work items become markdown files in git history. PR-reviewable, diffable, branch-aware. The right call for small teams.

DI 04

Seven Logical Work-Item Types

Requirement / Spec / Feature / Enhancement / Story / Task / Bug. Maps to each host's native types via Custom Map UX; strap:<type> tag preserves findability.

Self-documenting outputs

Beyond agent work, STRAP produces durable artifacts your team can review the same way they review code. Each is auditable, diffable, and meaningful at a glance.

SD 01

Project-Docs Pipeline

PROJECT.md + ARCHITECTURE.md + STACK.md rendered from the curated persistence stack. Self-contained HTML companion alongside.

SD 02

Mockup-as-Contract

designer produces deployable mockup code; frontend-engineer ports verbatim. The mockup IS the visual contract.

SD 03

DORA + AI Efficiency Ratio

Editorial-quality reports comparing original estimates vs actual wall-clock cycle times. The wall-clock IS the primary AI-efficiency signal.

SD 04

Cross-Session Continuations

Multi-session work survives via /context-prep + /context-fetch. Multi-developer hand-offs travel through these. No mid-feature work is stranded.

01.4

Quick Start

STRAP installs as a .claude/ folder inside your project's root. From there, four skills bring the pipeline online. Total time: ~45 minutes for the first read-along.

Before you start

Close Claude Code if it's running. The installer writes to .claude/settings.json; an active session may hold a file lock or miss the new permissions until restart.

Open a terminal in the directory where you want STRAP installed. The installer creates .claude/ at your current working directory. Picking the wrong install root means STRAP curates the wrong project — choose carefully.

The installer — choose your OS
macOS · Linux

Pipe-to-shell installer

curl -fsSL https://lmgstrapdist.blob.core.windows.net/releases/install.sh | bash

Pipe-to-shell is the standard pattern. For the security-conscious, download first and inspect: curl -fsSL .../install.sh -o strap-install.sh && bash strap-install.sh. Either way, .claude/ lands in the current directory. To pin a specific version, swap the URL for strap-install-<version>.sh — filename-versioned aliases are published per release.

Windows

PowerShell installer

iwr https://lmgstrapdist.blob.core.windows.net/releases/install.ps1 -OutFile strap-install.ps1
.\strap-install.ps1

PowerShell 7+ recommended; PowerShell 5.1 works. If execution policy blocks the script, run Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned once for your account — one-time setup, not per-install. To pin a specific version, swap the URL for strap-install-<version>.ps1.

The five-skill onboarding sequence
Step 01 · Install curl / iwr installer (commands above)

Downloads a versioned STRAP package, verifies SHA-256, extracts to .claude/, seeds harness permissions in settings.json. Cross-platform; no elevation required.

Step 02 · Onboard /strap-in

The first conversation. Dev-lead reads codebase at shallow scope, dispatches relevant specialists in parallel via CreateTeam for read-only deep-dive, curates the persistence stack. Code is immutable throughout.

Step 03 · Source Control /connect-code-repo

Wires up where git lives. Probes host, models branch + PR + auth, validates, persists profile. The code-immutability invariant releases when this clears.

Step 04 · Work Tracking /connect-devops-project

Wires up where work items live. Same five-step discovery flow. After this, the pipeline can file Requirements, Specs, Features, Stories, Tasks, and Bugs.

Step 05 · First Work /new-requirement <your idea>

Your first production-workflow invocation. req-lead drafts a Requirement work item, identifies open questions, iterates with you toward Resolved.

Three install-root shapes STRAP recognizes
ShapeWhere install landsWhat /strap-in does
Monorepo / single-repo ~/source/repos/MyApp/ Treats the directory as one project, dispatches specialists against all of it.
Polyrepo umbrella, bare sub-repos are siblings, no umbrella git ~/source/repos/MyUmbrella/ Detects sub-repos at depth-1, offers three-way CPO choice (umbrella mode / per-sub-repo / single-project escape).
Polyrepo umbrella, workspace umbrella tracks shared config + .sln ~/source/repos/MyPlatform/ Same detection; umbrella may carry its own git for shared config / docs / CI.
Tip

You don't need to set anything up in your DevOps tool ahead of time. /connect-devops-project probes what's there, models it against STRAP's logical operations, and surfaces any gaps with degradation paths before you commit.

Section 02

Core Principles

The architecture rests on three invariants. Once you internalize the super-pair, the agent roster, and the single-curator rule, the rest of STRAP makes sense.

02.1

The Super-Pair

Every STRAP session is operated by a two-entity super-pair. This identity is invariant — it does not change between sessions, between releases, or between adopters.

The Super-Pair Invariant

You — the human typing the prompts — are the CPO. The Claude Pipeline Orchestrator. You set priority. You approve work. You decide. Your authority is non-negotiable; no agent can impersonate you and no skill can run a state transition without your sign-off.

Claude itself — this session — is the dev-lead. Your working partner. The dev-lead does not write production code directly. It coordinates the team, dispatches specialists, synthesizes their work, curates their rules and memory, and brings everything back to you. It is the only agent that talks to you; everyone else routes through it.

Human authority

The CPO

The human typing the prompts. Owns priority, approval, and decision authority. Cannot be impersonated by an agent.

  • Sets priority and approves work
  • Approves every meaningful gate
  • Merges every pull request
  • Directs persistence-stack curation
  • Cannot be impersonated by any agent
Top-level agent

The dev-lead

The top-level Claude session. The CPO's working partner. The only agent that talks directly to the CPO.

  • Dispatches specialists via Task / Agent / CreateTeam
  • Curates rules + memory under the single-curator rule
  • Synthesizes specialist findings
  • Runs every STRAP skill end-to-end
  • Reports back to the CPO at every gate

Everything else extends from this one relationship.

02.2

Meet the Agent Team

Fifteen agents ship with STRAP. The roster is fixed: the same fifteen ship to every adopter, every install. They do not get renamed, replaced, or regenerated. They are dormant when not needed and active when work comes their way. Over time the dev-lead refines them — adding rules where guardrails are needed, adding memory where tradecraft is worth keeping — but the roster itself stays canonical.

agent-ops The planning & coordination team
7 specialists

Authoring chains, mockups, documentation, sprint cadence, governance, testing.

RL

req-lead

Owns Requirements. Refines raw ideas into structured Requirements with a clear Problem Statement, Desired Outcome, Success Criteria, and Scope. Allergic to vague problem statements.

SL

spec-lead

Takes resolved Requirements and produces Specs with enough technical depth that implementation can decompose without coming back for clarifying questions. The bridge between "what" and "how."

DG

designer

Interviews on intent, audience, scope, fidelity tier. Produces deployable mockup code — actual interactive mockups — that frontend ports verbatim. The mockup IS the visual contract.

TW

tech-writer

Drafts feature pages, release notes, use-case guides, API docs, architecture docs, how-to guides. Adapts tone to configured audience: community vs code.

SP

sprint-planner

Allocates Stories and Tasks into the current sprint (single-sprint constraint). Tracks velocity. Surfaces capacity conflicts rather than silently spilling.

DA

dora-analyst

Tracks DORA-4 metrics plus an AI Efficiency Ratio that leverages the AI tag to distinguish AI-authored from human-authored work.

UX

ux-test-engineer

Derives test plans from Spec acceptance criteria. Authors and runs E2E suites. Files structured Bug work items with reproduction steps + evidence.

agent-devs The implementation & verification team
8 specialists

Coordination, implementation across all layers, OWASP gate, IaC, test strategy.

DL

dev-lead

The top-level Claude session. Never a subagent. Coordinates specialists, curates persistence, runs every STRAP skill. The only agent that talks to the CPO directly.

BE

backend-engineer

Server-side code: domain entities, application services, transport handlers, data-access seams. Holds the line on clean architecture and DI. Authors tests; never runs them.

FE

frontend-engineer

Client-side code across web, desktop, mobile, native, server-rendered form factors. Respects store-ownership and parent/child contracts. Ports mockups verbatim when they exist.

DB

database-engineer

Owns the persistence layer: entity definitions, schema migrations, indexing. Applies migrations to local dev only. Production / UAT / shared-dev are pipeline-only. No exceptions.

OP

devops-lead

Owns IaC, cloud fabric, pipeline definitions. Authors and surfaces defects. Never runs apply / deploy against environments with dependents.

SR

security-reviewer

OWASP-aligned audit gate. Reviews authn, authz, tenant isolation, input validation, injection, secrets handling, error-response hygiene. Critical and High findings block merge.

IS

integration-specialist

Owns external-system integration. Dynamic endpoints, per-tenant config stores, retry policies, bidirectional mapping at trust boundaries. Dormant when no external surface exists.

TS

test-strategist

Authors test strategy at the Feature level, reviews coverage intent, triages failures the dev-lead redispatches. Does not run tests — that is the dev-lead's centralized responsibility.

The full stack is always present; what changes per install is the persistence stack the dev-lead curates over the project's lifetime. Agents stay simple. Intelligence accumulates in the persistence.

Three hard rules

1. Specialists never talk to the CPO directly. They report through the dev-lead.

2. Specialists never spawn other specialists. The dev-lead is the only fan-out layer.

3. Specialists never run the test suite. The dev-lead is the centralized executor at PR preparation.

02.3

The Single-Curator Rule

Single-Curator Invariant

Only the dev-lead writes to rules and memory. Specialists report findings; the dev-lead decides what gets persisted. The CPO directs the dev-lead through normal conversation — "save this learning to the backend-engineer's memory" — or through the explicit /memory-refine <agent> skill.

This rule exists because curated context is what makes STRAP compound over time. If specialists could write their own rules and memory, the persistence stack would drift — contradictions accumulate, stale tradecraft persists, the project profile loses coherence. One curator keeps the persistence stack tight.

The persistence stack at a glance
LayerPurposeLifetime
Team rulesCross-cutting team-level guardrails. STRAP-wide conventions that ship verbatim to every adopter.Stable
Per-agent rulesPer-agent guardrails added reactively when something needs preventing.Reactive growth
Per-agent memoryAccumulated tradecraft for THIS project. Soft learnings, not rules.Grows over time
Project profileThe canonical record of what THIS project IS. Stack, active domains, conventions, build/test commands.Refined
Dev-lead memoryThe dev-lead's own categorized notes, indexed by a master file.Grows over time
ContinuationsCross-session topic snapshots. Workstreams that span sessions get a runbook captured by /context-prep.Topic-scoped
Connection profilesPer-project work-tracking + source-control wire-up. Env-var references only — credential values never enter tracked files.Per host

Six months into a project, the per-agent memory files describe how to do the job well on this specific codebase. New developers operating as the CPO inherit that institutional knowledge automatically — it is source-controlled, it travels with the repo, it survives staff changes.

The agents themselves stay simple. The intelligence is in the persistence stack.

Section 03

Workflows

Three operational shapes. Onboarding (the super-pair meets the project), Production (the canonical pipeline from idea to PR), and Full Auto (the one-shot spec-to-PR motion).

03.1

Onboarding Workflow

The onboarding sequence runs once per project (with a re-runnable refresh available later). It establishes the persistence stack, wires up the DevOps host, wires up source control, and releases the "satisfied" gate that transitions from onboarding mode to operational mode.

Phase 01 /strap-in

Codebase discovery, specialist dispatch, persistence-stack curation, project-docs authoring.

Phase 02 /connect-code-repo

Wire source control. Auth recipes per host. Branch protection capture. Code-immutability releases.

Phase 03 /connect-devops-project

Probe host, model logical-to-host work-item mapping, probe state machines + fields, persist profile.

What each phase produces
PhaseWritesWhat it enables next
/strap-inproject-profile.md, per-agent rules + memory, project-docs HTML companionThe 15 agents come alive against this project's specific shape
/connect-code-repocode-connection.yaml with branch-protection + operation_templatesThe pipeline can open PRs; the satisfied gate releases the onboarding invariant
/connect-devops-projectdevops-connection.yaml with mapping + state asymmetries + operation_templatesWork-tracking resolves at runtime via the universal interface
Code Immutability Invariant

Throughout onboarding, the adopter's production code is immutable. Section 6 specialists run with a read-only tools palette (Read, Grep, Glob, Bash — no Write, no Edit); the source under inspection cannot be modified during onboarding. The Section 9 project-docs production phase is a narrow exception — tech-writer writes only to configured Project docs paths, never production source. The invariant fully releases when /connect-code-repo clears its satisfied gate.

Re-runnable

/strap-refresh reads the existing persistence stack as priors, runs a shallow scan against the current codebase, detects diffs, surfaces them for CPO approval before dispatching, then applies surgical edits. CPO edits, narrative additions, and prior-refresh curation are preserved. Whole-file rewrites at refresh time are a defect, not a feature.

03.2

Production Workflow

Once onboarding is complete, the production pipeline runs through a tight set of skills. Each follows the same pattern: dev-lead owns the CPO conversation and host-side persistence; specialists are dispatched for focused work; every persisted item carries lifecycle metadata; every state transition is audited.

Authoring chain

/new-requirement · /refine-requirement · /create-spec · /refine-spec · /generate-features · /decompose-feature

req-lead drafts Requirements; spec-lead authors Specs and Feature briefs; dev-lead persists. /decompose-feature activates required domains (CPO-gated structural precondition) and dispatches active-domain specialists in parallel via CreateTeam for read-only planning, then reconciles and persists Stories + Tasks.

Mockup tier user-facing

/create-mockups · /analyze-mockups

Runs between Spec resolution and Feature generation when the Spec carries user-facing scope. /create-mockups dispatches designer to interview, build deployable mockup code, iterate (re-runnable; CPO approval at every gate), and write the Mockup Reference back to the Spec. /analyze-mockups dispatches spec-lead to audit completeness, map mockup data shapes to backend API declarations, and write the Mockup Wiring Guide. /generate-features refuses to run on user-facing Specs missing either section.

Test plan tier

/create-test-plan

Authors an end-to-end test plan for a Spec or Feature and optionally scaffolds initial test files. Dev-lead dispatches ux-test-engineer as serial-Task specialist to read the Spec, codebase, and framework conventions; produce a structured plan; and scaffold runnable tests. ux-test-engineer is the third closing-phase write-exception alongside designer and tech-writer.

Execution

/plan-sprint · /rebalance-sprint · /execute-sprint

/plan-sprint allocates into the current sprint only (hard single-sprint rule; overflow stays unallocated). /execute-sprint creates the feature branch, dispatches active-domain specialists into per-agent worktrees, reviews each task branch, runs the centralized build-and-test pass, sets completion metadata at resolution, and prepares the PR.

Bug tier

/file-bugs · /fix-bugs

/file-bugs accepts informal CPO input, dispatches an intake specialist read-only for investigation and classification. /fix-bugs is the lighter sibling of /execute-sprint for Bug + Enhancement work items — targeted fixes, no Story decomposition, same metadata round-trip at resolution.

PR feedback

/refine-pr

Reads reviewer comment threads and failed CI checks via the source-control connection profile, categorizes by domain, dispatches the relevant specialists in parallel (or serially for file-conflicting fixes), runs the centralized build-and-test pass, pushes updates to the existing feature branch. Thread resolution stays with the human reviewer.

Close ritual

/close-ceremony

The deliberate CPO ritual for transitioning Resolved work items to Closed — the only authoritative manual gate. The execution skills stop at Resolved by design; this ritual is where the CPO walks Resolved Features, Enhancements, Bugs, and lingering Stories and decides per item: close / reject with rework tag / defer with reason tag / skip.

DORA governance

/dora-reconcile · /dora-collect · /dora-report

/dora-reconcile runs daily (cascades) or weekly with --auto-fix (stamps derivable hygiene). 8 reconciliation passes keep the AI-tag + lifecycle-metadata wiring honest. /dora-collect writes a JSON snapshot of work items, pipeline runs, and PRs. /dora-report renders a self-contained HTML report with embedded Chart.js. Wall-clock as primary AI Efficiency Ratio.

CPO tuning surfaces

/memory-show · /memory-refine · /revise-token-budget

/memory-show inspects per-agent memory; /memory-refine curates it under CPO direction. /revise-token-budget is the canonical surface for tuning STRAP's token budgets after /strap-in's initial setup — per-workflow per-agent and session-aggregate budgets, plus per-agent overrides. Persists with an append-only audit trail.

Single-motion path

/quick

The CPO "do now" lever. Free-form description through classification, work-item chain creation, specialist routing, implementation, centralized test pass, and draft PR — in one invocation. Five chain shapes; flags --under, --into, --mockup, --investigation, --stacked, --draft. Hard CPO approval gate after classification. Never refuses for size.

Recovery and continuation

/team-cleanup · /context-prep · /context-fetch

/team-cleanup recovers from wedged team state. /context-prep captures cross-session continuation runbooks; /context-fetch loads them as session-startup context. Multi-session and multi-developer workstreams travel through these.

03.3

Full Auto (Spec to PR)

Full Auto is STRAP's autonomy uplift. You have a Resolved Spec. You want to walk away. The dev-lead takes the Spec end-to-end — generates Features, decomposes each, allocates everything into the current sprint, executes across all Features in parallel, opens a draft PR per Feature — without asking your permission at every phase boundary. The Resolved Spec IS the contract. You already approved the intent when you Resolved the Spec; re-approving the same intent at every step adds no signal.

What does not collapse: the safety perimeter. PRs land as drafts — you merge, never the skill. security-reviewer Critical/High blocks the affected Feature. Spec mutation during the run is forbidden. New domain activation halts. These are not "settings"; they are the contract.

Entry precondition
Resolved Spec
CPO gates
1 entry contract
Features per run
N parallel
PRs produced
N drafts
Auto-merge
Never

When to reach for it good fit

/execute-sprint-full-auto <spec-id>

The Spec is well-shaped — Constituent Parts are clear, acceptance criteria resolve to concrete behavior, mockups (if user-facing) are locked in, the Wiring Guide is written. The work is multi-Feature in scope but each Feature is independently executable. You trust the Spec to be the contract and you want the pipeline to run hands-off. You'll be reading the conversation as the dev-lead emits checkpoint summaries, but you don't intend to intervene unless something genuinely needs you.

When NOT to reach for it wrong tool

/quick · /execute-sprint · /refine-spec

The Spec is rough or under-defined — use /refine-spec first; do not let Full Auto paper over Spec defects. The ask is free-form ("change the timeout from 5s to 10s") — use /quick; classification is what you need, not a multi-Feature run. The work is exactly one Feature already decomposed and sprint-allocated — use /execute-sprint; Full Auto is overkill. New specialist domains are required — activate them deliberately via /decompose-feature first, not mid-Full-Auto.

The composed motion

/generate-features · /decompose-feature · /plan-sprint · /execute-sprint

Full Auto inlines four production-workflow skills. It does not invoke them as separate skills (that would reintroduce per-skill approval gates). It walks the same phases with the same primitives — spec-lead authoring, specialist parallel planning via CreateTeam, worktree mechanics, centralized test execution — and stamps the full-auto tag at every persist.

Phase 4 (decomposition) is serial across Features but parallel within each — same as today's /decompose-feature baseline. Phase 6 (execution) is parallel across Features AND parallel within each — one team, one worktree, one feature branch, one draft PR per Feature, all running concurrently. The throughput uplift lives in Phase 6.

Gates that collapse dev-lead authority

Feature briefs · Decomposition · Sprint allocation · Per-task review

Feature brief approval (per /generate-features), per-Feature decomposition approval (per /decompose-feature), sprint capacity review (per /plan-sprint) — all collapse to dev-lead authority. The dev-lead acts. You watch the checkpoints. Per-task review remains because it is a quality gate (did the specialist implement what the Task says?), not a CPO-approval gate — the dev-lead runs it inline.

The Safety Perimeter · never collapses

The dev-lead halts and surfaces to you when ANY of the following trips. These are non-negotiable invariants, not configurable behaviors:

  • No auto-merge. PRs land as drafts. You convert to ready-for-review and merge.
  • security-reviewer Critical/High blocks. The affected Feature cannot Resolve until cleared. Other Features in the run continue independently.
  • No Spec mutation during the run. The Spec is locked. Mid-run Spec edits happen only via the Ambiguity Halt "Clarify here" branch, which is explicit and audited.
  • No silent new-domain activation. A Spec requiring an inactive specialist domain is a structural change to the project; the run refuses Phase 1 and surfaces.
  • No skip of centralized test execution. Build + tests run per Feature; failures halt that Feature before its PR opens.
  • No bypass of the per-task dev-lead review. Quality gate stays; specialists do not auto-land work without review.

Spec-Ambiguity Halt — the contract-protection interrupt

Clarify here · Pause to /refine-spec · Proceed with logged assumption

The most important non-obvious behavior in Full Auto. A "well-scoped Resolved Spec" is the contract, but decomposition or execution may surface gaps the Spec author did not anticipate. When a specialist flags ambiguity, incompleteness, or contradiction in its finishing report, the dev-lead halts the affected scope and asks you to choose: edit the Spec inline (additive amendment with audit comment; Spec stays Resolved), pause Full Auto and return to manual /refine-spec (the partial chain is preserved tagged full-auto-partial), or proceed with the dev-lead's best-judgment assumption (logged verbatim in the affected Feature description).

Three-strikes rule: if three Spec-Ambiguity Halts fire in one run, the dev-lead escalates and recommends cancelling + running /refine-spec. The Spec is likely not Full-Auto-ready; clarifying it to death mid-run is the wrong outcome.

Async observability — checkpoints without breaking flow

Phase boundaries · Per-Feature completion · Token consumption

The dev-lead emits structured checkpoint summaries at every phase boundary — Run Contract drafted, Features generated, each Feature decomposed (one per Feature in Phase 4), sprint allocated, each Feature executed (one per Feature in Phase 6 as they complete in arrival order, not creation order), PRs opened. Each checkpoint lists items created, branches, tokens consumed, time elapsed, what comes next.

Checkpoints are conversation output only. They do not gate. They do not require acknowledgment. You read them in real-time if you want; you ignore them if the run is going clean. Per-Feature granularity is the default — per-Task checkpoints would drown the conversation on a 50-Task run.

Worked example · single small Spec

~2-3 Features · ~6-15 Tasks · one repo

You Resolved a Spec for a self-contained UI enhancement: refactor the audit-log filter chrome and add tenant-id scoping. Two Constituent Parts (client-ui for the chrome, api for the tenant-scoped query). Full Auto generates two Features, decomposes them in sequence (~4 minutes each), allocates 8 Tasks into the current sprint, then runs Phase 6 with two teams in parallel. ~25 minutes wall-clock end-to-end. Two draft PRs land in the source-control profile, each with the Run Manifest in its description and acceptance criteria mapped to specific commits + tests.

Worked example · medium multi-Feature Spec

~5 Features · ~30 Tasks · one repo · multiple domains

You Resolved a Spec for a billing-pipeline overhaul: new invoice schema, migration, API surface, frontend display, observability. Five Constituent Parts; backend-engineer, database-engineer, frontend-engineer, devops-lead, and security-reviewer all active. Full Auto generates five Features, decomposes them serially in Phase 4 (~25 minutes), then runs Phase 6 with five teams in parallel. The 60% session-aggregate budget checkpoint fires around the third Feature's execution — the dev-lead surfaces, runs /context-prep, you /clear and resume with /context-fetch. Five draft PRs land. Total wall-clock ~90 minutes across two sessions.

Worked example · polyrepo umbrella Spec

~4 Features · ~20 Tasks · 3 sub-repos · cluster manifest

You Resolved a Spec on a polyrepo umbrella with three sub-repos (shared-types, api-backend, web-frontend). One Feature is cross-sub-repo (a new type defined in shared-types, consumed by both downstream sub-repos); three Features are single-sub-repo. Full Auto's Phase 1 builds the cluster manifest with the F6 dependency graph (shared-types first, then the two downstream sub-repos in parallel). Phase 4 decomposes each Feature against the right sub-repo's specialists. Phase 6 runs four teams in parallel; the cross-sub-repo Feature opens three coordinated PRs with cluster-manifest cross-references; the single-sub-repo Features open one each. Total: seven draft PRs. The dev-lead enforces merge-order at PR-merge time per the F6 graph — you merge shared-types first, then the others.

When the dev-lead surfaces

You will see the conversation pause and a structured question land in one of three categories: safety-perimeter halt (security finding, new-domain activation, profile mutation), Spec-ambiguity halt (three options to resolve the gap), or budget checkpoint at 60% (recommendation to /context-prep + /clear + resume). Anything else is a checkpoint summary — output-only, no action needed.

Force Multiplier

Full Auto is where STRAP earns the 5x-10x velocity claim. Not because it skips work — the same Features get generated, the same Tasks get implemented, the same tests get written, the same PRs get opened. The multiplier is in the orchestration: parallel-across-Features execution, collapsed approval-gate ceremony, and a dev-lead acting on Spec-as-contract authority. The CPO is still the deliberate gatekeeper — just at the entry and at PR-merge time, not at every phase boundary in between.

Section 04

DORA Governance & Reports

The DORA report is the deepest single instrument STRAP exposes for evaluating how the team is performing. Editorial-quality output every release cycle, grounded in the data the pipeline already records.

04.1

Getting the most from reports

The /dora-report skill renders a self-contained HTML document covering 10+ per-sprint sections, a multi-sprint comparison view, and an in-flight "right now" view. It draws on every work item, every pull request, every pipeline run, and every commit STRAP's adapters can reach.

The report is only as sharp as the data it consumes. The disciplines in Operational Disciplines are what keep the report sharp instead of noisy — environment-tagging, OriginalEstimate, CompletedWork, weekly /dora-reconcile, per-sprint /close-ceremony.

Per-sprint sections
10+ views
Comparison views
N sprints
In-flight view
Live
Per-dev profiles
UNION
Verify-then-write gates
6/6

The 5-asset engine architecture (engine-head.html + engine-render.js + engine-tail.html + build-payload.js + assemble-report.js) makes the visual rendering repeatable across adopters. The engine is verbatim CPO-approved design — adopters never edit the engine assets to retune visuals. If a section needs a value not computed, the fix is to populate the PAYLOAD field, not rewrite the engine.

04.2

DORA-4 Instruments

The four canonical DORA metrics. Each draws on a specific set of fields STRAP records on work items, pull requests, and pipeline runs.

01 · DEPLOYMENT FREQUENCY

How often you ship to production.

Pipeline runs whose definition matches the sub-repo's pipeline_match_patterns AND target a deployment_targets[].environment: prod.

What feeds it: Pipeline runs · pipeline_match_patterns · deployment_targets: declarations.

Where it gets noisy: PR-trigger pipelines inflate counts; non-merge runs need filtering. Pattern-match per pipeline name AT /connect-devops-project Step 6 substep 3.

02 · LEAD TIME FOR CHANGES

Wall-clock from PR open to PR merge.

Pull requests in the window with targetRefName == default_branch. Intermediate-target PRs surface separately, not counted toward DORA-4.

What feeds it: pull_request.creationDateclosedDate; default_branch field.

Where it gets noisy: Long-lived feature branches inflate. Hotfix-merges deflate. Both are surfaced via P50/P90 split.

03 · CHANGE FAILURE RATE

Percentage of prod deploys that yielded a Bug.

Bugs filed in the failure window (default 72h) after a prod deployment, with environment: prod.

What feeds it: environment field on Bugs · env:prod tag · CFR window config.

Where it gets noisy: Untagged Bugs (closed by v2.5 #39919) · window too generous inflates · long-tail regressions.

04 · MEAN TIME TO RESTORE

Median time from prod Bug filed to Resolved.

Bug work items with environment: prod AND a Resolved (or Closed, when no Resolved state exists) transition in window.

What feeds it: CreatedDateResolvedDate · host-specific field aliases.

Where it gets noisy: Long-tail restorations land in later report · "not a bug" / "duplicate" filtered by default.

04.3

STRAP Instruments

Beyond the canonical DORA-4, STRAP computes complementary instruments that surface what's unique about an AI-assisted SDLC.

01 · AI EFFICIENCY RATIO

Estimated effort vs. wall-clock delivered.

Sum of OriginalEstimate hours divided by CompletedWork. >1.0 beat the estimate; <1.0 took longer.

Required: OriginalEstimate set at Task creation; CompletedWork stamped at Resolved transition.

02 · PR ITERATION COUNT

Review-intensity proxy from RefUpdate events.

Buckets PRs into Small / Medium / Large / XL by update events. Useful as a "review velocity" lens when the team is hypothesizing about flow.

Optional: Falls back gracefully when the host doesn't expose thread data.

03 · AGENT VS HUMAN

AI-authored share of sprint output.

Tasks tagged AI (set automatically at creation) vs. untagged. Surfaces the AI-assisted share at-a-glance.

Configurable: mapping.strap_instrumentation_signals tunes the signal mix.

04 · AGING ALERTS

Stale work items, split by origin.

Tasks not updated in >N days. v2.5 splits STRAP-instrumented from inherited so adopters see whether STRAP's process is actually accelerating the stuck items, or just inheriting the same backlog.

05 · CYCLE TIME PER DEV

Sprint-over-sprint trend bars per dev.

Per-developer trend lines + roll-up totals. Reveals the texture of where time goes rather than just an aggregate.

06 · PR WEIGHT GRADIENT

Lines-changed buckets (opt-in).

Run /dora-collect --with-git-diff-weight to add a Small / Medium / Large / XL distribution. Cost: ~5-10 minutes per 100-PR window. v2.5 #39720 added the Raptor-shape schema.

04.4

Operational Disciplines

Six adopter disciplines keep the data layer clean. The DORA report sharpens with each one practiced; it dulls with each one neglected.

DisciplineWhat it controlsCadence
Environment-tagging Bugs CFR + MTTR attribution. v2.5 #39919 makes /file-bugs always prompt via AskUserQuestion. Every Bug
OriginalEstimate Tasks AI Efficiency Ratio numerator. /decompose-feature prompts at decomposition; manually-added Tasks need it set. Every Task at creation
CompletedWork Tasks + Bugs AI Efficiency Ratio denominator. STRAP stamps at Resolved transition; manual resolutions need backfill. At Resolved transition
Layers + Sub-repos + deployment_targets Per-layer Deployment Frequency, Lead Time, CFR scoping. Polyrepo-only. Configured at onboarding
/dora-reconcile --auto-fix Auto-cascades + 8 hygiene passes. Catches drift early. Weekly
/close-ceremony Per-sprint deliberate value-acceptance: Close / Reject / Defer / Skip per Resolved item. Every sprint boundary
Rule of thumb

If a metric looks surprising, the first question is "what does /dora-reconcile say about the data quality flags?" — not "is the metric wrong?". The report surfaces data-quality flags inline so you can audit before interpreting.

04.5

Configuration

The DORA report honors three configurable surfaces in devops-connection.yaml's mapping: block. None are required — sensible defaults apply when absent — but tuning them to your team's norms makes the report's narrative match your reality.

Config keyWhat it controlsDefault behavior
dora_confidence_thresholds Per-metric thresholds for the colored confidence pill on each DORA-4 instrument. Sensible defaults shipped in v2.5 #39701; tune to team cadence.
strap_instrumentation_signals Aging Alerts split between STRAP-instrumented and inherited items. Default tags_any: ["AI"]; extend with custom workflow signals.
cross_version_field_aliases Honors field renames detected across host process-template upgrades. Populated automatically by /connect-devops-project re-run rename flow (v2.5 #39702).

The CLI flag --with-git-diff-weight on /dora-collect is the only opt-in tuning beyond the YAML. It adds the PR Weight gradient block at the cost of ~5-10 minutes per 100-PR window.

Section 05

Upgrades & Customization

STRAP releases bring polish and new capabilities. Your customizations stay. The upgrade machinery is the load-bearing system that makes this true.

05.1

Upgrading STRAP

The upgrade story is one paragraph long: /strap-upgrade fetches the new release and the previously-installed release from the distribution URL, performs a three-way diff against your install, classifies every file, applies non-conflicting upstream changes, and surfaces conflicts for CPO resolution. Adopter customizations on protected paths are preserved.

Category A · Adopter-owned

Never touched

These paths represent state owned entirely by the install or the installer. Excluded from the diff entirely; even package-only adds are NOT applied.

  • .strap-version.json
  • settings.json + settings.local.json
  • project-profile.md
  • Continuations, state, work-items
  • Connection profiles
Category B · Seeded-then-curated

Reconcile (v2.5)

Package ships seeds; adopter dev-lead curates over time. v2.5 #39694 + #39696 add byte-equality reconcile with subtype split.

  • strap/rules/agents/*.md rules-doctrine
  • strap/memory/agents/*.md memory-tradecraft
  • strap/memory/MEMORY.md
  • strap/memory/dev-lead/
The upgrade gates the CPO sees
  1. Mode selection. Distribution mode (default; fetches from distributionUrl recorded at install) or source mode (--from-source, for STRAP-on-STRAP development).
  2. Plan presentation. File-classification counts, adds list, overwrites list, conflicts list, Category B reconcile candidates (v2.5).
  3. Category B reconcile gate v2.5. When Category B files match the prev seed byte-for-byte AND upstream improved them, surface a per-subtype AskUserQuestion: Keep install / Apply all upstream improvements / Review per-file.
  4. Main approval gate. Apply / Apply with conflict strategy take-package / Apply with keep-install / Pause / Cancel.
  5. Phase 7 schema migrations. Re-reads SKILL.md from disk (v2.5 #39695) so new migrations execute. Diagnostic surface shows fired / already-applied / cpo-skipped / n/a.
Major-version refusal

STRAP refuses to auto-apply a major-version bump. Major releases carry breaking schema changes that the auto-merge cannot safely land. Read the release notes, then re-invoke with --target-version explicitly to opt in.

The approval gate options at a glance
OptionWhat it doesWhen to use
Apply (skip conflicts)Apply clean changes; conflicts stay unchangedDefault when you want to land upstream improvements without making conflict decisions now
Apply · take-packageOverwrite every conflict with the package versionYou haven't deliberately customized the conflicting files; surface still requires a second confirmation
Apply · keep-installLeave every conflict file aloneYou actively customized the conflicting files; package updates to those files are NOT applied
PauseStop without changes; write a pending state fileResolve conflicts manually, re-invoke
CancelAbandon the upgrade; no state fileDecided you don't want to upgrade right now
05.2

Customizing STRAP

STRAP is opinionated by design and the customization surface is much narrower than typical platform-style frameworks — the canonical roster is fixed, the skill catalog is fixed, and per-project tuning happens through a small set of curated files the dev-lead writes on the CPO's direction.

The four tunable surfaces
SurfaceWhat lives hereEditor
Project profileproject-profile.md — stack, active domains, conventions, build/test commands, DevOps integration, optional Layers section for DORA partitioning.dev-lead (CPO directs)
Per-agent rulesrules/agents/<agent>.md — per-agent guardrails added reactively when something needs preventing.dev-lead (CPO directs)
Per-agent memorymemory/agents/<agent>.md — accumulated tradecraft for this project.dev-lead (CPO directs)
Connection profilesstate/devops-connection.yaml, state/code-connection.yaml — per-project wire-up./connect-* skills
05.2.1

Tuning Project Shape

The project profile at .claude/strap/contexts/project-profile.md is the canonical record of what this project is: stack, conventions, commands, architecture, active domains, sub-repos (polyrepo), deployment targets.

Three structural levers most often touched
Lever 01

Active domains

Which of the 15 specialists are actively engaged on this project. An agent that isn't in the active set is idle — not deleted, just not dispatched. Change it as your project evolves.

Lever 02

Sub-repos (polyrepo)

The per-sub-repo block carries Role, Active domains, Build command, Test command, Deployment target. /dora-collect reads these for per-layer metrics.

Lever 03

Deployment targets

Declarative deployment topology in devops-connection.yaml. Drives the per-target Deployment Frequency math and the per-target pipeline funnel.

Run /strap-refresh after major changes to ensure the persistence stack updates against the new shape.

05.2.2

Tuning Specialist Behavior

When a specialist almost made a mistake or has accumulated tradecraft worth keeping, the dev-lead curates per-agent rules or per-agent memory.

Hard constraint

Per-agent rules

Guardrails. "Don't push directly to main." "Always run the test suite from the repo root." Added reactively when something needs preventing.

Path: .claude/strap/rules/agents/<name>.md

Soft tradecraft

Per-agent memory

Soft learnings. "The test runner takes 8 minutes after fresh deps; warm it once first." "This codebase prefers the older mapping pattern for X." Grows naturally as work happens.

Path: .claude/strap/memory/agents/<name>.md

The CPO can direct curation explicitly via /memory-show <agent> to see what's already there and /memory-refine <agent> to update. Both flow through the dev-lead under the single-curator rule.

05.2.3

Tuning Token Budgets

STRAP workflows ship with default per-workflow per-agent budgets, plus session-aggregate ceilings. The defaults are tuned for medium-complexity adopter projects; large-codebase adopters routinely raise them, small-project adopters lower.

/revise-token-budget is the canonical knob. It lists current per-workflow per-agent budgets and the session-aggregate ceiling, lets the CPO revise any of them (or layer a per-agent override on a workflow default), and persists to .claude/strap/state/usage.yaml plus an entry in MEMORY.md recording the revision rationale.

When to raise

If a specialist is repeatedly hitting its budget on routine work (you'll see the warning in the dev-lead's status reports), raise that specialist's budget for the relevant workflow. If multiple specialists are hitting at the same time, raise the session-aggregate ceiling.

Polyrepo sessions show the additive projection — "3 sub-repos detected; projection: 1M + 2 × 300K = 1.6M" — so cost is never hidden. Revisions apply to new workflow instances only; in-flight work continues against the budget it started under.

05.2.4

Adding Custom Agents

Your project has a specialist STRAP doesn't ship by default — a payments-domain engineer, a regulatory-compliance reviewer, a stack-tier engineer for an esoteric runtime. The 3-step ceremony adds it. /strap-upgrade naturally protects your additions; you don't lose them when STRAP releases.

Step 01 Drop role contract

Author .claude/agents/agent-{ops,devs}/<name>.md following the existing role-contract pattern. Frontmatter declares the agent type, description, tools.

Step 02 Seed rules + memory

Drop .claude/strap/rules/agents/<name>.md + .claude/strap/memory/agents/<name>.md with seed guardrails + tradecraft.

Step 03 Wire into profile

Add the new specialist to project-profile.md's relevant Specialists field on the active Domain. Dev-lead dispatches it from the next invocation onward.

From that moment, every pipeline skill that reads active-domain specialists routes work through the custom agent like any canonical one. Cross-cutting agents (compliance reviewer, project-specific governance) fit naturally as additional Specialists on existing canonical domains.

/strap-upgrade is safe

Custom additions are always preserved: adopter-authored agents and skills land at paths the package never ships to (classified install-only); per-agent rules and memory live in already-protected directories; project-profile.md edits are Category A adopter-owned. The CPO cannot accidentally break the upgrade path by extending STRAP.

What is NOT supported

In-place edits to package-shipped artifacts. Editing a canonical agent's role contract file, a STRAP-shipped SKILL.md, or the team rules files directly surfaces as a conflict on every upgrade. The supported path for behavior changes is per-agent rules curation (stacks on top of the canonical role contract at runtime). For skill replacements, add a new skill with a different name.

STRAP Startup Guide. v2.6 · A Leo Motion Group portfolio project · Maintained by the STRAP Contributors.

This is a manually curated companion to Welcome-to-STRAP.html (auto-generated from the seven narrative source docs). Editorial quality is intentional. For deeper coverage of specific topics: walkthrough.md, dora-tuning.md, architecture.md, customization-guide.md, upgrade-guide.md.