strap-in

how a small team of AI specialists ships software under one human's authority

This chapter is the onboarding deep-dive: the team that comes online when STRAP meets your project, the persistence stack the dev-lead curates for it, the four-skill onboarding flow, and the work-tracking-as-code option. For what STRAP is and the shape of the box, start at the Welcome chapter.

Meet the Agent Team

Fifteen agents ship with STRAP. Together they form a complete software-development team. They are stable: the same fifteen ship to every adopter, every install. 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 agents themselves do not get renamed, replaced, or regenerated.

The team splits into two halves. agent-ops plans and coordinates. agent-devs implements and verifies.

The super-pair at the center

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, the one you are talking to right now -- 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.

This is the super-pair. Everything else extends from this one relationship.

agent-ops -- the planning and coordination team

req-lead owns Requirements. When you bring a raw idea -- a customer complaint, a market opportunity, an operational pain point -- req-lead refines it. Asks probing questions one at a time. Surfaces open questions and tracks them. Forces decisions where stakeholder needs conflict instead of papering over them. Writes the result as a structured Requirement with a clear Problem Statement, Desired Outcome, Success Criteria, and Scope. Allergic to vague problem statements.

spec-lead owns Specifications. Takes resolved Requirements and produces Specs with enough technical depth that the implementation team can decompose them without coming back to ask clarifying questions. Researches the codebase. Names specific files, modules, services, and components. Generates Features and Enhancements once a Spec is approved. The bridge between "what" and "how."

designer owns UI and UX. Interviews you on intent, audience, scope, and fidelity tier. Produces deployable mockup code -- actual interactive mockups built with the same component libraries the production app uses, not sketches -- that the frontend implementation team ports verbatim into production. The mockup IS the visual contract.

tech-writer owns documentation. Drafts feature pages, release notes, use-case guides, API docs, architecture docs, how-to guides. Adapts tone to the configured audience: community for non-technical readers, code for developers, both when both are configured. Drafts locally, publishes through the docs adapter, never invents metrics.

sprint-planner owns iteration cadence. Allocates Stories and Tasks into sprints based on the configured capacity model. Tracks velocity. Produces sprint reports. Rebalances at iteration boundaries. Surfaces capacity conflicts rather than silently spilling.

dora-analyst owns metrics and quality governance. Tracks STRAP adoption (how much of your delivered value STRAP delivered), STRAP autonomy (how independently it operated), bug resolution time, cycle times across the work-item lifecycle, and an AI Efficiency Ratio comparing original estimates against actual wall-clock cycle times. Evaluates release-readiness gates. Produces evidence; you interpret and decide.

ux-test-engineer owns end-to-end and load testing. Derives test plans from Spec acceptance criteria. Authors and runs E2E suites. Files structured Bug work items for failures with reproduction steps and structured evidence. Runs load tests on a release cadence and hands results to dora-analyst.

agent-devs -- the implementation and verification team

dev-lead is Claude. That's you talking to it right now. Introduced above.

backend-engineer implements server-side code: domain entities, application services, transport handlers, data-access seams, message contracts, integration glue. Holds the line on clean architecture and dependency injection. Authors unit tests alongside the production code but does not run them -- only the dev-lead runs the test suite, at PR preparation, in a single centralized pass.

frontend-engineer implements client-side code across web, desktop, mobile, native, and server-rendered form factors -- Angular / React / Vue on web, WPF / WinForms / MAUI / Avalonia / Borland C++ Builder VCL on desktop, Xamarin / MAUI / SwiftUI on mobile, Electron / Tauri / Flutter Desktop cross-platform, and server-rendered patterns (Python widget libraries like Streamlit / Dash / Gradio and in-house/custom widget frameworks, Phoenix LiveView, Rails Hotwire, Laravel Livewire, Blazor Server, ASP.NET MVC views, classic template engines, vendored JS widget libraries like DHTMLX / ExtJS). The disciplines are the same regardless: state-ownership (containers own derivation, views observe), parent/child contracts (typed inputs and outputs at every boundary), i18n (externalized through the framework's primitive), composition (small reusable elements). When mockups exist, ports them verbatim under the designer's contract.

database-engineer owns the persistence layer: entity definitions, relationships, schema migrations, indexing strategy, query plans. Generates migrations and inspects them. Applies them to the local development database to confirm they run -- and only the local database. Production, UAT, and shared-development are pipeline-only. No exceptions. No --force flag turns it off.

devops-lead owns infrastructure-as-code, cloud fabric, and pipeline definitions. Analyzes and builds. Authors IaC, surfaces state-management and secret-handling defects, builds the CI/CD pipelines themselves. But never runs apply, deploy, or any state-mutating command against an environment with dependents -- the pipeline applies; the devops-lead produces the IaC and the plan output. When the CPO pushes back on that rule, the answer is still no.

security-reviewer is the OWASP-aligned audit gate. Reviews code for authentication explicitness, authorization rigor, tenant isolation when the project is multi-tenant, input validation, injection prevention, secrets handling, error-response hygiene, API surface controls, and mass-assignment defense. Severity is non-negotiable. Critical and High findings block merge.

integration-specialist owns external-system integration. Dynamic endpoints, per-tenant configuration stores, retry policies, bidirectional mapping at trust boundaries, DI rigor across federated sub-services. Dormant when the project has no external surface; activated the moment one appears.

test-strategist authors test strategy at the Feature level, reviews test coverage intent across the team's tests, and triages test-code failures the dev-lead redispatches. Does not run tests -- that is the dev-lead's centralized responsibility.

How they work together

The dev-lead -- you, in this session -- dispatches specialists via Claude Code's primitives. Parallel fan-out (sprint execution waves, PR-feedback rounds, onboarding deep-dives) spawns named teammates so specialists appear as named, color-badged teammates and each replies directly via SendMessage. Serial dispatch (authoring chains where one specialist's output feeds the next, or single-target read-only investigations) uses Task / Agent directly. Each specialist works in its own scope -- a worktree, a branch, a set of files -- so they do not step on each other.

When a specialist finishes, it reports back to the dev-lead. The dev-lead synthesizes: reconciles overlaps, fills gaps, flags issues. Then the dev-lead reports back to the CPO with a coherent unified output the CPO can review in a single pass.

Specialists never talk to the CPO directly. They never spawn other specialists. They report and propose; you ratify; the dev-lead applies.

STRAP Persistence -- Context and Memories

Here is what makes STRAP genuinely different from a one-off agent setup: it gets better over time. Not because the agents themselves become smarter -- they are still markdown files -- but because the things they read become richer.

STRAP carries several kinds of source-controlled state. The dev-lead is the only hand that writes any of it, and for rules and memory the write happens only on your ratification: agents and skills propose, you ratify, the dev-lead applies. Specialists only read. This is the single-writer rule with orchestrator authority, and it is what makes the persistence stack coherent: exactly one writing hand, exactly one deciding human, and everyone else inherits.

Team rules

.claude/strap/rules/agent-ops.md and .claude/strap/rules/agent-devs.md carry the cross-cutting team-level guardrails -- STRAP-wide conventions that ship verbatim to every adopter. Be critical, not agreeable. Never use emojis. No inline comments. Human authority is final. Traceability is mandatory. Centralized test execution -- only the dev-lead runs the test suite. Single writer, orchestrator authority -- agents and skills propose, the orchestrator ratifies, only the dev-lead's hands touch rules and memory. One level of fan-out -- specialists never spawn other specialists.

These are the rules of the road. They do not vary per installation. They define what it means to operate as a STRAP team.

Per-agent rules

.claude/strap/rules/agents/<agent>.md carries each agent's individual guardrails. backend-engineer has rules about clean architecture and dependency injection and async/await invariants. devops-lead has the no-apply-from-agent rule. designer has the mockup-is-a-contract rule. security-reviewer has the severity-is-non-negotiable rule.

These rules ship with starter content. They grow over time -- reactively. When a specialist almost does something wrong ("the backend-engineer almost committed secrets to settings.json"), the near-miss becomes a proposal; once you ratify it -- via /rule-add or the /ratify queue -- the dev-lead applies the guardrail so it cannot happen next time. Rules are guardrails: you add them when something needs preventing, and a rule proposed from the field must cite the observed failure that motivates it.

Per-agent memory

.claude/strap/memory/agents/<agent>.md carries each agent's accumulated tradecraft for THIS project. Not rules -- soft learnings. "This codebase prefers the older mapping pattern for X." "The test runner is flaky after a fresh dependency install; warm it once first." "Use --no-build after a separate build step or you waste eight minutes."

Memory grows as work happens. A specialist finishes a task and proposes what it learned; the proposal queues until you ratify it -- at a sprint boundary via /ratify, or directly via /memory-add -- and the dev-lead applies the entry. New facts are born provisional and harden to confirmed when re-observed; a claim found wrong is invalidated in place, never deleted. Next time that specialist runs, the learning is already there.

This is the part that compounds. 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 project profile

.claude/strap/contexts/project-profile.md is the canonical record of what THIS project IS. Stack. Frameworks. Build commands. Test commands. Conventions. Architecture notes. DevOps integration. Every agent reads it on every invocation.

The project profile is why STRAP never bakes stack-specifics into agent files at install time: the agents stay generic and read the project profile to learn what stack they are working in. The dev-lead curates the project profile as the project evolves. A new tech adoption, a convention change, a known sensitivity surfacing -- all of it lands here.

The dev-lead's own auto-memory

.claude/strap/memory/MEMORY.md plus topic files under .claude/strap/memory/dev-lead/ is the dev-lead's own persistent memory. It works like the auto-memory pattern Claude uses across sessions in personal use, but project-scoped: categorized topic files indexed by a master file, growing over time with project shape, CPO preferences, operating learnings, and reference pointers.

This is the most important persistent file in the whole installation. The dev-lead is the curator of curators. Its own memory has to be disciplined: tight one-line index entries, named topic files, links between them where they share context.

Continuations

.claude/strap/contexts/continuations/<topic>.md carries cross-session topic snapshots. Workstreams that span sessions -- a feature underway, a refactor in progress, a workstream the team has been chipping at for weeks -- get a continuation runbook capturing where things stand: where we left off, what is in flight, open decisions, open work items, quick-resume instructions, critical context, source-of-truth pointers.

The dev-lead writes these via /context-prep when handing off a session, and reads them via /context-fetch when resuming.

Why this matters

Most AI tooling treats every session as fresh. You type your problem in, get a response, and the next session starts from zero. The tool cannot learn -- it has no place to put learnings.

STRAP gives learnings a place to live. Rules accumulate what should never happen again. Memory accumulates what should happen better. The project profile accumulates what this project is. Continuations accumulate where workstreams stand. The dev-lead's own auto-memory accumulates everything else.

All source-controlled. All shared across the team. All curated by the dev-lead.

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

The Onboarding Flow

Installing STRAP into a new project is a deliberate ceremony, not a silent file-drop. Four skills carry the flow.

/strap-in -- the super-pair meets the project

The first conversation. The dev-lead reads the codebase at a shallow scope -- top-level manifests, file-tree shape, recent git activity, CI config, mockup paths, integration markers, IaC files, E2E test markers. The CPO confirms operating budgets for the workflow (per-agent ceiling, session-aggregate ceiling). The dev-lead decides which of the fifteen canonical specialists matter for this codebase, presents the activation set to the CPO for confirmation or override, then dispatches the active ones in parallel as named teammates to deep-dive their respective domains.

Specialists report back. The dev-lead synthesizes findings into the persistence stack -- the project profile, per-agent memory files, per-agent rules additions cited to concrete observations. Reconciled across specialists where they overlap. Refined to the bar: another dev-lead resuming this project on a fresh session, with no memory of this conversation, would understand the project from the persistence stack alone.

After synthesis lands, the dev-lead invokes tech-writer at a closing project-docs production phase to render three human-facing orientation documents -- PROJECT.md, ARCHITECTURE.md, STACK.md -- from the curated persistence stack. These land at the configured Project docs paths (or the fallback .claude/strap/project-docs/) and give a new contributor reading the repo cold the same orientation the agents have. Bar: a new contributor reading them cold would understand what the project is, how the code is structured, and what it is built with.

Throughout, the adopter's production code is immutable. The 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 closing project-docs production phase is the explicit narrow exception -- tech-writer receives Write / Edit scoped to the configured Project docs paths only, never production source. This is the same exception pattern designer follows in /create-mockups. The invariant fully releases only when /connect-code-repo clears its satisfied gate -- the deliberate transition from onboarding mode to operational mode.

Polyrepo support. When the install root contains multiple peer sub-repos at depth-1 (each with its own .git/), /strap-in recognizes the umbrella shape and presents a three-way choice to the CPO: proceed as polyrepo umbrella (single STRAP install at the install root, with a Sub-repos section in project-profile.md capturing one entry per sub-repo and umbrella PROJECT.md / ARCHITECTURE.md / STACK.md describing the system view), exit and install per sub-repo (STRAP exits cleanly with guidance for running /strap-in independently in each sub-repo -- the right call when sub-repos have wildly different stacks, ownership, or release cadences), or continue as single-project at root (an explicit escape hatch when one sub-repo dominates and the rest are auxiliary, with a caution that per-sub-repo signals will be mushed together). The CPO picks; STRAP never silently switches modes. The --polyrepo flag forces polyrepo mode without prompting.

In polyrepo mode, the discovery loop runs once per sub-repo (manifests, file-tree shape, recent git activity), specialist activation unions signals across sub-repos, and the parallel deep-dive uses a mixed-dispatch model -- per-sub-repo briefs for backend-engineer / frontend-engineer / database-engineer when each is relevant to multiple sub-repos (so a Python sub-repo and a C# sub-repo don't get mushed into one backend brief), and umbrella briefs for security-reviewer / test-strategist / integration-specialist / devops-lead whose findings are inherently cross-cutting. Cross-sub-repo runtime dependencies are discovered through a three-stage funnel (manifest parse during shallow scan, specialist code-level confirmation during deep-dive, CPO confirmation at synthesis) and recorded in each sub-repo's Sub-repos entry. The session budget grows additively (base + (N-1) * per_sub_repo_increment) with the math shown to the CPO at the Section 3 budget prompt -- no hidden multipliers. Per-sub-repo project-docs are a later Feature; this initial polyrepo Feature ships umbrella docs only.

/connect-code-repo -- source control wire-up

Required. Wires up where git lives. CPO picks the host (Azure Repos, GitHub, Bitbucket, Local Git, or Other via full from-scratch discovery) via an AskUserQuestion. The dev-lead authenticates, probes the host live, models the connection -- auth method, default branch, branch-protection observations, capability declarations, operation templates for PR creation and branch management -- validates the model with the CPO, then persists the profile at .claude/strap/state/code-connection.yaml. Credentials are recorded as env-var references only; values never enter any tracked file.

Pre-flight checks git installed; the flow refuses to proceed without it. Write probes -- with explicit CPO consent -- create-and-delete a throwaway branch on the real remote to confirm end-to-end credentials, network, and git CLI all work together. The probe evidence is recorded in the connection profile so a future audit can answer "did this connection validate against the live host."

On a polyrepo umbrella, /connect-code-repo also establishes the state repo -- the home for the shared brain. STRAP's onboarding deliberately establishes no top-level git, so the dev-lead detects one of four situations (reuse the umbrella root's own repo, adopt/join a teammate's dedicated <slug>-strap-state remote, provision a new one, or a local-only repo) and, CPO-confirmed, writes the strap-brain-v1 allow-list .gitignore (tracking the brain -- memory, rules, the project profile, the transition ledger, ceremony reports -- and nothing else), a sync marker, and sweeps any buffered facts into the first commit. Facts auto-merge; memory carries merge=union; curated opinions land through one reviewed state PR per session; a session-start hook fast-forwards the brain and /strap-sync is its manual companion. Single-repo installs skip all of this -- the brain rides the code repo everyone already pulls.

/connect-devops-project -- work-tracking wire-up

Optional but typical. Wires up where work items live. Same five-step discovery flow as /connect-code-repo, against Azure DevOps Boards, Jira, GitHub Issues, Local (strap-agile -- see the next section), or any other host via full discovery. The connection profile at .claude/strap/state/devops-connection.yaml records logical-to-host type mappings (the STRAP Requirement is this host's Story; STRAP's Feature is this host's Epic), field mappings, state transitions, capability declarations, and operation templates. Capability gaps are explicitly recorded so subsequent workflows degrade gracefully when the host doesn't support an operation.

Since v2.14 the same wire-up also decides where new items sit and what the host demands to accept them. It probes the host's backlog levels and offers three hierarchy models -- a nested spine (each item's parent is the item it came from, recommended only when the process has one backlog level per STRAP stage), Epic buckets (container Epics per type, the default elsewhere), or flat -- plus container Epics for quick work, Bugs and human-authored items, which it recommends creating. It also reads the process rules that make fields required on create or activation, so /file-bugs and the execution skills pass them in the same write instead of failing on the host's rule, and it lists your iterations with their dates, naming any undated one as a to-do before sprint planning. Contract: .claude/strap/contexts/work-item-hierarchy.md.

/strap-refresh -- the re-run

The companion to /strap-in. When the codebase shape changes -- a new framework adopted, a major directory introduced, CI moved to a new host, a fresh team convention surfaced -- /strap-refresh reads the existing persistence stack as priors, runs a shallow scan against the current state, detects diffs between priors and current, and surfaces them for CPO approval BEFORE dispatching any specialist or updating any curated content. Specialists run only against changed domains; memory files for unchanged domains stay byte-identical. Specialists newly activated by new signals get a fresh deep-dive against their previously-unread domain.

After synthesis, tech-writer applies surgical updates to the project-orientation docs (PROJECT.md, ARCHITECTURE.md, STACK.md) for the sections flagged as drifted by the diff list. Sections that did not drift stay byte-identical -- CPO edits, narrative additions, and prior-refresh curation are preserved. Whole-file rewrites at refresh time are a defect, not a feature.

For polyrepo installs, /strap-refresh detects mode from the existing Sub-repos section in project-profile.md -- no re-prompting, no depth-1 re-detection. The priors are authoritative; refresh just verifies they still hold. Structural diffs are surfaced explicitly: a sub-repo declared in Sub-repos but missing on disk (removed since the last refresh), a new depth-1 .git/ subdirectory not yet declared (added since the last refresh), or per-sub-repo stack / convention / runtime-dependency drift. The CPO sees these structural diffs first in the refresh plan and can defer, ignore, or accept the default action per case before any updates land. Sub-repos entries get surgically updated -- the affected entry's affected fields change, every other entry and unaffected field stays byte-identical.

This matters: STRAP's curated persistence stack is a CPO-curated artifact, not an automated derivation. Updates require approval, not just detection. The single-writer rule applies to refresh runs same as initial onboarding: proposals surface, you ratify, the dev-lead applies.

Joining an already-onboarded umbrella

When a teammate has already onboarded the umbrella and established the state repo, a joining developer does not re-run onboarding -- the curated brain (project profile, per-agent memory and rules, both connection profiles) arrives with the clone. The join is four steps, in this order:

1. Clone the umbrella repo, plus the sub-repos listed in the inherited project-profile.md Sub-repos section (each is its own git repo).
2. Run the installer at the umbrella root. It detects the tracked sync marker and runs in joiner mode: the package (skills, agents, tools) arrives, and no existing file under rules/, memory/ or contexts/ is overwritten -- the team's brain in your clone is kept, and the installer reports how many package seeds it skipped. It also registers the per-developer SessionStart pull hook. The confirmation reads from your terminal even when piped from curl, or pass --no-prompt (bash -s -- --no-prompt) to skip it. git status should be clean afterwards apart from untracked package files. (Installers before v2.13 overwrote the brain with seeds here; step 3 undid that.)
3. /strap-sync --init -- adopts the remote brain, and remote wins over the fresh-install seeds: the team's curation is restored while the package stays untouched. Not optional, and always before the next step.
4. /connect-code-repo -- with your own host auth ready first (the env vars named in the inherited profiles, or az login plus az devops configure --defaults on Azure DevOps). For a joiner this does not re-model the connection: it validates your permissions against the live host and makes sure the SessionStart pull hook is registered (settings.json is never synced; the installer and --init register the same entry, and all three dedupe on it).

No /strap-in and no /connect-devops-project -- the connection models are inherited with the brain; only credentials are per-machine.

--init versus plain /strap-sync. --init is the adopt / re-baseline mode: joining a shared brain, or resetting a diverged local against the remote (remote wins; any divergent local curation is preserved on a recovery branch first). Plain /strap-sync is the everyday publish/reconcile cycle -- commit what you curated, pull what teammates published, publish through the session's state PR. Joining? --init. Working? Plain.

Order matters. Run --init before /connect-code-repo. The connect skill's reuse path commits and pushes tracked brain, and a seed-clobbered tree pushed before --init would overwrite the team's curation on the remote. The skill guards against this, but the discipline stands.

Single-repo installs need none of this: the whole .claude/ tree rides the code repo, so a joining developer clones, sets their auth, and works.

Work-Tracking as Code (strap-agile)

One of /connect-devops-project's host options is Local (strap-agile). This is not a fallback or evaluation-only mode -- it is a deliberate paradigm worth understanding.

In strap-agile mode, work items are markdown files in your repo's git history:

.claude/strap/work/
├── requirement/
│   ├── 0001-customer-export.md
│   └── 0002-multi-tenant-isolation.md
├── spec/
│   └── 0001-customer-export.md
├── feature/
│   ├── 0001-csv-export.md
│   └── 0002-pdf-export.md
├── story/
│   ├── 0001-csv-export-handler.md
│   └── 0002-csv-export-formatter.md
├── task/
│   └── 0001-author-csv-handler.md
└── bug/
    └── 0001-sales-routing-typo.md

Each file carries YAML frontmatter (id, type, state, parent links, assignee, timestamps); the body is the work-item content (problem statement, acceptance criteria, scope notes).

What this gets you:

• PR-reviewable work items. A Story is a .md file. Changes go through PR review -- same gates as code. The acceptance criteria of a Story can be debated and refined in code review before someone implements against it.
• Diffable history. git log .claude/strap/work/ is the work-item changelog. WHEN was a Bug filed? WHO filed it? WHY (commit message)? Every answer is in git history. No separate audit surface to reconcile against.
• Branch-aware. A feature branch can carry provisional work items that only exist on that branch until merged. You can experiment with how to structure a Feature without committing to it on main.
• Single source of truth. Code and work-items move together in the same commit. The "ticket says X but code does Y" mismatch becomes impossible because both are tracked in the same atomic change.
• Audit-friendly. Compliance / DORA-style metrics become git-blame-able. The work-item history IS the git history.
• Portable. No external service to migrate to or from. Work items travel with the repo.

This is the same paradigm as IaC, applied to work tracking: work-item-tracking-as-code.

It is not positioned as a wholesale replacement for Azure DevOps Boards or Jira on large multi-team programs -- those tools earn their cost when capacity planning across many sprints, cross-team dependency graphs, executive reporting, and integrations with Slack / Teams / Salesforce are load-bearing. strap-agile is positioned as the right choice for small teams, solo developers, and projects where the agility and PR-review-everything posture of work-as-code outweighs the breadth of a large DevOps platform.

A future skill will render strap-agile work items as an exportable HTML view -- kanban board grouped by state plus backlog grouped by type -- so the work-tracking surface stays useful for at-a-glance project state without forcing CPOs back into git grep. For now: the markdown is the surface, and git log is the query language.

What comes after onboarding

Once the persistence stack is curated and the connections are wired, day-to-day operation moves to the production pipeline: the Welcome chapter's Daily Orchestration Workflows section is the cheatsheet for which motion to reach for, and its Production Workflows catalog documents every skill. The DORA Tuning chapter covers the governance cadence that keeps the delivery data honest.

A Simple STRAP Walkthrough

This is the read-along narrative for a new CPO landing STRAP on their first project. Follow along on your own codebase; the steps assume nothing about your stack. By the end, you'll have onboarded STRAP, connected it to a DevOps host, filed a Requirement, driven it through to a Pull Request, and rendered your first DORA report.

The walkthrough uses a deliberately tiny example: adding a one-line comment block to a single file. Don't worry that the work is trivial -- the point is to feel the full pipeline end-to-end with the smallest possible payload.

Time budget: ~45-60 minutes for the first read-along. Most of it is reading the dev-lead's structured surfaces and confirming the choices; STRAP does the synthesis work.

Before you start

You need:

• A real project on your machine. Any stack works -- TypeScript, Python, Go, C#, Rust, anything STRAP doesn't already know about. STRAP probes the stack live.
• A DevOps host wired up: Azure DevOps, GitHub, Jira+Bitbucket, or strap-agile (Local) if you don't have a remote tracker. Have your auth credentials available (env vars set; tokens in scope).
• A source-control host: Azure Repos, GitHub, Bitbucket, or Local Git.
• Claude Code installed and authenticated. Run claude in the project root.

Optional but recommended: a fresh feature branch in your repo, so this walkthrough's PR doesn't land on main accidentally.

Step 1: /strap-in

Your first command. The dev-lead reads your codebase, infers your stack, dispatches relevant specialists in parallel for read-only discovery, and curates the persistence stack (project profile, per-agent memory, per-agent rules) for your project specifically.

/strap-in

What you'll see:

1. Discovery phase. The dev-lead surveys your repo -- file extensions, build configs, package manifests, existing CI yaml. It detects single-repo vs polyrepo. It probes for sub-repos. It infers active domains (frontend, backend, database, integration, devops, etc.).
2. Approval gate. The dev-lead surfaces what it inferred and asks you to confirm or correct. This is the first place to step in if the inference missed something -- maybe your TypeScript project has a Python script in tools/ that the inference flagged as a second active domain when it shouldn't be.
3. Specialist dispatch. Once you confirm, the dev-lead dispatches active-domain specialists in parallel (backend-engineer, frontend-engineer, database-engineer, etc.) for deep read-only research. Each specialist reads its assigned domain and reports back; the dev-lead synthesizes.
4. Persistence-stack curation. The dev-lead writes:
   • .claude/strap/contexts/project-profile.md -- the curated record of THIS project (stack, conventions, commands, architecture)
   • .claude/strap/memory/agents/<name>.md per active specialist -- seed memory pre-populated with your project's patterns
   • .claude/strap/rules/agents/<name>.md per active specialist -- guardrails specific to your stack
5. Project-docs phase. The tech-writer writes PROJECT.md, ARCHITECTURE.md, STACK.md to your project's docs path (or the configured fallback). These are human-readable narratives derived from the same discovery.

When /strap-in finishes, your project has STRAP-aware persistence. Re-running /strap-in is safe and idempotent (re-discovery mode); use /strap-refresh for incremental updates.

Step 2: /connect-devops-project

Wire up work-item tracking. The dev-lead asks which host (Azure DevOps / GitHub Issues / Jira / Local strap-agile / Other), probes the host's capabilities, models the logical-to-host mapping for the 7 STRAP work-item types (Requirement / Spec / Feature / Story / Task / Bug / Enhancement), and persists a connection profile.

/connect-devops-project

Key steps:

1. Host pick. Name the host. Each option's AskUserQuestion description tells you what auth is needed.
2. Authenticate. The dev-lead probes the host with a no-op call (e.g., GET /projects?$top=1 for ADO). Failed auth surfaces inline with a remediation hint.
3. Probe the host's work-item types + state machines. Instead of assuming defaults, STRAP probes the host directly. It surfaces what it found (e.g., "Found work-item types: Epic, Feature, User Story, Task, Bug, Issue") + proposes a STRAP-logical mapping. You either Accept, Customize, or Reject.
4. State-machine collapse confirmation. Per work-item type, STRAP surfaces the probed states + its proposed STRAP-logical collapse. Most adopters accept; custom-template adopters use the Customize flow.
5. Field probe + cross-version rename detection. STRAP validates that every field declared in the connection profile actually exists on the host's process template. It also detects renames (e.g., Custom.PullRequestUrl -> Custom.PRUrl) and offers to update the mapping.
6. Validation + persist. STRAP surfaces the assembled profile, you confirm, profile lands at .claude/strap/state/devops-connection.yaml.

For polyrepo umbrellas, Step 6 walks each non-primary sub-repo for its own work-tracking config (Same as primary / Different project / etc.).

Step 3: /connect-code-repo

Wire up source control. Similar shape to /connect-devops-project -- pick the host, authenticate, probe, model, validate, persist.

/connect-code-repo

Key auth recipes:

• Azure Repos: bearer token via az account get-access-token --resource 499b84ac-1321-427f-aa17-267ca6975798
• GitHub: fine-grained PAT preferred (Contents/Pull requests/Actions scopes) OR gh auth login
• Bitbucket Cloud: app password from your Atlassian account
• Local Git: no remote auth; branch_push / branch_delete_remote are unsupported

The connection profile lands at .claude/strap/state/code-connection.yaml. The "satisfied" gate -- the deliberate transition from onboarding mode to operational mode -- releases when this skill clears.

Step 4: /new-requirement

Time to create work. A Requirement is the entry point for any new piece of intent. The dev-lead dispatches req-lead to author the initial Requirement body + probe questions, persists with the STRAP lifecycle metadata, and drives the first refinement pass conversationally.

For our toy example, run:

/new-requirement

When STRAP asks "What is the requirement?", paste:

Add a one-line comment block at the top of <pick any file in your repo> documenting what the file is for.

STRAP creates the Requirement work item in your DevOps host, tags it with strap:requirement, marks it Authored By: AI (or your account, depending on the connection profile), and surfaces the initial body + a list of clarifying questions.

Step 5: /refine-requirement <id>

Drive the Requirement toward Resolved. The dev-lead probes for ambiguity and walks you through clarifying questions until the requirement is implementable.

/refine-requirement <the-id-you-got-from-step-4>

For the toy example, the refinement is trivial -- the dev-lead might ask:

• "What file specifically?" → answer with the path
• "What style of comment block?" → JSDoc / docstring / structured / whatever your language uses
• "Anything else?" → no

After a round or two, the dev-lead surfaces a Resolved-ready summary + AskUserQuestion for the approval gate. You confirm; the Requirement transitions to Resolved.

Step 6: /create-spec <requirement-id>

A Resolved Requirement isn't yet implementable. The Spec phase translates the Requirement into a detailed technical specification: which Constituent Parts (frontend / backend / database / etc.) get touched, what changes per CP, how they interact, what acceptance criteria look like.

/create-spec <requirement-id>

For our toy example, the Spec is small -- one CP (the file you named), one change (add a comment block at top), zero cross-CP coordination. Larger requirements decompose into multi-CP Specs.

The dev-lead dispatches spec-lead to author the initial Spec outline, links it back to the source Requirement, and surfaces the body for your review.

Step 7: /refine-spec <id>

Similar to /refine-requirement but at Spec depth. Walks section-by-section: research the codebase, surface gaps, populate Constituent Parts with technical depth, drive to Resolved.

/refine-spec <spec-id>

For the toy, this is also fast. The dev-lead might confirm:

• The file's current state (no comment block exists OR an existing one needs replacing).
• The comment block contents (Description / Author / Last-modified / etc.).
• Acceptance criteria (file builds with the new block; existing tests still pass).

Resolved Spec.

Step 8: /generate-features <spec-id>

A Spec produces Features. For our toy, one Feature is enough. Larger Specs decompose into multiple Features that can be parallelized across sprints.

/generate-features <spec-id>

The dev-lead dispatches spec-lead to author Feature briefs, applies lifecycle metadata + tags, persists the Features in your work-tracker.

Step 9: /decompose-feature <feature-id>

A Feature decomposes into Stories + Tasks. For our toy, one Story + one Task is plenty.

/decompose-feature <feature-id>

The dev-lead reads the linked Spec, activates any required domains (CPO-gated structural precondition), dispatches active-domain specialists in parallel for read-only planning, reconciles their output, and persists work items.

When /decompose-feature finishes, the Feature has a child Story has a child Task. The Task carries OriginalEstimate (e.g., 0.5 hours for a one-line comment block).

Step 10: /execute-sprint <feature-id>

Now execute. The dev-lead creates a feature branch, sequences Tasks by dependency, dispatches active-domain specialists in worktrees (one specialist per Task, isolated from each other), reviews each task branch, runs the integration audit, sets completion metadata at resolution, and prepares the PR.

/execute-sprint <feature-id>

For the toy: one Task → one specialist → one tiny code change → one git commit → one PR. You'll see the dev-lead orchestrate this conversationally; specialists work in isolated worktrees so you can observe progress without context-switching pain.

When /execute-sprint finishes, you have:

• A feature branch with the implementation committed
• The Task marked Closed (auto-run from Resolved) with CompletedWork set
• A PR opened against the integration branch

Step 11: PR review + merge

This is your moment to review. STRAP doesn't merge for you -- the CPO is the deliberate gatekeeper. Walk the PR diff in your DevOps host, confirm the change matches the Spec, request changes if needed (via /refine-pr <pr-id> from STRAP), and merge.

Step 12: /dora-collect + /dora-report

Now see how it looked.

/dora-collect

The dev-lead queries work items, the adoption denominator, STRAP's own transition ledger, and pull requests (split by integration target vs intermediate per your code-connection), then writes a structured JSON snapshot at .claude/strap/state/dora-snapshots/.

Then:

/dora-report

The dev-lead builds a PAYLOAD from the snapshot, assembles head + render + tail via the html-render pipeline, runs the verify-then-write quality gates, and writes a self-contained HTML report. Open it in a browser.

For our toy walkthrough you'll see a single-PR sprint -- not much to compare against, and adoption and autonomy will read thin or refuse outright, which is the report behaving correctly rather than failing. After a few real sprints it becomes rich: the adoption and autonomy trajectory sprint over sprint, agent attribution from the ledger, cycle-time trends, and the methodology section explaining how each metric was computed.

See ./dora-tuning.md for getting the most out of the report over time.

What you've done

In ~45 minutes you went from claude prompt to a STRAP-onboarded project with a real work item driven end-to-end and a DORA report rendered. The pipeline did not invent files in your codebase, did not modify production code during onboarding, and did not act without your approval at any of the gates.

This is the operational shape of STRAP. The toy example is trivial; real Requirements get richer treatment at each step. The same skills handle:

• A bug a customer reported: /file-bugs → /fix-bugs <bug-id> → PR.
• A 12-Task Feature that touches frontend, backend, and database: /decompose-feature produces a parallel-safe Task graph; /execute-sprint runs specialists concurrently in isolated worktrees.
• A polyrepo umbrella with three sub-repos and different deployment targets: STRAP's polyrepo model gives per-sub-repo connection-profile overrides + per-layer DORA metrics.
• A Spec you are confident in, taken straight to PRs: /execute-sprint-full-auto generates Features, decomposes, allocates, and executes across all Features in parallel, opening one draft PR per Feature -- the Resolved Spec is the contract.
• A team of developers on a polyrepo umbrella sharing one brain: a state repo syncs memory, rules, the transition ledger, and ceremony reports across everyone -- facts auto-merge, curated opinions land through one reviewed state PR per session, and a session-start hook (umbrella-sync-pull.sh) fast-forwards the brain; /strap-sync is its manual companion.

Next steps

• Add more Requirements + drive a real sprint. Use the toy walkthrough's flow on actual work; the muscle memory builds quickly.
• Run /dora-reconcile --auto-fix weekly. Keeps the data layer clean (state transitions, AI tags, CompletedWork).
• Run /close-ceremony per sprint. The deliberate value-acceptance ritual for Resolved work items.
• Read ./dora-tuning.md for getting the most from the DORA report over time.
• Read ./architecture.md for the contributor-depth mental model of why STRAP is built this way.
• Read ./customization-guide.md if you want to extend STRAP with a project-specific specialist (e.g., a stack-tier specialist STRAP doesn't ship by default).

A note on the future

/strap-tour (interactive walkthrough that uses real STRAP skills against a sandboxed example) is on the roadmap. This document is the read-along surrogate; the interactive variant will sit alongside it for adopters who prefer a guided experience over a read-along.

References

• ./strap-in.md -- the operational walk-through of installing STRAP
• ./architecture.md -- contributor-depth architecture
• ./customization-guide.md -- extending STRAP with custom specialists
• ./upgrade-guide.md -- moving an installed STRAP forward across releases
• ./dora-tuning.md -- getting the most from DORA reports

STRAP Architecture

System architecture for STRAP contributors and the curious adopter. STRAP is a portable agentic SDLC pipeline that ships as a .claude/ tree, drops into any project, and brings a coordinated team of fifteen AI specialists online under one human's authority. This document is the contributor-facing complement to strap-in.md -- where that narrative explains what STRAP feels like to use, this one explains why it is built the way it is.

The audience is a contributor extending STRAP, or an adopter who wants a deeper mental model than the customization guide provides. For the operational walk-through of installing STRAP and curating it post-install, see strap-in.md.

Design principles

Four principles run through every architectural choice. They are stable across releases; they explain most decisions.

1. Single writer, orchestrator authority. Only the dev-lead's hands touch rules and memory files, and only on the CPO's ratification: agents and skills propose, the orchestrator ratifies, the dev-lead applies. Every write is an explicit, atomic, diff-reviewable act through the brain curation skills; no silent writes. This is what makes the persistence stack coherent over time -- there is exactly one writing hand, one human authority, and everyone else inherits.
2. Canonical roster, project-tuned context. Fifteen agents ship with STRAP; the same fifteen ship to every adopter; the roster does not change per install. What changes per install is the persistence stack -- per-agent rules, per-agent memory, project-profile -- that the dev-lead curates over the project's lifetime. Agents stay simple. Intelligence accumulates in the persistence stack.
3. Connection-discovery model. STRAP does not ship a fixed adapter per host. It probes the host live during a per-project /connect-* flow, models the host's actual capabilities against STRAP's logical operations, validates with the CPO, and persists a per-project connection profile that the pipeline reads at runtime. The skill catalog stays portable; the per-host details live in the profile, not in the skill body.
4. Code immutability during onboarding. Section 6 specialists dispatched during /strap-in or /strap-refresh run read-only. The adopter's production code is not modified during persistence-stack curation. Three narrow exceptions exist for closing-phase specialists that write local-only artifacts: tech-writer writes the project-orientation docs (PROJECT.md, ARCHITECTURE.md, STACK.md) to the configured Project docs paths at the closing phase of both /strap-in and /strap-refresh; designer writes mockup files to the configured Mockup paths in /create-mockups; ux-test-engineer writes test plans + scaffolded test files to the configured test paths in /create-test-plan. All three exceptions are scoped narrowly -- writes target adopter-owned local paths, never production source. The full invariant releases when /connect-code-repo clears its satisfied gate -- the deliberate transition from onboarding mode to operational mode.

Package layout

STRAP is distributed as a directory of markdown artifacts the Claude Code runtime loads. No binaries, no compiled stages, no server. Every artifact is text and the agent runtime is the only execution surface.

STRAP/                     (source repo -- the root files below never ship; the package is .claude/ alone)
  README.md                top-level orientation
  INSTALL.md               install flow STRAP exposes to adopters
  CHANGELOG.md             release history
  CLAUDE.md                contributor-session grounding (adopter sessions ground via the dev-lead role contract)
  .claude/
    agents/
      agent-ops/           7 ops-team role contracts
      agent-devs/          8 dev-team role contracts (including dev-lead)
    skills/                slash-command skills covering the full SDLC pipeline + onboarding
    strap/
      rules/
        agent-ops.md       team-wide rules
        agent-devs.md      team-wide rules
        agents/            per-agent guardrails (15 files)
      memory/
        agents/            per-agent accumulated tradecraft (15 seed files)
      templates/
        work-items/        Mustache-templated work-item description bodies (7 types incl. Enhancement)
        connection-templates/  per-host accelerator templates (optional)
        project-profile.scaffold.md  scaffold the installer writes; /strap-in populates + strips the sentinel
        project-docs/      PROJECT.md / ARCHITECTURE.md / STACK.md Mustache templates for tech-writer
      contexts/
        onboarding-design.md   onboarding-flow design source-of-truth
        budget-discipline.md   cross-cutting budget pattern (incl. polyrepo aggregation)
        umbrella-sync.md       polyrepo shared-brain state-sync contract
        transition-ledger.md   append-only state-transition record for DORA timing
        ...                    other contributor-facing design docs
      docs/                this directory; contributor + CPO narratives
      hooks/
        umbrella-sync-pull.sh  SessionStart pull hook for the polyrepo shared brain (mode 755)
      tools/
        html-render/       markdown-to-HTML pipeline (project-docs HTML companion + Welcome HTML)
  infra/
    install/               installer + smoke runbook
    pipeline/              CI/CD scripts

The tarball is a deny-list archive of .claude/. It excludes STRAP-source and per-developer state that should never propagate to adopter installs: .strap-version.json (the installer writes a fresh per-install copy), project-profile.md (the installer copies a separate scaffold from templates/project-profile.scaffold.md at first install), contexts/continuations/ (STRAP-source session bookkeeping), the contributor-only skills/session-start + skills/session-end, the CI-only skills/dora-report/fixtures/ (golden artifacts built from real adopter data), and the local harness settings.json + settings.local.json. Everything else under .claude/ ships -- including memory/MEMORY.md and memory/dev-lead/, which carry STRAP-source-curated universal operating learnings that apply to every adopter dev-lead. /strap-upgrade's seeded-then-curated category preserves adopter customizations on upgrade while still applying new package-only adds. The html-render pipeline at .claude/strap/tools/html-render/ IS bundled (it is adopter-runtime tooling invoked at every /strap-in and /strap-refresh closing phase); a package.json declares marked as the only runtime dep, resolved at first invocation via npm install --no-save.

The canonical 15-agent roster

The default roster is fifteen agents. The same fifteen ship to every adopter, every install; the package does not rename or regenerate them. Adopters can extend the roster with their own agents (cross-cutting reviewers, project-specific governance, stack-tier specialists STRAP doesn't ship by default) by dropping a role contract under .claude/agents/agent-{ops,devs}/, seeding the persistence-stack files for it, and asking the dev-lead to wire the new agent into project-profile.md's Domains Specialists fields. The integration is curation-only -- no package code changes -- and /strap-upgrade naturally protects adopter additions. See customization-guide.md for the three-step ceremony.

The two-team split mirrors the SDLC handoff: agent-ops produces; agent-devs consumes; the Spec is the contract between them. The split is reflected in two team-wide rules files (.claude/strap/rules/agent-ops.md, .claude/strap/rules/agent-devs.md) that ship verbatim and apply STRAP-wide.

The super-pair invariant. The CPO is the human typing the prompts. The dev-lead is the top-level Claude session -- never a subagent. They form the super-pair: every STRAP session is operated through this one relationship, and every skill runs under it.

The persistence stack

Four kinds of source-controlled state inform every agent. For rules and memory the model is propose/ratify/apply: agents and skills propose, the orchestrator ratifies, the dev-lead is the only applying hand. Agents only read.

Every specialist agent loads the team rules, its own rules, its own memory, and the project profile on every invocation. Specialists report findings and propose learnings from their dispatches; proposals queue at .claude/strap/state/brain-proposals/ until the CPO ratifies them (via /ratify or a direct write skill), and the dev-lead applies each ratified change.

Rules and memory entries follow the brain-format contract (../contexts/brain-format.md): every entry declares its claim type (fact / policy / anti-pattern), facts cite the producer they describe, and a new fact is born provisional until a second independent observation confirms it. A claim found wrong is invalidated in place, never deleted -- refuted entries flip to anti-guidance carrying their counter-evidence, because deleting a wrong learning restores the conditions that produced it. The CPO's curation surface is seven skills: /memory-{show,add,refine}, /rule-{show,add,refine}, and /ratify.

The active-domain model in project-profile.md is what makes the canonical roster project-tuned. The Domains section enumerates which logical concerns (client-ui, api, core, data, infrastructure, integrations, etc.) are active on this project, names the specialists each domain dispatches to, and carries the per-domain Source-of-truth paths + Conventions the specialists read. A specialist isn't "deleted" from the roster when its domain is dormant -- it's just not dispatched. The same specialist becomes active the moment its domain shows up in the project, with a deep-dive seeded by the dev-lead during /strap-refresh.

Polyrepo support

When the install root contains multiple peer sub-repos at depth-1 (each with its own .git/), /strap-in recognizes the umbrella shape. The pipeline supports two structural models from a single install:

• Single-project: the canonical case. /strap-in runs against one repo; one Domains section drives specialist activation; one project-profile, one persistence stack.
• Polyrepo umbrella: STRAP installs once at the umbrella root (<root>/.claude/); a new Sub-repos H2 section in project-profile.md carries one H3 entry per detected sub-repo with 7 fields (Path, Purpose, Stack, Conventions, Source-of-truth, Runtime dependencies, Activated). Sub-repos can coexist with Domains -- a Domain can declare paths spanning multiple sub-repos. Pre-existing .claude/ directories inside sub-repos are bystanders at non-overlapping paths; never touched by the umbrella install.

Detection. /strap-in Section 2 runs a depth-1 scan (find -maxdepth 2 -mindepth 2 -type d -name .git). When N >= 2 sub-repos are detected (each with their own .git/ directory at depth-1), the dev-lead surfaces a three-way CPO choice via AskUserQuestion: proceed as polyrepo umbrella, exit cleanly with guidance to install per sub-repo separately, or continue as single-project at root with an explicit caution. The detection does NOT pre-filter on whether the install root has its own .git/ or its own source manifests (.sln, package.json, pyproject.toml, etc.) -- ambiguous cases (umbrella workspace manifests; root projects vendoring sub-repos as sibling clones) could go either way, and the CPO is the authority on the interpretation. The --polyrepo flag forces umbrella mode without prompting. STRAP never silently switches modes.

Polyrepo discovery flow (when umbrella mode is selected). Section 4 runs the shallow scan once per detected sub-repo, narrating per-sub-repo progress. A manifest cross-reference pass detects cross-sub-repo dependency hints (e.g., package.json dependencies referencing a sibling sub-repo by name, requirements.txt editable installs, *.csproj ProjectReferences, go.mod replace directives) -- the first stage of a three-stage runtime-dependency funnel.

Mixed specialist dispatch in Section 6. Per-sub-repo briefs (spawned as named teammates in one batch) for backend-engineer, frontend-engineer, database-engineer when each is relevant to multiple sub-repos -- their findings are inherently sub-repo-scoped (different language/framework per sub-repo would mush together in a single brief). Umbrella briefs for security-reviewer, test-strategist, integration-specialist, devops-lead -- their findings are inherently cross-cutting and only make sense viewed across the system.

Three-stage runtime-dep funnel. Manifest-cross-reference (Section 4) seeds the dependency edges; per-sub-repo specialist code-level confirm (Section 6) refines with observed imports + cross-service contracts; CPO confirmation at synthesis (Section 8) closes the gate via AskUserQuestion before the Runtime dependencies field lands in each Sub-repos entry. Stage 3 also surfaces negative findings explicitly ("no cross-sub-repo runtime deps detected; confirm or edit") so curated absence is recorded.

Budget aggregation. The session-aggregate budget grows additively in polyrepo mode: projected_aggregate = session_aggregate + (N - 1) * per_sub_repo_increment where per_sub_repo_increment comes from budget-discipline.md (300K for /strap-in, 200K for /strap-refresh). The math is shown to the CPO at the Section 3 budget prompt -- no hidden multipliers.

/strap-refresh polyrepo path. Mode is detected from the existing populated Sub-repos section in project-profile.md; no re-prompting. Structural diffs (sub-repo added on disk but not declared; sub-repo declared but missing on disk; per-sub-repo stack drift) surface explicitly at Section 6's diff-summary gate with defer / ignore / accept options.

Per-sub-repo project-docs rendering is deliberately out of scope: the umbrella PROJECT.md / ARCHITECTURE.md / STACK.md capture the system view, with per-sub-repo summaries plus a per-sub-repo Stack table. A future Feature adds per-sub-repo project-docs alongside the umbrella set.

Umbrella state sync -- the shared brain

STRAP's persistence stack is source-controlled state. In a single-repo install it rides the one code repository everyone already clones, pulls, and pushes -- sync is free and this mechanism is inert. A polyrepo umbrella breaks that assumption: the pipeline installs at <umbrella>/.claude/ while code lives in peer sub-repos beneath it, and onboarding deliberately establishes no top-level git. With no umbrella repo, every state producer that commits "to the install repo" would strand the brain per-developer -- one developer's memory curation, ledger shards, and ceremony reports never reach another, and cross-developer metrics have no shared substrate. The umbrella state repo closes that gap: a dedicated home for the brain, decoupled from the sub-repos' code branches, established at /connect-code-repo the moment the CPO commits to operating the pipeline. The canonical contract is ../contexts/umbrella-sync.md; the sync skill and the pull hook reference it and never redefine it.

Facts vs opinions -- the tracked set is an allow-list. Because contexts/ and state/ each mix brain with shipped-package and regenerable content, the state repo tracks the brain via an allow-list (strap-brain-v1, written to <umbrella-root>/.gitignore), not a directory split. Four sync classes:

• Facts (state/transition-ledger/, state/close-ceremonies/) -- machine-generated, append-only, uniquely named per session, so they union with no conflict and auto-merge by path policy. A same-filename collision would be a producer bug to surface, never a merge to resolve.
• Opinions (all memory/, all rules/, contexts/project-profile.md, contexts/continuations/) -- curated human judgment; they flow through a reviewed state PR, never an auto-merge.
• Config (the marker, the *-connection.yaml profiles, usage.yaml -- budget ceilings only) -- shared and never carrying secrets (profiles hold references, never credentials); a conflict is a genuine divergence, resolved deliberately.
• Regenerable / package (everything else -- shipped design/contract docs, docs/, templates/, tools/, snapshots, reconcile logs, rendered HTML, upgrade-cache/) -- never tracked; the package rides its own install and regenerable output rebuilds from inputs.

One governance exception rides the allow-list: the host opinion-review file (CODEOWNERS on GitHub/Bitbucket) is tracked so the review gate itself is version-controlled and reaches every clone. The state repo centralizes the most sensitive brain -- both connection profiles, all memory, the project profile -- so its access control must be at least as strict as the most sensitive sub-repo it aggregates.

The commit gate is the enclosing repo, not the marker. A producer commits when the install working tree is inside a git repo and buffers on disk when it is not -- the same gate the transition ledger uses. Single-repo rides the code branch, with one guard: on the remote default branch (planning phases run before any feature branch exists) the ledger emit helper skips the commit loudly and the shard stays disk-durable until the next emit from a work branch sweeps it in -- a direct default-branch commit would bypass the adopter's PR governance. Pre-connect polyrepo buffers on disk and sweeps the buffered facts into the first commit at establishment (losing nothing); post-connect polyrepo commits to the umbrella state repo, which is exempt from the default-branch guard (local main accumulation is its designed offline-first model, published via per-session state PRs). The marker (state/umbrella-sync.yaml) does not decide whether a producer commits -- it signals "this is a synced umbrella" and where to push.

Memory unions; the profile and config do not. Memory is append-structured -- developers mostly add entries -- and git's default 3-way merge conflicts on concurrent end-of-file additions. STRAP ships memory/.gitattributes with *.md merge=union so both developers' additions land with no conflict; /strap-sync compacts the rare concurrent same-line union in a later additive pass. project-profile.md and the config YAMLs deliberately do not union -- a conflict there is a real divergence a human resolves.

Ongoing sync -- the hook and /strap-sync. A SessionStart pull hook (hooks/umbrella-sync-pull.sh, mode 755) fast-forwards the shared brain at session start so a developer resumes current: self-gating (inert unless the marker is present with a remote), fast-forward-only (it never merges or rebases -- that is /strap-sync's job, with a human), and never blocking (every path exits 0, silent when current). /strap-sync is the manual publish/reconcile cycle owned by the dev-lead -- pure git plus the source-control auth already established, with no work-tracking adapter and no specialist dispatch: commit brain edits, pull --rebase (facts and memory union automatically), reconcile curated conflicts with the CPO, compact union artifacts, run a no-secrets scan, and publish.

State-PR governance. Brain deltas accumulate on the umbrella main locally and are never pushed straight to the remote. Publishing -- whether a pipeline skill opens a code PR or /strap-sync runs -- pushes the accumulated brain-delta commits to a stable per-session branch (strap-state/<handle>-<YYYYMMDD>) and opens one state PR into the state repo's main, so repeated publishes update the same PR. A fact-only PR auto-merges; any PR touching an opinion or config path requires review. /connect-code-repo configures the host's gate at establishment -- a tracked CODEOWNERS on GitHub/Bitbucket, or a per-path required-reviewer branch policy on Azure Repos -- as a CPO-confirmed, default-yes action. Every publish runs the no-secrets scan before it pushes (the manual cycle and every pipeline auto-publish alike); a hit refuses the push. Until protection lands, the state PR fast-merges everything and the pull hook ff-merges that unreviewed brain into every developer's agent context -- so establishment states that default-open window to the CPO. This convention is defined once in the contract and referenced -- never copied -- by the five PR-opening skills and /strap-sync.

The connection-discovery model

STRAP runs against host systems (work tracking + source control) that vary per adopter. Hardcoding az boards or gh issue into skills would foreclose the portability that motivates STRAP. Instead of shipping a fixed adapter per host, STRAP probes each host live and persists a per-project profile.

Two /connect-* skills drive this. Each follows the same five-step flow:

1. CPO names the host via AskUserQuestion (Azure DevOps / Jira / GitHub Issues / Local / Other for work-tracking; Azure Repos / GitHub / Bitbucket / Local Git / Other for source-control).
2. Dev-lead authenticates -- env-var REFERENCES only; credential values never enter any tracked file.
3. Dev-lead explores the host's capabilities: types, states, fields, links, iterations, PR-feedback surface. Write probes only with explicit CPO consent.
4. Dev-lead models the host as a connection profile: logical-to-host type mappings, state mappings (with state_asymmetries fallback for hosts where the state machine collapses), field mappings, capability declarations, and operation_templates.<op> -- per-operation Mustache-templated request bodies for create / read / update / delete / query / link / comment / etc.
5. Dev-lead validates with the CPO and persists.

Every production-workflow skill reads operation_templates.<op> from the profile at runtime, substitutes placeholders from the call site, and executes via the appropriate transport (Bash/curl for HTTP hosts, az / gh CLIs, filesystem writes for Local strap-agile). Deterministic templates over reasoned-on-the-fly execution. New hosts ship as accelerator templates under .claude/strap/templates/connection-templates/; the discovery flow uses them as priors if present, runs from scratch if absent.

Local mode (strap-agile). One of /connect-devops-project's host options is Local. Work items live as markdown files under .claude/strap/work/<type>/<id>-<slug>.md. Each carries YAML frontmatter (id, type, state, parent links, assignee, timestamps); the body is the work-item content. State transitions update frontmatter. This is work-item-tracking-as-code: PR-reviewable, diffable in git history, branch-aware, no external service. Operations execute as filesystem writes; capabilities like iteration_get_capacity are unsupported (no calendar / team-capacity model in flat files) and the skills that consume capacity degrade per the documented fallback (read assumptions from project-profile.md).

Dispatch model

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

Two primitives, two scenarios:

Named-teammate dispatch is gated behind one harness env key (CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1), which the installer seeds in settings.json at install time. Without it a named Agent call does not fail -- it runs as an ordinary subagent -- so skills verify the shape of a fan-out by checking dispatched names against ListAgents rather than waiting for an error. Skills that depend on parallel fan-out check for these keys at pre-flight and surface an actionable error if absent.

Teammate shutdown via SendMessage is unreliable; /team-cleanup is the documented recovery primitive when team state wedges.

Work-item lifecycle metadata convention

Every STRAP-created work item carries three pieces of metadata that survive across host conventions:

1. Lifecycle metadata block at the top of the description body -- a table with Authored By / Authored At / Completed By / Completed At fields populated via Mustache placeholders in the type-specific template (requirement.template.md, spec.template.md, etc.). Set at create (Authored half) and at resolution (Completed half) by the relevant skill. Template re-rendering on resolution preserves the original Authored half.
2. AI tag distinguishing AI-authored work from human-authored work. Surfaces in DORA queries (Agent Efficiency Ratio compares AI-tagged Tasks' original estimate against actual cycle time) and in adopter reporting.
3. strap:<logical-type> tag (e.g., strap:requirement, strap:bug) for findability when the host's type mapping collapses (e.g., Azure DevOps' Issue is shared by Requirements and Bugs in some process templates). The strap:<logical-state> tag (e.g., strap:resolved) plays the parallel role when the host state machine collapses (ADO Task has no Resolved; the tag preserves the logical state).

State transitions are audited via [STRAP/agent:<name>] comments posted through operation_templates.work_item_comment_add so the logical actor is identifiable even when the host's native actor identity is always the human's az credential. Markdown-to-HTML conversion happens at the boundary for HTML-flavored hosts (declared by mapping.field_formats.description); markdown-flavored hosts (Local strap-agile) pass through unchanged. The conversion entity-escapes every non-ASCII character as a numeric character reference, so the payload survives every shell and transport encoding hop, and a write/read-back spot check at the session's first write catches mojibake before it spreads (the description-format boundary contract).

End-to-end pipeline run

Once installed and connected, STRAP drives features from idea to PR through a stable sequence:

1. CPO has an idea.
   /new-requirement -> req-lead drafts Requirement; CPO refines via /refine-requirement
                       until Resolved.

2. Requirement is Resolved.
   /create-spec -> spec-lead drafts Spec outline.
   /refine-spec drives Constituent Parts toward Resolved.

3. Spec is Resolved.
   For Specs with user-facing scope (any client-ui Constituent Part):
   /create-mockups -> designer interviews CPO, builds mockup code in the
                      configured paths, iterates until CPO approves, writes
                      the Mockup Reference section back to the Spec.
   /analyze-mockups -> spec-lead audits coverage + extracts data shapes +
                       maps to backend API declarations, writes the
                       Mockup Wiring Guide back to the Spec.
   /generate-features refuses if a user-facing Spec is missing either
   section; otherwise:

   /generate-features -> spec-lead authors Feature briefs; dev-lead persists
                         with lifecycle metadata.
   /decompose-feature -> per-Feature; activates any required domains (CPO-gated
                         structural precondition); dispatches active-domain
                         specialists as named teammates for read-only
                         planning; reconciles; persists Stories + Tasks.

4. Features ready.
   /plan-sprint -> single-sprint allocation (hard rule; overflow stays unallocated).
   /rebalance-sprint -> cross-sprint flow at sprint boundaries or mid-sprint.

5. Sprint executes.
   /execute-sprint -> dev-lead creates feature branch + per-agent worktrees.
                      Tasks sequenced by dependency, dispatched in waves via
                      named teammates. Dev-lead reviews each task branch, runs the
                      centralized test pass, sets Completed By / At at
                      resolution, prepares the PR.

6. PR opens. Reviewers comment; CI runs.
   /refine-pr -> dev-lead reads comments + failed checks via the source-control
                 connection profile, categorizes by domain, dispatches relevant
                 specialists, pushes fixes to the existing feature branch.
                 Thread resolution stays with the human reviewer.

7. PR opens, then merges.
   Agentic units (Tasks, Stories) auto-run to Closed as the pipeline
   completes them -- not gated on the parent. The execution skill resolves
   the value unit (Feature / Enhancement) at PR-open; /dora-reconcile's
   Pass A is an idempotent fallback that resolves a value unit once all its
   children are terminal. Value units stop at Resolved and wait.

8. /close-ceremony.
   The deliberate CPO ritual that accepts delivered value units -- Features,
   Enhancements, Bugs (plus any lingering Stories as interrupted-run
   stragglers) -- deciding per item, in a batch, or via the one-motion
   "close all Resolved value units" fast-path: close (Resolved -> Closed,
   value accepted), reject (back to Active with `rework` tag), defer (stays
   Resolved with `defer:<reason>` tag), or skip. Cycle complete.

Companion paths:
- /quick: single-motion CPO orchestration lever. Free-form description ->
  classification -> work-item chain creation -> specialist routing ->
  implementation -> centralized test pass -> draft PR, all in one
  invocation. Five chain shapes adapt to the ask; never refuses for size.
  Bypasses the deliberate Requirement -> Spec ceremony for DO-NOW work.
- /execute-sprint-full-auto: one-shot Spec-to-PR. From a Resolved Spec,
  generate Features, decompose, allocate, and execute across all Features in
  parallel, opening one draft PR per Feature. The Resolved Spec is the
  contract; per-phase approval gates collapse to dev-lead authority; the
  safety perimeter (no auto-merge, no Spec mutation, security Critical/High
  blocks, new-domain activation halts) is non-negotiable.
- /file-bugs / /fix-bugs: lighter-weight intake + targeted fix for Bug +
  Enhancement items, same lifecycle-metadata + state-transition discipline.
- /reset-feature: destructive Feature subtree delete; pre-deletion audit
  comment posted on the linked Spec so the trail survives.
- /context-prep / /context-fetch: cross-session continuation runbooks.
- /team-cleanup: recovery primitive for wedged team state.

Every operation runs through operation_templates.<op> from one of the two connection profiles. Skills are portable across adopters because their dispatch logic references logical types and active-domain specialists; the per-host details live in the connection profile and the project-profile, not in the skill body.

DORA governance and close ceremony

STRAP layers an explicit governance + metrics convention on top of the production pipeline. It separates execution (workflow skills that auto-close agentic units -- Tasks and Stories -- and stop value units at Resolved) from value acceptance (the CPO ritual that closes Resolved value units) from data quality (the daily janitor that keeps lifecycle metadata honest) from interpretation (the snapshot/render pair that turns data into reports).

/close-ceremony -- the deliberate CPO ritual for accepting delivered value units. Agentic units (Tasks, Stories) auto-run to Closed during execution; value units (Features, Enhancements, Bugs) stop at Resolved by design, and /close-ceremony is the only authoritative manual gate that converts a Resolved value unit into Closed. The CPO decides per item, in a batch, or via the one-motion "close all Resolved value units" fast-path: close (value accepted), reject (back to Active with rework tag + audit reason), defer (stays Resolved with defer:<reason> tag), or skip -- reject and defer are walk-or-batch decisions, while the fast-path only closes value units and skips lingering Stories. Each close emits a synchronous ledger event + audit comment; an optional final step chains the metrics refresh (reconcile -> collect -> report). Filter by --type, --owner, --days; --dry-run previews without applying. Produces a ceremony report at .claude/strap/state/close-ceremonies/.

/dora-reconcile -- the daily data-quality janitor. Pass A auto-cascades forward as an idempotent fallback (a value unit -> Resolved when all its children are terminal; a lingering Resolved agentic unit -> Closed on its own completion, not gated on the parent; Requirement -> Closed when its linked Spec is Resolved and a Feature is in a sprint) and surfaces hygiene gaps across eight passes (state mismatches, stale items, unlinked PRs, AI-tag inheritance, date hygiene, CompletedWork hygiene, Bug-specific hygiene, parent-child structure). With --auto-fix, derivable fields (state-transition timestamps + AI-tag inheritance from description metadata + wall-clock CompletedWork for AI-authored items) get stamped. The skill never invents data. Run log at .claude/strap/state/dora-reconcile-runs/. The load-bearing piece of the governance layer -- without daily reconcile, the lifecycle-metadata wiring sits idle.

The transition ledger -- an append-only, source-controlled record of every work-item state transition STRAP itself drives, written as session-sharded JSONL under state/transition-ledger/. It exists because host state-change timestamps are lossy or absent on some trackers and human-populated host fields drift: each event carries an event_time (exact for live transitions; reconstructed with a lower-confidence timing marker for events the reconcile fallback derives), so the metrics engine computes cycle time from STRAP's own instrumentation. The consumer reads ledger-primary with per-transition host-field fallback -- de-duplicating, flagging divergence between the two, and reporting coverage (the share of terminal items the ledger accounts for) as a first-class data-quality signal rather than silently trusting a partial record. Only STRAP-driven transitions enter the ledger, so the AI side is ledger-timed while the human side is host-field-timed; the engine reports the two coverages separately and derives one comparable AI-vs-human metric across that asymmetry. The contract is ../contexts/transition-ledger.md; producers emit through a single helper on the same enclosing-repo commit gate the shared brain uses.

/dora-collect + /dora-report -- the snapshot/render pair. /dora-collect writes a structured JSON snapshot of work items, the adoption denominator, the transition ledger, PRs (split into integration vs intermediate streams per code-connection.yaml's default_branch), and skill-log counts. The snapshot is read-only against every data source. /dora-report consumes the snapshot and renders a self-contained HTML report (inline-SVG charts; no external libraries): eight per-sprint sections -- STRAP adoption, STRAP autonomy, headline timing, AI Efficiency Ratio, at-a-glance, what landed, quality cycle-times, data quality -- plus a multi-sprint comparison view carrying agent attribution, lifecycle stage times, trend sparklines, movement and a methodology reference. Wall-clock as primary AI Efficiency Ratio (sidesteps the well-known OE/CW data-entry artifact where CompletedWork gets stamped equal to OriginalEstimate at close-time, making the ratio read 1.00x universally). Supports --compare for side-by-side prior-sprint analysis and --last-n N for multi-sprint trend charts, with --quality-threshold filtering low-quality snapshots from trend math.

The report deliberately does not carry the DORA-4. Deployment Frequency, Lead Time and Change Failure Rate were removed in v2.10 because STRAP cannot warrant them: a deployment has no author, so none of the three could be scoped to STRAP-executed work, and CFR additionally divided bugs raised in a window by deploys shipped in it. The adopter's own DevOps host owns that data and reports it better. What remains is what only STRAP knows -- how much of the delivered value it executed, how independently, and how fast its own lifecycle ran.

dora-analyst -- the interpretation specialist dispatched by the dev-lead when the CPO asks for analysis on top of a rendered DORA report. The analyst reads the snapshot + HTML, performs interpretive analysis (anomaly investigation, trend explanation, release-readiness recommendations, governance-compliance assessment, adoption and autonomy trajectory), and produces a structured analysis report at .claude/strap/state/dora-analyses/. The analyst is the interpretation layer, not the operator -- the dev-lead runs the data-acquisition skills (collect, report, reconcile) directly because they're mechanical; the analyst's value-add is interpretation atop the data, never raw queries.

The four skills + the agent form a self-reinforcing governance loop: execution lands work at Resolved -> reconcile keeps the metadata honest -> collect snapshots the cleaned state -> report renders the evidence -> analyst interprets when the CPO asks -> close-ceremony converts Resolved to Closed when the CPO has accepted the value. The AI tag and strap:<logical-type> tag are the load-bearing convention that lets all five distinguish AI-authored from human-authored work and route correctly across the loop.

Onboarding and upgrade

Three skills carry the install + maintenance lifecycle.

/strap-in -- the first-encounter onboarding skill the CPO runs after install. The dev-lead reads the codebase at a shallow scope, dispatches relevant specialists in parallel as named teammates for read-only deep-dive, and curates the persistence stack (project-profile.md, per-agent memory, per-agent rules) so the canonical roster comes alive for THIS project. Code immutability is enforced throughout via read-only tools palettes (Read, Grep, Glob, Bash -- no Write, no Edit). The invariant releases when /connect-code-repo clears its satisfied gate.

/strap-refresh -- the re-run companion. Reads the existing persistence stack as priors, runs a shallow scan against the current codebase, detects diffs between priors and current state, surfaces them to the CPO for approval, then dispatches only the specialists whose domains actually changed (or newly appeared). The single-writer rule applies to refresh runs same as initial onboarding: the dev-lead is the only applying hand, and nothing lands without the CPO's approval.

/strap-upgrade -- the package-vs-install reconciliation skill. Diffs the freshly-pulled STRAP package against the adopter's installed .claude/ tree using the previous-version tarball (distribution mode) or git show <previous-tag>:<path> (source mode) as the three-way-merge anchor, applies non-conflicting package changes, surfaces conflicts on package-managed files for CPO resolution, preserves adopter customizations on protected paths, and updates .claude/.strap-version.json. The protected-paths list mirrors the persistence-stack ownership and is split into two categories: adopter-owned (project-profile, continuations, state, settings -- excluded from diff entirely, no adds either) and seeded-then-curated (per-agent memory, per-agent rules, dev-lead memory + index -- package-only adds APPLIED so new operating learnings or new specialists land at the adopter install; modify and conflict suppressed so adopter curation wins). See upgrade-guide.md for the operational walk-through.

What is NOT in scope

For clarity:

• Federation across multiple work-tracking adapters within one installation. Each surface has at most one adapter.
• Multi-language LSP/AST tooling. Specialists read code via Claude rather than parsing it programmatically.
• Cross-host federation across sub-repos. The connection profile is one file per surface but carries a sub_repos: map: the connect skills configure the primary sub-repo, then walk each non-primary sub-repo to capture per-sub-repo overrides (a different work-tracking project on the same host, a different source-control host/org/auth, or per-sub-repo branch protection). What remains out of scope is federating a sub-repo on a genuinely different host/org than the primary -- that case is captured (surfaced as a limitation on the work-tracking side; persisted as an override on the source-control side), not federated.
• Per-sub-repo project-docs rendering. Umbrella PROJECT.md / ARCHITECTURE.md / STACK.md capture the system view; per-sub-repo doc rendering is a future Feature.
• Strap-agile iterations filesystem layout. Capability is declared supported but the file shape is undefined; a future release will pin it down alongside an HTML backlog/kanban/sprint viewer.
• In-place edits to canonical agent role contracts, STRAP-shipped SKILL.md files, or team rules files. These are package-owned; in-place edits surface as conflict on every /strap-upgrade. The supported customization paths are per-agent rules (augment canonical agents), adopter-authored new agents and skills (add alongside the canonical set), and per-agent memory (project-specific tradecraft).

References

• strap-in.md -- the adopter-facing narrative this document complements.
• customization-guide.md -- how adopters tailor STRAP within its curation model.
• upgrade-guide.md -- the /strap-upgrade operational walk-through.
• ../contexts/onboarding-design.md -- v2 design source-of-truth + canonical connection-profile schema.
• ../contexts/budget-discipline.md -- cross-cutting budget pattern every workflow follows.
• ../contexts/umbrella-sync.md -- polyrepo shared-brain state-sync contract (facts vs opinions, allow-list, state-PR governance).
• ../contexts/transition-ledger.md -- append-only state-transition record the DORA engine reads for host-independent timing.
• ../../skills/connect-devops-project/SKILL.md -- work-tracking connection-profile schema source-of-truth.
• ../../skills/connect-code-repo/SKILL.md -- source-control connection-profile schema source-of-truth.
• ../../skills/decompose-feature/SKILL.md -- reference workflow skill (parallel named-teammate dispatch + lifecycle metadata).
• ../../skills/execute-sprint/SKILL.md -- reference workflow skill (lifecycle metadata round-trip + Local Git PR ceremony).

Getting the most from DORA reports

The report STRAP renders via /dora-report is the deepest single instrument the pipeline exposes for evaluating how the team is performing. It draws on the work items STRAP touched, the pull requests it opened, and -- above all -- STRAP's own transition ledger. This document walks adopters through the operational disciplines that make the report sharp instead of noisy: what feeds each metric, where data quality matters, the cadence to keep, and the configurability the report exposes.

Audience: any CPO running STRAP whose team has crossed the first few sprints and wants the report to be measuring something true. New adopters should run /strap-in first, complete a sprint, then return here.

The DORA-4 are gone, and that is the point (v2.10). Earlier revisions of this page opened with Deployment Frequency, Lead Time for Changes and Change Failure Rate documented in full. All three have been removed from the report. They were not removed because they are bad metrics. They were removed because STRAP cannot warrant them:

• A deployment has no author. Nothing in a pipeline run says whether STRAP or a person drove the change it shipped, so Deployment Frequency could never be scoped to STRAP-executed work -- and a number that mixes the two, presented in a STRAP report, reads as a STRAP claim.
• Lead Time was computed from the PR cycle, which went out with the deploy metrics for the same reason.
• CFR was not a ratio. Its numerator counted Bugs raised in the window; its denominator counted deploys shipped in it. Those are two unrelated populations, and dividing one by the other produced a percentage that looked like a failure rate and was not one.

Your DevOps host almost certainly computes all three, from data it owns, better than STRAP can. Read them there. What STRAP reports now is the thing only STRAP knows: how much of your delivery it executed, how independently, and how fast its own lifecycle ran.

What the report measures now

Three questions, in the order the report answers them: adoption (how much of your delivered value STRAP delivered), autonomy (how independently it operated), and productivity (throughput and efficiency). Every figure is computed from data STRAP can attest, or it declines to render and says why.

Feature highlights

What it shows. The Features STRAP delivered this window, leading the report — because a page that opens on a ratio is hard to read if you have never used STRAP, and the work itself is the most legible thing on it. Per Feature: when it activated and was delivered, how long that took, which agent resolved it, the linked PR, and how many of its Tasks STRAP attested.

What feeds it. Everything except the title comes from STRAP's transition ledger. The title is read from your work tracker and reproduced verbatim — STRAP makes no claim about its wording, and a title that reads poorly is fixed where it was written, in /generate-features, not here. Feature descriptions are deliberately not shown: they are specifications, and summarising one would put a non-deterministic step inside a report whose whole claim is that it reproduces exactly.

Where it gets noisy.

• Features your tracker reports as delivered but STRAP did not execute are counted, not described. A highlights section showing only STRAP's work without that count would imply STRAP delivered everything.
• Ordering is by delivery time, newest first — never by size or "importance". Any such ranking would be STRAP asserting which of your Features mattered most, which it has no basis to do.
• A Feature resolved before v2.10 (or by a skill that did not name an agent) shows as resolved without a named agent. That is the honest reading of a ledger event with no agent field, not a gap to fill in.

STRAP adoption

What it measures. Attested STRAP value units delivered in the window -- Features, Enhancements, Bugs -- over the host's total delivered count of those types in the same window.

What feeds it. The numerator is STRAP's transition ledger: exact, host-independent, and countable. The denominator is a plain count read from your work tracker against mapping.adoption_denominator_root.

Where it gets noisy. This is the only figure whose two sides come from different systems, so it carries two warranties and is never computed on further. When the two sides cannot be shown to share a definition of "delivered" and a clock, the report declines to render it and names which side failed rather than showing a ratio it cannot defend. An undeclared adoption_denominator_root means the denominator is skipped, never defaulted -- a project-wide count would sweep in co-resident teams, and reusing the numerator's own area path would read near 100% by construction.

STRAP autonomy

What it measures. How independently STRAP operated, reported as counts plus a level (L0-L3), never as a bare score.

What feeds it. Every state transition an execution skill made, plus every advance the upstream-state precondition gate applied. Acceptance closes, reconcile repairs and planning signoffs are excluded -- all three are attested facts, but none is STRAP executing work, and counting them would let a CPO clicking "close" raise the number.

Where it gets noisy. Coverage renders inline, because the counts only mean something against the share of delivered work the ledger actually accounts for. Below the configured autonomy_coverage floor the metric refuses rather than reporting a rate from a thin ledger. The ladder stops at L3: levels 4 and 5 need thresholds only a real ledger can derive.

Acceptance rework

What it measures. Of the value units STRAP delivered this window, the share you sent back at the close ceremony. It renders inside the autonomy block, not beside it — deliberately. An agent that works independently and gets sent back half the time is not autonomous, it is unsupervised, and quoting the autonomy level without this number would be exactly the flattering figure this report is built to avoid.

What feeds it. Both sides are STRAP's own ledger. Delivery is the forward event carrying a unit into Resolved; the rejection is the backward resolved -> active event /close-ceremony writes when you reject. It never consults your work tracker, and it is causally tied to the specific unit it judges — which is what the retired Change Failure Rate never was.

Where it gets noisy.

• It measures acceptance, not correctness. A low rate may mean good work, or a ceremony where the batch got waved through. It counts what review caught and says nothing about what reached production and failed there. That limitation is printed on the page, not buried here.
• It refuses below rework_sample (default 5 delivered units) rather than reporting a flattering 0%. The floor sits on the denominator on purpose: "nobody was rejected out of twenty delivered" is a real result worth reading, while "nobody was rejected out of one" is not a measurement of anything. Without the floor those two are the same number.
• Rejections of units you delivered in an earlier window, and backward moves that are not ceremony rejections (a /dora-reconcile repair, say), are counted and shown separately rather than folded into the share.

Expect this to refuse at first. Probed across every live adopter install on 2026-08-13: the reject path has never fired in production. If your ceremony has always been close-or-skip, this figure will refuse until it has enough delivered units and you actually reject something. That is the metric working, not failing.

Bug resolution time

Renamed from "Mean Time to Restore (MTTR)". The old name made three claims the measurement does not support: it is a median, not a mean; it clocks a work item, not a restored service, and nothing in STRAP observes an outage ending; and it is now scoped to bugs STRAP attested resolving. Do not compare this figure against published MTTR benchmarks -- they are calibrated for time-to-restore-service and will flatter or damn you for the wrong reason.

What it measures. Median time from a prod-environment Bug being filed to its Resolved (or Closed, when no Resolved state exists in the host's state machine) transition.

What feeds it. Bug work items with environment: prod AND a Resolved/Closed state transition timestamp within the report window. The report uses the wall-clock between Microsoft.VSTS.Common.CreatedDate and Microsoft.VSTS.Common.ResolvedDate (or the host-specific equivalents from the connection profile's mapping.fields).

Where it gets noisy.

• Bugs Resolved after the report window ends are not counted in the current window; they'll surface in a later report. The report exposes the count of in-window-filed-not-yet-resolved Bugs as the in-flight indicator.
• Bugs marked Resolved as "duplicate" or "not a bug" inflate the count of resolutions without an actual fix, and STRAP does not currently exclude them. /dora-collect captures resolved_reason and reports its coverage, but nothing reads the field: there is no disposition filter, and the mttr_resolution_reasons key earlier revisions of this page told you to configure was never read by anything. Treat this figure as "time to reach a Resolved state", not "time to fix". If your team resolves many duplicates, the median is optimistic by roughly their share.

The rest of the report

• AI Efficiency Ratio. OriginalEstimate hours divided by wall-clock cycle hours (activated to closed), computed per Task and aggregated as a P50 across eligible Tasks. Eligible means attested (since v2.11.1): the Task carries a transition-ledger execution record and both wall-clock endpoints are ledger-sourced, so the hero never quotes a number reconstructed from host fields -- a sprint with too few attested Tasks renders the no-signal pill instead. The estimate divides as the human baseline: taken from the Task's creation ledger event when one carries it, from the host planning field otherwise. Above 1x means execution beat the estimate. Wall-clock is primary deliberately -- see the transition-ledger section below for why the older estimate-over-CompletedWork form was abandoned. Required field: OriginalEstimate at Task creation (see OriginalEstimate discipline below).
• Agent attribution. Per-agent counts taken from the agent field on each ledger event. Credit is per transition, not per item: a Story the dev-lead activated and a specialist resolved contributes to both, so "items touched" is a separate count that deliberately does not sum to the transition total. Transitions STRAP made without naming an agent are unattributed and credited to no role.
• Quality cycle-times. P50 + P90 per work-item type per state transition, plus cross-type hops (Spec resolved to first Feature created, and so on).
• Lifecycle stage times. Median time per stage across the STRAP lifecycle. Called "Pipeline funnel" until v2.10; both halves of that name were wrong, since it is a work-item clock rather than a CI/CD one and nothing is counted as lost between hops.
• Aging Alerts. Stale work items, split into STRAP-instrumented (via mapping.strap_instrumentation_signals) vs inherited, so adopters can see whether STRAP's process is accelerating the stuck items or just inheriting the same backlog patterns.

Removed in v2.10 along with the DORA-4: the per-developer breakdown and its cycle-time trend bars, PR iteration-count buckets, the PR size distribution, the PR Weight gradient, cluster cycle-time, and the per-layer and per-target metric blocks. Each described PR or pipeline activity rather than STRAP-executed work.

The transition ledger -- where AI timing comes from

The instruments above depend on when work moved between states. Host state-change timestamps are lossy or absent on some trackers, and human-populated fields drift. STRAP closes that gap with the transition ledger: an append-only, source-controlled record of every state transition the pipeline itself drives, written as session-sharded JSONL under state/transition-ledger/.

• Exact timing over host fields. Each event carries an event_time and a timing fidelity marker -- exact for live transitions, reconstructed at lower confidence for events the reconcile fallback derives. The engine reads ledger-primary with a per-transition host-field fallback -- it uses the ledger time when the ledger has the transition, falls back to the host field when it does not, and cross-checks the two, flagging divergence rather than silently trusting one source.
• Coverage is a first-class signal. The engine reports coverage -- the share of terminal items the ledger accounts for -- as a data-quality number, so a partial ledger reads as "80% ledger-backed" rather than masquerading as complete. Low coverage is a prompt to drive work through the pipeline (which emits events) rather than transitioning items by hand.
• There is no human track. Only STRAP-driven transitions enter the ledger. Earlier revisions of this page described an "AI side" timed from the ledger and a "human side" timed from host fields, reported as two comparable velocity lines. That second lane was retired, because it was never a measurement of people: it held every item STRAP had no record for -- work done outside the pipeline, work predating adoption, work whose tags were never applied -- and published that union as human performance. What the report shows instead is attested and unattested. Unattested is a third state, not a second lane: it is stated as a count, attributed to no one, and never divided into a rate. An absence of proof is not proof of a person.
• Wall-clock is the only AI-efficiency signal. The retired estimate-over-CompletedWork form (OriginalEstimate / CompletedWork) was vulnerable to a well-known data-entry artifact -- CompletedWork stamped equal to OriginalEstimate at close-time makes the ratio read 1.00x universally. The ledger's exact wall-clock timing sidesteps it, and the shipped ratio reads no CompletedWork at all: earlier revisions of this page described the OE/CW form surviving as "a secondary cross-check", but nothing computes it -- the cw_oe_degeneracy flag survives purely as a data-quality signal about the host fields themselves.

The ledger contract is ../contexts/transition-ledger.md; on a polyrepo umbrella the shards ride the shared-brain state repo (see the umbrella state-sync section of architecture.md).

Operational disciplines

The instruments above are only as sharp as the data they consume. Six adopter disciplines keep the data clean.

Environment-tagging discipline (Bugs)

Bug resolution time depends on Bug work items carrying an environment value. /file-bugs always prompts for environment via AskUserQuestion, with the result persisted both as the environment field AND as an env:<value> tag.

Environment values: /file-bugs offers production, staging, development; adopters can extend the list per project. The report counts bug resolution time against prod-matching environments (env:production, env:prod); other environments surface in the by-environment breakdown. The tag is read first and the host field only as a fallback, so adopters whose tracker has no environment field still get the metric.

Backfill. For Bugs that predate STRAP's environment capture or were filed outside /file-bugs, run /dora-reconcile --auto-fix -- Pass G stamps state-transition timestamps and Pass H (Bug hygiene) flags Bugs missing environment for CPO backfill. The report's data-quality flags surface the count.

OriginalEstimate discipline (Tasks)

The AI Efficiency Ratio requires OriginalEstimate set at Task creation time. STRAP's /decompose-feature skill prompts for estimates per Task during decomposition. Adopters who skip estimates leave the ratio incomputable for those Tasks.

Recommended values. Half-day increments (0.5, 1, 2, 4 hours per Task) work well at the Story-decomposition level. Larger Tasks suggest re-decomposition. The estimate is committed-effort, not wall-clock; CompletedWork captures wall-clock.

Hygiene. /dora-reconcile Pass F surfaces in-flight Tasks without OriginalEstimate; backfill or accept the gap (the Task gets excluded from the ratio).

CompletedWork discipline (Tasks + Bugs)

A host-side bookkeeping hygiene, not an input to any report figure -- the AI Efficiency Ratio's wall-clock comes from transition timestamps (ledger-first), and no shipped metric reads CompletedWork. STRAP's /execute-sprint and /fix-bugs skills stamp CompletedWork at the terminal transition automatically (Closed for Tasks, Resolved for Bugs); manually-resolved items need the field set. /dora-reconcile --auto-fix Pass G stamps CompletedWork from Resolved - Active wall-clock when the field is missing AND state-transition timestamps exist.

Layers + Sub-repos (polyrepo)

Declare Sub-repos in project-profile.md with Role + Active domains per sub-repo, and the Layers section when your umbrella has more than one deployable layer. The report uses layers for Bug attribution -- resolving each Bug to a layer via its strap:layer:<slug> tag first and its host area path only as a fallback -- and sub-repos for PR routing.

deployment_targets: no longer affects the report (v2.10). It was the third leg of a three-part configuration that produced per-target Deployment Frequency, per-layer Lead Time and target-scoped CFR. All three metrics are gone, so nothing in the report reads the declaration. It remains a valid topology statement in devops-connection.yaml and /connect-devops-project still captures it; it simply buys you no metrics today. If you configured it for the report, you can stop maintaining it for that reason.

/dora-reconcile cadence

Run /dora-reconcile --auto-fix weekly. The skill walks eight passes (state mismatches, stale items, unlinked PRs, AI-tag inheritance, date hygiene, CompletedWork hygiene, Bug-specific hygiene, parent-child structure) and:

• Auto-fixes derivable fields (state-transition timestamps, AI-tag inheritance, wall-clock CompletedWork).
• Surfaces non-derivable gaps for CPO decision (state mismatches, structural issues).
• Logs a run report at .claude/strap/state/dora-reconcile-runs/.

The weekly cadence catches drift early; monthly is fine for small teams. Daily is overkill except when actively investigating a discrepancy.

/close-ceremony per sprint

At sprint boundary, run /close-ceremony to accept delivered value units -- Features, Enhancements, and Bugs (plus any lingering Stories as interrupted-run stragglers). Decide per item or in a batch -- Close (value accepted), Reject (back to Active with a rework tag), Defer (stay Resolved with a reason tag), or Skip -- or take the one-motion "close all Resolved value units" fast-path, which closes every Resolved value unit and skips lingering Stories (reject and defer are per-item/batch decisions the fast-path does not offer). Each close emits a synchronous transition-ledger event and an audit comment, and an optional final step chains the metrics refresh (reconcile -> collect -> report). PR-merge and all-children cascades land automatically via /dora-reconcile; /close-ceremony is the deliberate manual CPO acceptance moment.

Why it matters for DORA. Throughput counts a value unit at its terminal membership -- a Feature, Enhancement, or Bug counts as delivered when it reaches Resolved, so closing it does not change the throughput number. Closing accepts value that has already counted; it never makes value "appear." What the ceremony governs is the acceptance record: the Closed state, the audit trail, and the deliberate CPO sign-off that a Resolved unit's value is accepted. Running it each sprint boundary keeps that acceptance record current without inflating or deflating the delivery metrics.

Configurability

The DORA report honors three configurable surfaces in devops-connection.yaml's mapping: block. None are required; sensible defaults apply when absent.

mapping.dora_confidence_thresholds

Sample floors below which a metric renders the no-signal pill instead of a figure, so a value computed from three data points is not presented with the same confidence as one computed from three hundred. The block is flat, and every key takes a single number:

mapping:
  dora_confidence_thresholds:
    bug_resolution_sample: 5       # min prod bugs before a resolution-time P50 renders
    cycle_time_sample: 5           # min samples before a cycle-time figure renders
    ai_eff_sample: 5               # min samples before an AI Efficiency ratio renders
    rework_sample: 5               # min delivered value units before an acceptance-rework share renders
    adoption_unclocked_share: 0.05 # max share of delivered units the host cannot date
    autonomy_coverage: 0.80        # min attested share of delivered work before autonomy rates
    autonomy_min_transitions: 20   # min execution transitions before autonomy rates

Setting any key to 0 disables that one threshold. Unrecognised keys are ignored silently, so check spelling against this list.

Renamed keys are honoured; a retired one is not. A config still setting mttr_sample is applied to bug_resolution_sample, and lead_time_sample to cycle_time_sample -- both renames tracked their metric's rename, and the aliases exist so an existing devops-connection.yaml keeps working untouched. cfr_deploys is retired outright: it floored Change Failure Rate, and with that metric gone there is nothing to alias it to. A config still setting it is inert and can be deleted.

Corrected in v2.10. Earlier revisions of this page documented a nested block -- deployment_frequency.high_min, lead_time.high_max, cfr.low_max, cfr.mttr_resolution_reasons, mttr.high_max and siblings -- presented as performance bands rather than sample floors. None of those keys was ever read by anything. The engine has only ever matched the flat keys above, so an adopter who configured that block got no effect and no warning. If your devops-connection.yaml carries the nested form, it is inert and can be deleted. Verified by running the documented block through the engine's own parser: it changed zero thresholds.

The report does not band metrics into Elite/High/Medium/Low at all. It reports values with their coverage and refuses when the sample is too thin, which is a deliberate difference from benchmark-style DORA reporting: a band invites comparison against an industry cohort STRAP cannot see.

mapping.strap_instrumentation_signals

The Aging Alerts split between STRAP-instrumented and inherited items. Configurable signals identify which Tasks are STRAP-tracked vs pre-STRAP backlog:

mapping:
  strap_instrumentation_signals:
    tags_any:
      - "AI"             # STRAP creates Tasks with this tag by default
      - "strap:*"        # logical-type prefix tags
    fields_any:
      - "Custom.STRAPVersion"   # set when /decompose-feature creates the Task
    title_prefix_any: []         # rarely needed; tags are usually sufficient

Without configuration, the default is tags_any: ["AI"]. Adopters with custom workflows can extend.

mapping.cross_version_field_aliases

Honors field renames detected during cross-version checks. When a host renames a field (e.g., Custom.PullRequestUrl -> Custom.PRUrl), /connect-devops-project re-run flow asks the CPO to confirm + records the rename in mapping.field_renames. The report reads through the alias when computing metrics that reference renamed fields.

--with-git-diff-weight

/dora-collect still accepts this flag and still computes per-PR git-diff line counts into the snapshot. No report section renders them -- the PR Weight gradient left in v2.10 with the other PR metrics -- so the flag currently costs ~5-10 minutes per 100-PR window and changes nothing you can see. Leave it off unless you are collecting the data for your own analysis of the snapshot JSON.

What the report cannot tell you

Questions the report cannot answer alone:

• How often do we deploy, how long does a change take to ship, and how often does it break? Deployment Frequency, Lead Time and Change Failure Rate were removed for the reasons at the top of this page. Your DevOps host computes them from data it owns; read them there. STRAP not reporting a number is not STRAP claiming the number does not matter.
• Did this sprint produce value for end users? The report measures work-item state and STRAP's own execution record. Whether the shipped features moved a business metric is product-side analysis.
• Is the team happy? Velocity health and engagement are different signals. Pair the report with retros, 1:1s, eNPS.
• Should we add headcount? The report shows what the current team is producing. Capacity decisions require projecting against business priorities.
• What did the people on the team do? By design. The report measures what STRAP executed; everything else is unattested, and unattested is not a synonym for human.

Use the report as one of several instruments. It is sharp when the disciplines above are kept; it is dull when the data layer is leaky.

References

• ../../skills/dora-report/SKILL.md -- the report generator
• ../../skills/dora-collect/SKILL.md -- the snapshot collector
• ../../skills/dora-reconcile/SKILL.md -- the weekly janitor
• ../../skills/close-ceremony/SKILL.md -- the per-sprint acceptance ceremony
• ../../skills/file-bugs/SKILL.md -- Bug creation flow (always-on environment capture)
• ../../skills/connect-devops-project/SKILL.md -- mapping.* configuration surfaces
• ./architecture.md -- broader STRAP context
• ./walkthrough.md -- E2E STRAP walkthrough for a new adopter

Customization Guide

How adopters tailor STRAP to their project without breaking the upgrade path. 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 the per-project tuning happens through a small set of curated files written only by the dev-lead's hands, and -- for rules and memory -- only on the CPO's ratification.

This guide is for the Claude Pipeline Orchestrator (CPO) -- the human who owns the install. Read it before editing anything under .claude/. The pattern you pick determines whether the next /strap-upgrade preserves your change cleanly, surfaces it as a conflict, or overwrites it.

The customization surface

Four surfaces are adopter-tunable. Everything else is package-owned.

Three other adopter-owned categories are tracked but rarely edited directly:

• Continuations (.claude/strap/contexts/continuations/<topic>.md) -- written by /context-prep, read by /context-fetch. Session-state, not configuration.
• Settings (.claude/settings.json, .claude/settings.local.json) -- harness permissions + env. Edited via the harness /config flow or the installer, not directly.
• Project docs (default path .claude/strap/project-docs/, or whatever the Project docs paths field declares) -- the human-facing PROJECT.md, ARCHITECTURE.md, STACK.md rendered by tech-writer at /strap-in and refreshed surgically by /strap-refresh. A self-contained <project-name>-orientation.html companion is rendered alongside the three markdowns via the STRAP html-render pipeline at .claude/strap/tools/html-render/. The markdown is the source of truth (surgically updated at /strap-refresh); the HTML is a derived artifact (always full re-render). Both are read-mostly; the dev-lead curates through the closing-phase dispatches, not through in-place edits. The HTML renders through the pipeline's default single-page layout; Welcome-to-STRAP.html opts into the pipeline's paged guide layout via its own render config, so the two artifacts share tooling but present differently.

That's the entire customization surface. There is no project.yaml. There is no template-rendering layer. There is no agent registry. The fixed canonical roster + the curated persistence stack is the whole model.

Single writer, orchestrator authority

Only the dev-lead's hands touch per-agent rules and per-agent memory, and only on the CPO's ratification. The cycle has three distinct acts: agents and skills propose -- a specialist that learns something in the field queues a proposal from its dispatch; the CPO ratifies -- through /ratify (the proposal queue) or by invoking a write skill directly; the dev-lead applies the ratified change as an explicit, atomic, diff-reviewable edit. No silent writes, ever.

The write surface is seven skills: /memory-show, /memory-add, and /memory-refine for memory; /rule-show, /rule-add, and /rule-refine for rules; /ratify for the queued proposals specialists raise during dispatches. Every entry follows the brain-format contract (.claude/strap/contexts/brain-format.md): the claim type is declared, facts cite their producer, and a new fact is born provisional until a second independent observation confirms it.

This split 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 writing hand keeps the stack coherent; one human authority keeps it honest.

Two consequences worth internalizing:

• A claim found wrong is invalidated in place, never deleted. Deleting a wrong learning restores the conditions that produced it. Refuted entries flip to anti-guidance carrying their counter-evidence; obsolete entries become tombstones.
• Ratification is a human act. Nothing reaches a rules or memory file without the CPO's per-proposal decision. Proposals queue at .claude/strap/state/brain-proposals/ and are presented at sprint boundaries, or whenever you invoke /ratify.

Tuning project shape

Most customization is project-profile curation. The project profile is what tells every specialist what THIS project is.

Stack tuning. Add or edit the Stack section to capture languages, frameworks, runtimes. Update when the project adopts a new tech (e.g., adds a mobile client, swaps databases). The dev-lead reads the project profile on every invocation; updating it is the cleanest way to redirect specialist behavior.

Domain activation. The Domains section enumerates which logical concerns (client-ui, api, core, data, infrastructure, integrations) are active on this project, names the specialists each domain dispatches to, and records the per-domain Source-of-truth paths + Conventions. The client-ui domain covers any client-side UI form factor -- web (Angular / React / Vue / etc.), desktop (WPF / WinForms / MAUI / Avalonia / Borland C++ Builder VCL / etc.), mobile (Xamarin / MAUI / SwiftUI / native), cross-platform runtimes (Electron / Tauri / Flutter Desktop), AND server-rendered patterns (Python widget libraries like Streamlit / Dash / Gradio and in-house/custom widget frameworks, Phoenix LiveView, Rails Hotwire, Laravel Livewire, Blazor Server, classic template engines, vendored JS widget libraries). frontend-engineer dispatches across all of them via the same disciplines; the project profile names the specific framework. Adding a new domain (e.g., a new mobile client adds client-ui paths) goes through the /decompose-feature activation gate when a Spec first requires it, or through /strap-refresh when the project profile drifts from current codebase shape.

Polyrepo Sub-repos. When the install is a polyrepo umbrella (multiple peer sub-repos at depth-1 under the install root, each with their own .git/), /strap-in's polyrepo path populates a top-level Sub-repos section in project-profile.md with one H3 entry per sub-repo. Each entry carries seven fields: Path (relative from install root), Purpose (one-line role), Stack (per-sub-repo languages and frameworks), Conventions (per-sub-repo branch / commit / lint patterns that differ from the umbrella), Source-of-truth (paths exemplifying the sub-repo's shape), Runtime dependencies (internal cross-sub-repo coupling -- external deps like Postgres or third-party APIs belong in Stack or STACK.md), and Activated. The section starts empty for single-project installs and stays empty -- a populated Sub-repos section is the polyrepo signal that /strap-refresh reads to skip re-prompting on subsequent runs. Domains can still exist alongside Sub-repos: a Domain can declare Source-of-truth paths that span multiple sub-repos (e.g., a core domain spanning two libs), and the dev-lead curates the Domain/Sub-repo relationship at synthesis. To restructure -- add a sub-repo to the umbrella, remove one, restate a runtime-dependency contract -- direct the dev-lead through /strap-refresh, which surfaces structural diffs explicitly before any updates land. CPO can defer or ignore a structural diff per case before applying it.

Polyrepo shared brain. On a polyrepo umbrella the persistence stack syncs across developers through a dedicated state repo established at /connect-code-repo. The package rides its own install (from the installer); the brain -- memory, rules, the project profile, the transition ledger, ceremony reports -- rides the state remote (via /strap-sync). The two never fight: memory files carry merge=union so concurrent additions both land, facts auto-merge on unique filenames, and curated opinions (memory, rules, the profile) land through one reviewed state PR per session. Single-repo installs need none of this -- the brain rides the code repo everyone already pulls.

Mockup paths (client-ui domain only). When the client-ui domain is active and the project already has a mockup application (e.g., an Nx workspace with web-mockups and mobile-mockups), declare its paths in a Mockup paths field on the client-ui domain entry. /create-mockups writes designer-authored mockup files under the declared paths. When Mockup paths is absent, the skill falls back to .claude/strap/mockups/spec-<id>/ -- usable out of the box, but adopters with stack-specific mockup tooling typically prefer the override so the running mockup app picks them up directly.

Project docs paths (top-level). Declares where the human-facing project-orientation documents (PROJECT.md, ARCHITECTURE.md, STACK.md) land. tech-writer renders these from the curated persistence stack at /strap-in's closing phase and refreshes them surgically at /strap-refresh's closing phase. When the field is absent, the skill falls back to .claude/strap/project-docs/. Adopters with an existing docs directory (e.g., docs/, documentation/project/) declare it here so the rendered docs land where the team already looks for them. The first declared path is the write target; subsequent paths document additional locations for awareness. The path is protected by /strap-upgrade (adopter-owned; never reconciled against the package).

Layers. The top-level Layers section names the deployable layers of your product. Each layer declares a Pipeline pattern (glob or regex matching pipeline run names), an optional Product layer (grouping label), an optional Federation pattern (file-path glob for code-activity attribution), and Excluded from DORA (boolean; default false). When the section is empty, the report degrades gracefully to single-layer -- adopters with simple single-pipeline setups can leave it empty.

Since v2.10, Layers does not change the report. Every per-layer block -- per-layer CFR, per-layer deploy counts, the Layer Metrics section -- was removed with the metrics that fed them, and no surviving section renders per layer. The section is still parsed, still stamped into the snapshot as metadata.layers_resolved, and /file-bugs and /quick still stamp strap:layer:<slug> on the items they create, so the attribution data keeps accumulating against the day a per-layer view returns. But declaring area_paths or sub_repos today buys you nothing visible in the report, and it is honest to say so rather than let you maintain configuration for an output that does not exist.

Build / test commands. The Build and test section carries the active-domain build + test commands. /execute-sprint, /fix-bugs, and /refine-pr all read these for the centralized build-and-test pass.

Conventions. Sprint cadence, naming convention, pair topology, capacity assumptions -- anything /plan-sprint and /rebalance-sprint consult when the host doesn't supply it natively. Branch conventions, commit-message format, worktree-root override -- anything /execute-sprint consults if the connection profile doesn't pin it down.

When in doubt, ask the dev-lead to surface what it actually reads from the profile, then update the profile. The profile is the canonical record; if a behavior isn't grounded in the profile, it should be.

Tuning specialist behavior

When a specialist almost made a mistake or has accumulated tradecraft worth keeping, the fix lands in per-agent rules or per-agent memory -- through the propose/ratify/apply cycle.

Per-agent rules are guardrails. "Don't push directly to main." "Always run the test suite from the repo root, not from a subdirectory." "Validate Terraform plans against a dry-run before applying." Added reactively when something needs preventing.

Per-agent memory is soft tradecraft. "The test runner takes 8 minutes after a fresh dependency install; warm it once first." "This codebase prefers the older mapping pattern for X." "Use --no-build after the separate build step or you waste eight minutes." Grows naturally as work happens; specialists notice things and propose; the CPO ratifies what is worth keeping.

The distinction matters: rules block behavior; memory shapes behavior. Use rules for hard constraints, memory for soft guidance. The proposal bar differs accordingly: a rule proposed from the field must cite an observed failure, not just an observation, because a wrong rule blocks correct work.

The CPO drives curation through the seven-skill surface:

• /memory-show <agent> / /rule-show <agent> to inspect what is already there.
• /memory-add <agent> / /rule-add <agent> to add one entry directly -- invoking the skill IS the ratification act.
• /memory-refine <agent> / /rule-refine <agent> to sharpen, confirm, or invalidate existing entries. Never deletes: a wrong claim flips to anti-guidance in place.
• /ratify to work the queue of proposals specialists raised during dispatches -- one proposal at a time, your decision on each.

All writes flow through the dev-lead's hands; all decisions are the CPO's.

Tuning token budgets

STRAP's budget discipline is per-workflow (/strap-in, /strap-refresh, /decompose-feature, /execute-sprint, /refine-pr, /fix-bugs, /quick, /create-test-plan). The CPO confirms the onboarding workflow's per-agent + session-aggregate budgets once at /strap-in time; remaining workflows' defaults are written silently to MEMORY.md + usage.yaml. Subsequent workflows pull defaults silently.

When defaults don't fit your project's natural shape -- a large monorepo needs more session aggregate; a tight refresh wants a smaller ceiling; a specific specialist consistently over- or under-runs the default -- the canonical tuning surface is /revise-token-budget. The skill lists current budgets, accepts a workflow + agent + value to revise (or a workflow-wide change), persists to both usage.yaml and MEMORY.md, and writes an audit-trail comment. Per-agent overrides (budgets.<workflow>.agent_overrides.<agent>.per_agent) get honored at dispatch time -- the SKILL.md files resolve via budget-discipline.md's "Dispatch-time resolution" rule.

For polyrepo installs, the session-aggregate budget is computed additively as base + (N - 1) * per_sub_repo_increment. The increment comes from the same defaults table; /revise-token-budget lets you tune either the base or the increment. Default increment is 300K for /strap-in and 200K for /strap-refresh.

Reconnecting hosts

When work-tracking or source-control needs change (a Jira instance moves, a new auth token rotates in, a host changes its API shape, the team migrates from one tool to another):

1. Re-invoke /connect-devops-project (or /connect-code-repo). The pre-flight surfaces the existing profile and offers keep / reconnect / switch.
2. reconnect re-probes the same host to refresh capabilities (useful when the host changed its API surface).
3. switch re-runs the five-step discovery against a different host entirely.

Connection profiles persist env-var REFERENCES only -- credential values never enter any tracked file. To rotate a credential, update the env var in .claude/settings.local.json (or system env, or CI env); the profile reads the reference at runtime.

Choosing a work-item hierarchy

Where a new Requirement, Spec or Feature sits in your backlog is a profile decision, made once at /connect-devops-project Step 5c and recorded in mapping.hierarchy and mapping.default_parents:

• Nested spine -- Requirement -> Spec -> Feature are Parent/Child; default_parents.spec and .feature hold the literal upstream. Right for a process with one backlog level per STRAP stage. Recommended only when the probe shows that shape.
• Epic buckets -- container Epics per type; default_parents.<type> holds an Epic id. The default everywhere else.
• Flat -- explicit nulls; tags, area paths and queries organise the backlog.

Whichever model, /quick output that skips Requirement and Spec, Bugs with no generating Feature, and your own untagged items each need a container; Step 5c offers to create three Epics for them (default_parents.quick, .bug, .non_strap) and recommends doing so, because Epics are invisible to the metrics engine and to /dora-reconcile -- a container never ages, never trips a structure warning, never inherits an AI tag. Changing the model later applies to items created afterwards only. To re-decide, re-run /connect-devops-project with reconnect. Contract: .claude/strap/contexts/work-item-hierarchy.md.

Adding your own agents, skills, and rules

The canonical roster of 15 agents and the package skill catalog are the default set STRAP ships with -- not a wall. Adopters are encouraged to add their own agents, skills, and rules. The persistence stack is precisely the integration point that lets custom additions become first-class participants in the STRAP pipeline.

Adopter-authored skills

Two flavors, both supported:

Standalone skills the CPO invokes directly (/<your-skill> <args>). Drop .claude/skills/<your-skill>/SKILL.md with the standard frontmatter (name, description, allowed-tools). The dev-lead reads the skill catalog on every session; no further wiring is needed. Use operation_templates.<op> from the connection profile for host work, and project-profile.md's Domains for specialist dispatch -- the same patterns the STRAP skills follow.

Pipeline-integrated skills that should run as part of an existing workflow (e.g., "always run /our-compliance-scan after /execute-sprint"). Two integration paths:

1. Per-agent rules curation. Direct the dev-lead to add a rules entry under .claude/strap/rules/agents/dev-lead.md describing when to invoke the new skill ("after /execute-sprint prepares the PR, recommend /our-compliance-scan"). The dev-lead will surface it conversationally at the right moment.
2. Claude Code harness hook in settings.json. Fires the skill automatically on a tool event. This is a harness-level mechanism (not STRAP-specific) and bypasses the dev-lead's conversational surface entirely. Use when truly hands-off automation is wanted.

Adopter-authored agents

Adding a new agent and wiring it into the pipeline is a three-step ceremony:

1. Create the agent role contract. Drop <custom-agent>.md at .claude/agents/agent-{ops,devs}/<name>.md with the standard frontmatter (name, description, model, tools, color). Follow the same role-contract structure as the canonical 15 (Identity / Operating context / Responsibilities / Dispatch contract / Boundaries).
2. Seed the persistence-stack files. Create .claude/strap/rules/agents/<custom-agent>.md and .claude/strap/memory/agents/<custom-agent>.md with starter content (or empty stubs the dev-lead curates over time).
3. Wire into the pipeline via project-profile.md. Ask the dev-lead to add the new agent to the Specialists field of the relevant domain entry under the Domains section. CPO directs; dev-lead applies the edit under the single-writer rule.

Example: a compliance-reviewer that runs alongside backend-engineer on every API surface. Add compliance-reviewer.md to agent-devs/, seed its rules + memory, and tell the dev-lead "add compliance-reviewer to the api domain's Specialists list." From that moment, every pipeline skill that reads active-domain specialists (/decompose-feature, /execute-sprint, /fix-bugs, /refine-pr, /test-parallel) routes work through the custom agent like any canonical one.

Cross-cutting agents (security-scanning, compliance, project-specific governance) fit naturally as additional Specialists on existing canonical domains. Entirely new logical domains beyond the canonical six (client-ui, api, core, data, infrastructure, integrations) are a heavier lift -- most pipeline skills handle them fine because they read project-profile.md directly, but /decompose-feature's Spec-section-to-domain mapping logic was authored around the six and may need a small skill update for a Spec section that targets a brand-new domain. The easier path is to extend existing domains with custom Specialists.

What /strap-upgrade protects

Custom additions are always safe from package reconciliation:

The CPO cannot accidentally break the upgrade path by extending STRAP through these channels.

What is NOT supported

The constraint isn't "no new agents" -- it's "no in-place edits to package-shipped artifacts." Specifically:

• Editing a canonical agent's role contract file in place. The 15 STRAP-shipped role contracts at .claude/agents/agent-{ops,devs}/<canonical-name>.md are package-owned; in-place edits surface as conflict on every upgrade. The supported path is per-agent rules at .claude/strap/rules/agents/<canonical-name>.md -- those are adopter-owned and stack on top of the role contract at runtime.
• Editing a STRAP-shipped skill SKILL.md in place. Same pattern as canonical agents. The supported path is to add a new skill with a different name and direct the dev-lead to invoke yours instead.
• Editing team rules (agent-devs.md, agent-ops.md) in place. Same pattern. The supported path is per-agent rules -- they apply contextually to specific agents and stack on top of team rules.
• No template-rendering layer. Files are canonical. STRAP does not render agents, rules, or contexts from per-stack templates at install time; per-stack context lives in project-profile.md and the agents read it at runtime.
• No project.yaml. Project identity, stack, and conventions live in project-profile.md (curated narrative); host-specific operations live in the two connection profiles.
• No /onboard-* skill family. The lifecycle surface is /strap-in (first encounter) + /connect-* (host wire-up) + /strap-refresh (re-discovery) + /strap-upgrade (package reconciliation).

When to fork STRAP entirely

Forking is a last resort. The cost is permanent: you stop receiving STRAP upgrades and you take on the entire pipeline as your own product. Reasonable triggers:

• Your team's pipeline diverges so far from STRAP's two-team model that the orchestration logic itself no longer fits.
• A regulatory constraint requires you to vendor every dependency under your own version control with no upstream link.

If you fork: mirror the STRAP source repo into your own git remote, stop running /strap-upgrade, continue using the persistence-stack curation model (it's not coupled to upstream STRAP being a moving target). Forking is reversible only by manually merging fork changes against an upstream tag and re-adopting the upgrade flow.

Do not fork because of a single missing knob. File the gap as a STRAP feature request first.

Quick reference

When in doubt: ask the dev-lead. The dev-lead reads the persistence stack on every invocation and can tell you what's already curated, what's adopter-owned, and what the supported customization path is for the change you're contemplating.

References

• upgrade-guide.md -- the full /strap-upgrade walk-through, including the protected-paths list this guide alludes to.
• architecture.md -- the persistence-stack and connection-discovery models in design detail.
• strap-in.md -- the adopter-facing narrative that introduced the persistence-stack concept.
• ../contexts/brain-format.md -- the per-entry contract for rules and memory: claim types, statuses, the proposal queue, invalidation semantics.
• The seven-skill curation surface: /memory-show, /memory-add, /memory-refine, /rule-show, /rule-add, /rule-refine, /ratify.
• ../../skills/strap-refresh/SKILL.md -- the incremental re-discovery skill when project shape drifts.

Upgrade Guide

Operational walk-through of /strap-upgrade, the skill that reconciles a new STRAP package version against an existing installation. This guide is the CPO-facing narrative companion to ../../skills/strap-upgrade/SKILL.md -- the SKILL.md is the contract, this guide is how it feels to run.

It assumes STRAP is already installed in your project (.claude/.strap-version.json exists). In the default distribution mode nothing else is needed -- the skill fetches releases from the distribution endpoint recorded at install time. Source mode (--from-source <path>) exists for adopters who deliberately maintain a STRAP source clone.

When to upgrade

Three triggers:

1. A new release is published. Run /strap-upgrade -- it fetches the distribution manifest, resolves the target version from your channel (stable by default), and brings the changes into your project. (Source-mode installs: git pull in your source clone first.)
2. A release notes document calls out a change. Some upgrades introduce new skills, new agent role contracts, or schema extensions to the connection profiles that require explicit reconciliation.
3. You detect drift. The version in your project's .claude/.strap-version.json is older than the channel's current release (or, in source mode, than your source clone's HEAD).

Do NOT run /strap-upgrade for a fresh install. Use the installer (install.sh / install.ps1, fetched from the distribution endpoint), followed by /strap-in to curate the persistence stack.

One rule before anything else

Never re-run the installer to upgrade. Re-installing over an existing install is a reseed, not an upgrade: extraction replaces every package-managed file with fresh seeds -- including the seeded-then-curated per-agent rules, team rules, and memory your dev-lead has curated since install. /strap-upgrade exists precisely to preserve those. The installer enforces this: when it detects an existing install it refuses and points you here; the --force-reseed flag (-ForceReseed on Windows) exists only for the rare deliberate reseed, and it states exactly what it will overwrite before asking for confirmation.

The model in one paragraph

STRAP separates package-owned files (skills, agent role contracts, team rules, templates, design docs) from two flavors of protected files. Category A adopter-owned files (project-profile, connection profiles, continuations, settings, per-install state) are excluded from the diff entirely -- even if the package version differs, the install version wins. Category B seeded-then-curated files (per-agent rules + memory, dev-lead memory + index) ship as seeds: the adopter dev-lead inherits the STRAP-source-curated content on fresh install, then accumulates customizations on top. On upgrade, package-only adds DO land (a new operating learning at STRAP source or a new specialist's seed makes it to every adopter); a seed you have NOT touched that upstream improved fires a reconcile gate (you choose whether the improvements land); once you HAVE curated a file, conflicts are suppressed and the install version wins. For package-owned files, the skill uses a three-way merge against the previous-version tarball (or the source clone's git history in source mode) to distinguish clean upgrades (you haven't touched the file; safe to overwrite) from conflicts (you customized AND the package changed; CPO decides).

Two modes

Distribution mode (default). The skill reads the distributionUrl recorded in .claude/.strap-version.json at install time, fetches the manifest, resolves the target version from your channel, downloads the new and previously-installed tarballs into .claude/strap/state/upgrade-cache/ (SHA-256-verified against the manifest), and reconciles. No source clone required -- this is the path for every install made via the hosted installer.

Source mode (--from-source <path>). For adopters who maintain a STRAP source clone deliberately. The clone's git history (git show <previous-tag>:<path>) supplies the three-way-merge anchor. Auto-selected when the install was made with the installer's --from-source path (the version manifest records distributionUrl: null).

What happens during an upgrade

1. Resolve mode + source (distribution manifest, or source clone in source mode)
2. Compare versions
3. Diff the trees (with adopter-owned exclusions applied)
4. Present the plan + approval gates (Category B reconcile prompt when candidates exist, then the main gate)
5. Apply (per chosen strategy)
6. Update .claude/.strap-version.json
7. Run version-specific schema migrations (when the release carries any)
8. Post-upgrade recommendations
9. Report

The skill meets you at the approval gates between plan and apply: a batched Category B reconcile prompt when candidates exist (see the Category B section below), then the main strategy gate. Everything else flows from the inputs the skill resolved.

A structured upgrade report lands at .claude/strap/state/upgrade-reports/<ISO-timestamp>.md so any upgrade can be audited later.

The protected-paths list

Protected paths fall into two categories with different upgrade rules. Both categories preserve adopter customizations; they differ only on package-only adds.

Category A -- adopter-owned (NEVER touched, even adds)

These paths represent state owned entirely by the adopter install or by the installer. Excluded from the diff entirely; even package-only adds are NOT applied. The installer (not /strap-upgrade) writes the per-install copy where applicable:

• .claude/.strap-version.json -- updated by the skill itself at the end; not subject to diff.
• .claude/settings.json and .claude/settings.local.json -- harness permissions + env.
• .claude/strap/contexts/project-profile.md -- the curated record of THIS project (dev-lead-curated during /strap-in); installer copies a scaffold from .claude/strap/templates/project-profile.scaffold.md once at first install.
• .claude/strap/contexts/continuations/ -- session-state runbooks.
• .claude/strap/state/ -- connection profiles, the transition ledger, close-ceremony reports, usage tracking, and any per-install state. /strap-upgrade never touches state/. On a polyrepo umbrella state/ carries the fact + config side of the shared brain (the curated-opinion side -- memory, rules, the project profile -- is the Category B seeded-then-curated set below); all of it syncs via the state repo established at /connect-code-repo, from the installer-delivered package, so an upgrade and a brain-sync never collide over state/.
• .claude/strap/work/ -- when Local (strap-agile) is the work-tracking host, the adopter's work items.
• .claude/strap/mockups/ -- when the default mockup-path fallback is in use, this carries the adopter's designer-authored mockup files (keyed by Spec id). When project-profile.md's client-ui domain declares Mockup paths pointing at an out-of-tree location (e.g., an existing Nx workspace), the override is used instead and the default directory may not exist.
• .claude/strap/investigations/ -- where /quick --investigation writes specialist investigation reports (keyed by Task id). Same protection rationale as .claude/strap/mockups/.
• .claude/strap/project-docs/ -- where tech-writer writes the human-facing project-orientation documents (PROJECT.md, ARCHITECTURE.md, STACK.md) at /strap-in closing phase and refreshes them surgically at /strap-refresh. When project-profile.md declares a top-level Project docs paths field pointing elsewhere (e.g., docs/project/), the override is used and this default directory may not exist; the protection here covers the default fallback path.

Category B -- seeded-then-curated (package-only adds APPLIED; reconcile gate on untouched-seed improvements; install-wins on conflict)

These paths ship from STRAP source as scaffolds / seeds. The adopter dev-lead curates against them through /strap-in and ongoing operations. On upgrade:

• package-only adds APPLIED -- a new file at STRAP source lands at the adopter install. Examples: a new universal operating learning added to dev-lead memory in a later STRAP version; a brand-new specialist's seed memory/rules accompanying a newly-added role contract.
• package-modified clean (your copy is still byte-equal to the original seed AND upstream improved the file) -- RECONCILE GATE. Candidates surface in a batched AskUserQuestion BEFORE the main approval gate, split by subtype: rules-doctrine (rules/agents/*.md) and memory-tradecraft (the memory files) both recommend Apply all upstream improvements -- byte-equality to the seed proves the file carries no learning of yours, so nothing is lost and upstream seed corrections land. (On a polyrepo umbrella, byte-equality speaks only for your install -- a teammate may have curated the same file in the state repo; /strap-sync's union merge preserves their entries alongside the applied seed, which is why the first mover upgrades before syncing.) Declining is permanent in effect: a kept older seed classifies as conflict (install-wins) at every future upgrade. A per-file review walk is always available. In two-way merge mode (no previous-version anchor) the reconcile gate is disabled and these fold into conflict handling.
• conflict (you curated the seed AND the package changed) -- SKIPPED. Adopter customization preserved; surfaced in the plan as awareness; install wins; not subject to the conflict-strategy gate.

All classifications compare EOL-normalized content: a file that differs from the package only by line endings (common on Windows installs) is treated as unchanged and kept as-is, listed in the plan as eol-only, kept -- it never surfaces as a conflict or prompts a decision.

Category B paths:

• .claude/strap/memory/MEMORY.md -- the dev-lead's memory index. Ships with the STRAP-source-curated index entries (universal operating learnings); adopter dev-lead extends through /strap-in and ongoing curation.
• .claude/strap/memory/dev-lead/ -- the dev-lead's per-topic memory files. Ships with universal operating learnings (e.g., Bash CWD drift in polyrepo sessions, Windows shell selection); adopter dev-lead adds entries via /memory-refine or organic curation.
• .claude/strap/memory/agents/*.md -- per-agent memory. Package ships a seed/scaffold per active specialist role; once the dev-lead curates, the install version is authoritative for modify/conflict cases.
• .claude/strap/rules/agents/*.md -- per-agent rules. Same seed-then-curate pattern as per-agent memory.

The list mirrors the persistence-stack ownership. Anything the single-writer ownership model says is adopter-owned ends up in Category A or B.

The diff classification

For everything NOT in the protected-paths list, the skill walks the tree and classifies each path:

"Package's previous version" comes from the previously-installed tarball fetched into the upgrade cache (distribution mode) or from git show <previous-tag>:<path> against the source clone's git history (source mode -- the clone must be a real git checkout; flat copies don't carry the history). When neither can supply the anchor (e.g., the manifest no longer lists the installed version and no cached tarball matches), the skill degrades to a two-way comparison rather than failing.

The approval gate

When Category B reconcile candidates exist, the batched reconcile prompt fires first (see the Category B section above). The skill then presents a plan to the CPO with counts per classification, full path lists for each, the resolved target (manifest version + distribution URL in distribution mode; source clone HEAD in source mode), and the cross-cutting impact (which adopter-owned skills should be re-considered post-upgrade -- see "Post-upgrade recommendations" below).

The gate uses AskUserQuestion with five nominal options:

• Apply (skip conflicts) -- apply adds and clean-overwrites; conflicts stay unchanged and surface at the end for manual resolution.
• Apply with conflict strategy: take-package -- apply adds, clean-overwrites, AND overwrite every conflict with the package version. Adopter customization to those files is lost. Requires a second confirmation showing per-file consequences (e.g., "backend-engineer memory: 14 lines of curated tradecraft will be replaced with the package's seed scaffold"). Use sparingly.
• Apply with conflict strategy: keep-install -- apply adds and clean-overwrites; leave every conflict file alone with the install version. Adopter customization preserved; package updates to those files are NOT applied. The next upgrade will surface the same conflicts again because the divergence widens.
• Pause -- stop without changes. The skill writes a pending-state file at .claude/strap/state/upgrade-pending.md capturing the plan; resolve conflicts manually and re-invoke.
• Cancel -- abandon the upgrade. No state file, no changes.

The "Apply (skip conflicts)" path is the safest default: clean upgrades land, conflicts surface so you can address each one consciously.

Conflict resolution workflow

When you choose Apply (skip conflicts) or Pause, the skill ends with a list of conflict paths in hand. Three paths to resolve each:

Take the package version

Replace your install version with the package version. Appropriate when the local edit was a workaround for a bug the package now fixes, or when the local edit is no longer relevant, or when the package version is a clean improvement and your edit isn't load-bearing. Mechanism: extract the file from the new-version tarball in .claude/strap/state/upgrade-cache/ (distribution mode) or copy from the source clone (source mode).

Keep your install version

Decline the package change entirely. Appropriate when your local edit is load-bearing and you've consciously chosen to diverge. Mechanism: do nothing; the file is already at the install version. Note: the next upgrade will re-surface this conflict because the divergence keeps widening. Document the intentional divergence in your project's onboarding notes.

Three-way merge manually

For non-trivial conflicts, drive a real three-way merge in your editor. Three windows:

1. The package's previous version: extracted from the previous-version tarball in the upgrade cache (or git show <previous-tag>:<path> in source mode).
2. The package's new version: extracted from the new tarball (or the source clone's working tree in source mode).
3. Your install version: the file at the same path in your project.

Merge by hand. Replace the install version with the merged file. Re-run /strap-upgrade with Apply (skip conflicts) -- the file is now treated as unchanged (or package-modified clean if you adopted the package side).

The skill does NOT invent a merged file. Conflict resolution is the CPO's call; the skill makes the data available.

Post-upgrade recommendations

When the upgrade introduced certain kinds of change, the skill recommends follow-up actions. These are advisory; the CPO decides whether to run them.

The skill flags which of these apply in the upgrade report so you can decide which follow-ups to run.

Upgrading a polyrepo umbrella: one developer upgrades, everyone else pulls

On a synced umbrella the brain is shared, so an upgrade's brain delta -- new seed entries, corrected rules, brain-side migrations -- must be applied once and published, not applied by every developer. Two developers who both run /strap-upgrade produce two divergent deltas that conflict on curated files; that happened in the field on the 2.11.1 to 2.12.0 step. Since v2.13 the tracked sync marker carries brain_version, and /strap-upgrade reads it from the state remote before doing anything:

1. Everyone runs /strap-sync first, so the local brain is current and clean.
2. One developer runs /strap-upgrade. The skill sees the remote brain_version is older than the target, runs the full upgrade as the first mover, stamps the marker, and tells them to /strap-sync immediately. That state PR carries the marker and is the lock.
3. Once that PR merges, everyone else runs /strap-sync (the brain arrives by pull) and then /strap-upgrade, which sees the remote brain_version already equals the target and runs in package-only mode: skills, agents, tools and per-machine files update; nothing brain-side is re-applied; no state PR results.

Running step 3 before the first mover's PR has merged makes a second first mover -- the window the doctrine closes by naming one upgrader and publishing promptly. An umbrella established before v2.13 has no brain_version yet; the first upgrade to v2.13 or later stamps it.

Major-version refusal

The skill refuses to advance across STRAP major-version bumps automatically. Major bumps may carry breaking schema changes the skill is not authorized to apply without explicit CPO acknowledgement of the release notes.

When the package is a major version ahead:

1. The skill reports the major bump and stops without applying anything.
2. Read the release notes for that major.
3. The migration may require: re-curating the project profile, re-running /connect-* skills against schema changes, addressing connection-profile-shape changes manually.
4. After the migration steps land, re-invoke /strap-upgrade -- now the version delta is within the major and the skill proceeds normally.

The major-version refusal is the only place STRAP says "no, you do this part by hand." The trade-off is reversibility: a major-bump auto-apply that goes wrong is hard to back out of; the manual checkpoint catches it.

Recovery from a failed upgrade

/strap-upgrade is not transactional across the filesystem. If a write fails mid-apply you may end up with a partial upgrade -- some files at the new version, some still at the old. The skill names what landed in the report; the rest is recovery.

The simple recovery: git

Your project is a git repository. STRAP artifacts under .claude/ are version-controlled. The simple recovery:

git status                   # see what landed
git diff                     # see the partial upgrade
git checkout -- .claude/     # discard the partial upgrade

Then fix the underlying cause (permissions, disk space, broken source clone) and re-run /strap-upgrade from a clean state. The skill is idempotent at the version level -- re-running from a clean state produces the same result.

The harder recovery: partial commits

If you committed the partial upgrade before discovering the failure, git reset --hard <pre-upgrade-commit> is the recovery -- but git reset --hard is destructive. Use it only when you can re-derive any work-in-progress and only after confirming the pre-upgrade commit is what you actually want. The upgrade report under .claude/strap/state/upgrade-reports/ is your source-of-truth for what changed.

Preventing the failure mode

The most common cause is filesystem permissions on a path under .claude/. To prevent: run /strap-upgrade from a working tree where you have write access to every path under .claude/. STRAP does not modify files outside .claude/ and the install's .strap-version.json -- that surface is the only one that needs to be writable.

When STRAP-on-STRAP development is detected

If the project you're running /strap-upgrade in IS the STRAP source repo itself (you're working on STRAP, not consuming it), the skill refuses cleanly. You're operating ON the package, not consuming it -- the skill's reconciliation logic doesn't apply to its own source.

Upgrading to v2.14 (from v2.13.0)

The v2.14 line adds the work-item hierarchy model. Nothing in your profile changes shape by itself, and there is no Phase 7 migration: the new profile keys are written by /connect-devops-project, not by the upgrade.

What changes at your install

• New contract contexts/work-item-hierarchy.md; new schema keys mapping.hierarchy, mapping.required_fields, mapping.environment_values, mapping.required_field_defaults, link_types.child_parent, default_parents.quick and default_parents.non_strap. Your existing default_parents values keep their meaning; upstream is now understood.
• The create templates carry the parent. If your devops-connection.yaml was written before v2.14 its work_item_create has no {{parent_relation}} (Azure) or {{parent_field}} (Jira); the skills notice, add the parent with work_item_link_add after create, and say so. Copy the fragment from the connection template for your host into your profile to get the parent on create.
• New read-only probe operations in the Azure template (backlog_configuration_probe, process_id_probe, process_rules_probe). Copy them into your profile before re-running the connect skill, or the hierarchy prompt will run without probe evidence.

Recommended post-upgrade actions

1. Re-run /connect-devops-project with reconnect to decide the hierarchy model, create or name the three containers, and capture the process rules your host enforces. Until then the skills behave exactly as on 2.13.
2. If you had hand-written an upstream rule for the dev-lead, expect the deletion-manifest walk to queue an EXPIRE proposal for it (stage_parent, TF401320); ratify it -- the skills resolve upstream natively now.
3. Set dates on your iterations if the connect hand-off names any as undated.

Upgrading to v2.13 (from v2.12.0)

The v2.13 line hardens the polyrepo umbrella and the install path. Every change came from three live 2.12.0 installs re-pointed between host projects in September 2026. Nothing about your project, profile, or connection profiles changes shape.

What changes at your install

• Migration 7.xiv lays down .gitattributes with merge=union under state/transition-ledger/ and state/close-ceremonies/. Additive and content-neutral; state/ is adopter-owned, so the migration -- not the package diff -- is how the two files arrive. Count-verified 2/2 with git check-attr.
• Ledger shards gain a developer handle in their name (<YYYYMM>-<slug>-<handle>-<shortid>.jsonl). Your existing shards are left exactly as they are and are still read; the next emit simply starts a correctly named shard. No action.
• The sync marker gains brain_version (polyrepo umbrellas). It is stamped by the first /strap-upgrade to v2.13 on the umbrella and published by that developer's /strap-sync. Read Upgrading a polyrepo umbrella above before anyone runs the upgrade: from this release on, one developer upgrades and the rest pull.
• The installer reads its confirmations from the terminal (so curl ... | bash works) and has a joiner mode for umbrella clones. This matters for the next developer who joins, not for the upgrade itself.
• New universal operation pull_request_set_completion in the connection templates. Your existing code-connection.yaml does not have it; /strap-sync looks for it when it publishes a state PR and falls back to leaving completion manual when the operation is absent. Copy the operation from the template for your host into your profile to get rebase completion and fact-only auto-complete.

Recommended post-upgrade actions

1. Polyrepo umbrellas: apply the rebase-and-fast-forward-only merge policy to the state branch by hand, using the per-host recipe in /connect-code-repo 7.8. Re-running the connect skill on an already-established umbrella performs only the per-developer halves, so the policy does not reapply itself. Until it is applied, completing a state PR with squash will replay the publisher's commits into union-merged memory on their next pull.
2. Polyrepo umbrellas: copy pull_request_set_completion from the connection template for your host into state/code-connection.yaml (it syncs to the team through the state repo).
3. Everyone: the rg rule. Agents now carry a rule to always pass a path to rg. If you curated your own shell rules, check they do not contradict it.

Upgrading to v2.12 (from v2.11.x, v2.10 or v2.9.x)

The v2.12 line re-bases STRAP's parallel-dispatch protocol on a changed Claude Code contract. Nothing about your project, profile, or connection profiles changes, and this release introduces no schema migration -- Phase 7 is a silent no-op on a v2.11.x hop.

Read this before you upgrade

Do not run /team-cleanup on your current install. In v2.11.x and earlier its recovery path ends in a filesystem wipe of ~/.claude/teams/ and ~/.claude/tasks/. That was survivable when a team only existed because something created one. It is not survivable now: current Claude Code gives every session a team directory at startup, so that wipe deletes the live coordination state of every other Claude Code session you have open -- in any repo, not just this one -- along with the task lists that resumed sessions restore from. The skill is rewritten in this release to stop teammates by name and never remove a directory without naming it to you first. Until you upgrade, recover wedged agents by restarting the session instead.

What changes at your install

• Parallel dispatch is rewritten across every skill that fans out. Claude Code removed the TeamCreate and TeamDelete tools in v2.1.178: a session now has exactly one implicit team, and a specialist joins it by being given a name. So there is nothing to create and nothing to delete -- teammates are stopped individually, and the team is cleaned up when your session exits. /execute-sprint, /decompose-feature, /fix-bugs, /refine-pr, /quick, /strap-in, /strap-refresh, /test-parallel and /execute-sprint-full-auto all carry the new protocol. Full Auto in particular listed a now-removed tool among its hard requirements, so on a current Claude Code it would refuse to start.
• Per-sub-repo and per-Feature team clusters are gone, because a session cannot hold more than one team. On a polyrepo umbrella each specialist is now scoped by the absolute paths in its brief instead of by an inherited working directory, which is strictly more robust -- and it means a whole wave dispatches in one batch rather than one sub-repo at a time.
• Two claims your brain may repeat are now refuted, and the EXPIRE walk will surface them if your curated rules or memory carry either. First, that specialist reports persist to a team inbox file to be read off disk -- they do not; messages arrive directly and that file sits empty, so reading it and finding nothing would have you report delivered work as lost. Second, that the onboarding read-only palette makes your code structurally unmodifiable during discovery -- it never did, because Bash can write. Onboarding now takes a git status reading before and after the discovery fan-out and compares them, so a breach is detected rather than assumed impossible.
• Your budget file is split, so routine runs stop appearing in your pull requests. usage.yaml carried two things with opposite lifecycles: the ceilings you set, and the token counters for whichever run happened last. Because the whole file was tracked, every skill invocation put an unrelated hunk in your next PR and concurrent runs produced merge conflicts on values nobody had chosen. Migration 7.xiii moves session: and agents: to usage-runtime.yaml and ignores that file; budgets: and any agent_overrides: stay exactly where they are and stay tracked. Counter values are carried across verbatim rather than reset -- resetting them would re-grant a full budget to every specialist mid-checkpoint. On a polyrepo umbrella the state repo needs no allow-list change: it re-includes usage.yaml by exact name, so the new file is already excluded. The one thing to know: the runtime file is machine-local, so resuming a 60% checkpoint on a different machine now restarts the per-agent counters. That over-grants budget rather than cutting a run short, and the session-aggregate ceiling still binds.
• Slash commands take a single slash again. Every skill shipped with a leading slash inside its frontmatter display name, so the skill menu showed //strap-in and anyone following the menu typed the doubled form. The command itself was always derived from the skill's directory name -- which is why the single-slash form in every doc was correct throughout -- but the label contradicted it on all 42 skills at once. Labels are now bare, and a build gate asserts each one against its directory.
• The installer stops writing CLAUDE_CODE_SPAWN_BACKEND. That variable is no longer part of the harness contract; display mode is the teammateMode setting, whose default works in every terminal. Your existing entry is left exactly as it is and is inert -- the upgrade does not touch settings.json, which is adopter-owned. You may delete the line at your leisure. The key that still matters, CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1, is unchanged, and the installer now verifies it survived the merge instead of checking the wrong key.

Coming from v2.10 or v2.9.x you also cross the v2.11 line: read that section below, because its migrations 7.xi and 7.xii apply on the direct hop. Coming from v2.11.x there are no migration crossings at all.

Recommended post-upgrade actions

1. Run /test-parallel. This is the one release where that smoke test earns its keep: it confirms a named dispatch actually produces a teammate on your Claude Code version, which is the assumption every parallel skill now rests on. It also catches the silent failure mode -- without CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 a named dispatch does not error, it quietly becomes an ordinary single-agent call, and you would not find out until reports stopped arriving mid-sprint.
2. Run /ratify to work through the EXPIRE proposals the walk queued against the two refuted claims above.
3. If you keep notes of your own about how STRAP dispatches agents, re-read them. Anything mentioning creating or deleting a team describes a mechanism that no longer exists.

Upgrading to v2.11 (from v2.9.x or v2.10)

The v2.11 line makes the persistence stack self-curating under human authority: agents and skills propose, the orchestrator ratifies, the dev-lead applies. Upgrading from v2.9.x crosses the v2.10 metrics changes too -- read the v2.10 section below as well; its migration 7.x (adoption denominator) and reconcile-gate guidance both still apply on a direct 2.9 -> 2.11 hop.

What changes at your install

• Seven curation skills arrive: /memory-show, /memory-add, /memory-refine, /rule-show, /rule-add, /rule-refine, /ratify. The add/refine skills are the only write paths to rules and memory; /ratify works the queue of proposals your specialists raise during dispatches.
• Migration 7.xi -- brain envelope. Your curated rules and memory files gain a YAML frontmatter envelope (brain: + agent:), structural only: no body line is added, removed, or reworded. Your curation is never overwritten; content corrections travel as proposals through the ratification queue. Re-running the migration against an already-migrated file is byte-identical.
• Migration 7.xii -- orphan retirement. The shipped seed memory/agents/dev-lead.md was never loaded by anything (the dev-lead's memory lives at memory/MEMORY.md + memory/dev-lead/); the migration retires it where the install still carries the untouched seed.
• The EXPIRE walk. The upgrade checks your memory against the release's deletion manifest -- the record of producers this release deleted or renamed -- and queues an EXPIRE proposal for every entry whose cited producer is gone. Nothing is auto-applied: you ratify each one via /ratify, and a mechanical hit is triage, not a verdict.
• The dev-lead loader. The installer writes a root CLAUDE.md stub once-when-absent, so every new session grounds as the STRAP dev-lead. An existing root CLAUDE.md is preserved untouched.

Recommended post-upgrade actions

1. Run /ratify after your first post-upgrade sprint to work through any EXPIRE proposals the walk queued.
2. Skim /rule-show and /memory-show with no argument -- the roster listing shows each file's entry counts and any undeclared entries your own curation may carry.

Upgrading to v2.10 (from v2.9.x)

The v2.10 line narrows the report to claims STRAP can prove from its own record. Expect fewer numbers, and expect some to refuse -- that is the release working, not failing. Read the What's New entry in the Welcome guide before running the upgrade, because the report you get afterwards is deliberately different from the one you have.

What ships across the line

• Three new headline surfaces: STRAP adoption, STRAP autonomy, and acceptance rework (rendered inside the autonomy block, never apart from it). Plus Feature Highlights, which now opens the report.
• The DORA-4 are removed -- Deployment Frequency, Lead Time for Changes, Change Failure Rate. A deployment has no author, so none could be scoped to STRAP-executed work, and CFR divided bugs raised in a window by deploys shipped in it. Your DevOps host computes all three from data it owns; read them there.
• Every per-person surface is removed, along with per-layer and per-target metrics, cluster cycle-time, and the PR cycle / size / weight blocks.
• Your threshold config keeps working. mttr_sample and lead_time_sample are honoured through aliases (bug_resolution_sample, cycle_time_sample). cfr_deploys is retired outright and is now inert -- there is no surviving metric to alias it to, and you can delete the line.
• deployment_targets: and the Layers section no longer affect the report. Both remain valid topology declarations; neither buys a metric today. Nothing breaks if you leave them.
• Your existing snapshots still render. Pre-v2.10 snapshots build under the new engine; surfaces they cannot supply refuse rather than erroring.

Recommended post-upgrade actions

1. Answer the adoption-denominator question when the upgrade asks it (migration 7.x). Adoption measures STRAP's attested delivery against your team's total delivery, and it needs you to say what "your team's total" means. If your project belongs to one team with no sibling areas, the upgrade probes that, records it, and does not ask. If the project is shared -- several teams, or areas outside this install's scope -- it shows you the sibling areas by name and asks you to choose. If you skip it, adoption renders a refusal rather than a number, permanently, until you declare it via /connect-devops-project. STRAP will not guess: a project-wide count sweeps in other teams' work, while reusing your own area path makes the ratio read near 100% by construction. Both are wrong in opposite directions, and neither would be visible in the output.
2. At the reconcile gate, choose "Apply upstream" for memory/agents/dora-analyst.md. This is the one file where the recommended default is wrong for this release. Per-agent memory is treated as your curated tradecraft, so the gate recommends keeping your copy. But if you have never edited that file, your copy still carries v2.9 tradecraft describing a report that no longer exists: it instructs the analyst to interpret per-developer breakdowns across PR Health, Quality, Pipeline Funnel and Skill Calibration (all removed), to "look for outliers: a developer whose cycle time is 3x the team median", and to read per-layer DORA-4 breakdowns from your Layers section. Keeping it does not merely leave stale notes -- it points the analyst at per-person analysis this release deliberately stopped producing, which it could then reconstruct from the raw snapshot. The upstream version corrects those statements. If you have curated that file the gate skips it, and you should re-read your own notes against this release's What's New.
3. Run a full sprint through the pipeline before judging the report. Adoption, autonomy and rework each carry a floor and refuse below it. A sprint with fewer than ~5 delivered value units, ~20 STRAP-executed transitions, or 80% ledger coverage will produce refusals rather than numbers -- correctly. Attribution additionally needs work executed on v2.10, because the per-agent field did not exist in earlier releases and no pre-upgrade event carries it.
4. Then /dora-collect + /dora-report.

What does NOT change

• The v2.2 lifecycle-metadata convention and the canonical 15-agent roster are unchanged.
• Your curated per-agent rules and team rules are untouched (install-wins on conflict, as always).
• Connection profiles, project-profile.md, and everything under state/ remain adopter-owned and are never overwritten.

Upgrading to v2.7.x (from v2.3 through v2.6)

The v2.7 line's theme is STRAP-generated instrumentation: metrics read STRAP's own signals instead of depending on humans populating host fields. Upgrades from any v2.3+ install reconcile cleanly through /strap-upgrade; nothing below requires manual migration.

What ships across the line

• Transition ledger -- an append-only, session-sharded record of every state transition STRAP drives. DORA reads ledger-first with host-field fallback and reports coverage as a data-quality signal. No setup; shards accumulate under .claude/strap/state/transition-ledger/ as you run the pipeline.
• Value-unit terminal model -- agentic units (Tasks, Stories) auto-run to Closed; value units (Features, Enhancements, Bugs) stop at Resolved for /close-ceremony. After upgrading, value units sitting at Resolved are your ceremony queue, not an error -- and closing them adds no throughput (value counts at Resolved).
• Umbrella shared brain (polyrepo only) -- /strap-sync syncs memory, rules, profile, and ledger across developers through a state repo established at /connect-code-repo. Inert on single-repo installs.
• One-shot execution -- /execute-sprint-full-auto takes a Resolved Spec to draft PRs without per-phase gates (v2.6).
• Per-layer Change Failure Rate (v2.7.1; removed in v2.10) -- CFR left the report entirely: its numerator counted bugs raised in the window and its denominator deploys shipped in it, two unrelated populations. /file-bugs and /quick still stamp the strap:layer:<slug> tag, so layer attribution data keeps accumulating, but no report section reads it.

Recommended post-upgrade actions

1. Polyrepo umbrellas that want the shared brain: re-run /connect-code-repo to establish the state repo.
2. Run /dora-collect + /dora-report after a sprint -- the report gains the ledger-coverage data-quality signal.

(A third action here used to ask you to declare area_paths and sub_repos so bugs would attribute to layers for per-layer CFR. That metric was removed in v2.10; the declaration is optional now and changes nothing you can see.)

What does NOT change

• The v2.2 lifecycle-metadata convention and the canonical 15-agent roster are unchanged.
• Existing tagged items continue to flow through DORA queries; pre-upgrade sprints render as before.

Upgrading from v2.2 to v2.3

v2.3 is the first official release to external adopters. v2.2 was an internal validation milestone (no release tag was cut). Most v2.3 changes are additive -- new skills, new specialist coverage, new optional pathways -- and /strap-upgrade reconciles them cleanly as package-only or package-modified clean. A few changes warrant explicit adopter awareness:

What ships new

• Polyrepo support. /strap-in's pre-flight now detects depth-1 sub-repos and offers a three-way CPO choice (polyrepo umbrella / per-sub-repo install / single-project at root). Existing single-project installs are unaffected -- the new code path only engages when N >= 2 sub-repos are detected at the install root OR the --polyrepo flag is passed explicitly. If you want to migrate an existing single-project install to polyrepo mode against an umbrella that has since grown sibling repos, run /strap-refresh and the existing-Sub-repos-section check applies (or --full to re-derive the persistence stack from scratch).
• html-render pipeline ships inside .claude/ at .claude/strap/tools/html-render/. In v2.2 the pipeline lived at infra/pipeline/scripts/html-render/, which is excluded from the install tarball -- the project-docs HTML companion never rendered at adopter installs as a result (only the three markdowns landed). v2.3 vendors the pipeline into the runtime tree so the HTML companion lands on every /strap-in and /strap-refresh. After upgrading, the next /strap-refresh (or a manual re-render via node .claude/strap/tools/html-render/render.js <config>) populates the HTML companion at your configured Project docs paths.
• frontend-engineer activation broadened. Section 5's activation signal list now covers desktop UI (WPF / WinForms / MAUI / WinUI / UWP / Xamarin / Avalonia / Borland C++ Builder / Qt / Apple platforms / Flutter Desktop / etc.) AND server-rendered patterns (Python widget libraries like Streamlit / Dash / Gradio and in-house/custom widget frameworks; Phoenix LiveView; Rails Hotwire; Laravel Livewire; Blazor Server; classic template engines like ERB / HAML / Jinja / Razor; vendored JS widget libraries like DHTMLX / ExtJS / jQuery UI). These new signals don't fire retroactively on existing installs: an existing single-repo install where frontend-engineer was previously dormant on a desktop project will stay dormant until /strap-refresh (or /strap-refresh --full) re-evaluates Section 5's activation criteria. After the refresh, the specialist activates and starts accumulating UI tradecraft naturally.
• /revise-token-budget is a new skill for tuning budgets after install. v2.2 had budgets in MEMORY.md + usage.yaml; v2.3 adds the explicit CPO-driven revision surface with audit trail. Per-agent budget overrides are now a first-class field (budgets.<workflow>.agent_overrides.<agent>.per_agent). Existing usage.yaml files don't need a structural update -- the field is optional and dispatches resolve per budget-discipline.md's dispatch-time resolution rule.
• /create-test-plan v2 rewrite. New SKILL.md following the /create-mockups pattern (interview + plan + scaffold + present). ux-test-engineer becomes the third closing-phase write-exception specialist (alongside designer and tech-writer).
• Enhancement is the 7th STRAP logical type. mapping.work_item_types.enhancement is a new field in devops-connection.yaml. Existing profiles missing the field are still functional; re-invoke /connect-devops-project in reconnect mode to add it. The strap:enhancement tag is also new on filed Enhancement work items.
• /strap-refresh frontend-engineer priors-override-signals exception. On refresh, when frontend-engineer's memory has substantive curated content from prior runs but current signals don't trigger activation, the dev-lead defaults to keeping the specialist active rather than marking dormant. UI signal patterns are heuristic; curated memory is more authoritative.

What does NOT change

• The protected-paths list (above) is unchanged. All adopter-owned paths stay protected. Your curated project-profile, per-agent rules, per-agent memory, continuations, connection profiles, work items, mockups, investigations, and project-docs remain untouched.
• v2.2 lifecycle-metadata convention (Authored By/At, Completed By/At, AI tag, strap:<logical-type> tag) is unchanged. v2.3 builds on it; existing tagged items continue to flow through DORA queries.
• The canonical 15-agent roster is unchanged. v2.3 broadens frontend-engineer's scope through role contract + activation-signal updates; the agent's name, model, and identity stay the same.

Recommended post-upgrade actions

After /strap-upgrade lands, in order:

1. Re-render project-docs HTML companion. Either run /strap-refresh (which produces the HTML automatically), or manually invoke node .claude/strap/tools/html-render/render.js <config> (build a config like the one /strap-in Section 9 builds in memory). One-time npm --prefix .claude/strap/tools/html-render install --silent --no-save resolves marked on first render.
2. /strap-refresh if your project has desktop UI or server-rendered UI surfaces that weren't picked up by v2.2's web-only frontend-engineer activation. The refresh recomputes activation against v2.3's expanded signal list. --full if you want a complete re-derivation against the new signal set.
3. /connect-devops-project reconnect to add the enhancement mapping if your existing devops-connection.yaml predates v2.3. Optional -- only needed if your team plans to file Enhancement work items against this connection.
4. /revise-token-budget if you want to tune any per-workflow budget or set per-agent overrides. Optional; v2.2 budget defaults continue to work as-is.

Polyrepo opt-in for existing single-project installs

If your existing v2.2 single-project install lives at an umbrella root that has since grown sibling sub-repos (or always had them, but v2.2 didn't model them), /strap-refresh --full re-derives the persistence stack from scratch -- the depth-1 detection runs, the three-way CPO choice surfaces, and you can opt into polyrepo mode if appropriate. The existing curated content (project-profile, per-agent memory) is read as priors during the full re-derive but is not assumed authoritative. Backup the install's .claude/ first if you want a clean rollback option.

Quick reference

References

• ../../skills/strap-upgrade/SKILL.md -- the skill definition this guide operationalizes (the contract).
• ../../skills/strap-refresh/SKILL.md -- the incremental re-discovery skill recommended after upgrades that introduce new specialists.
• ../../skills/memory-refine/SKILL.md -- per-agent memory curation, recommended after role-contract changes.
• ../../skills/connect-devops-project/SKILL.md and ../../skills/connect-code-repo/SKILL.md -- re-invoke in reconnect mode after schema changes.
• customization-guide.md -- which surfaces are adopter-owned (this guide's protected-paths list mirrors that ownership model).
• architecture.md -- the persistence-stack model that grounds the protected-paths list.