architecture-dev-handoff

What this skill does

# Architecture Dev Handoff Skill — Orchestrator

## When This Skill is Invoked

Manually activated when users request component handoff document generation. It is NOT automatically triggered.

**Activation Triggers:**
- "Generate handoff for [component name]"
- "Create development handoff"
- "Hand off [component] to development"
- "Generate implementation spec for [component]"
- "Create dev handoff for all components"
- "Generate handoff documents"
- "Create handoff docs"
- "Prepare components for development"
- `/skill architecture-dev-handoff`
- `/skill architecture-dev-handoff all`
- `/skill architecture-dev-handoff [component-name]`

**NOT Activated For:**
- General architecture documentation tasks (use `architecture-docs` skill)
- Compliance generation (use `architecture-compliance` skill)
- Component index maintenance (use `architecture-component-guardian` skill)
- Peer review (use `architecture-peer-review` skill)

---

## Architecture — Orchestrator + Sub-Agent

As of v3.7.0, this skill is an **orchestrator**. Per-component generation runs in isolated sub-agent contexts via `agents/generators/handoff-generator.md` (model: sonnet) and `agents/builders/handoff-context-builder.md` (model: sonnet, added in v3.13.0). The orchestrator stays in main context; sub-agents do the heavy per-component reads.

- **Main context budget**: ~80–120 KB per invocation, flat regardless of how many components are selected.
- **Sub-agent budget**: ~25–40 KB per spawn (per-component payload + handoff template + section-extraction guide + ranged slice of asset guide).
- **Parallelism**: sub-agents spawn in batches of N (default 4, configurable via `--parallelism N`, capped at 8), one message per batch. Default raised from 2 in v3.13.0 — sub-agents are read-only on independent payloads, so 4-way fan-out cuts wall-clock by ~50% on 8-component runs without extra rate-limit risk on standard tiers.

Why this matters: previous versions re-read 7 shared architecture files plus the full `adr/` directory once per component. For a 10-component run that was ~750–2,750 KB of redundant reads. The orchestrator now reads them **exactly once** and slices per component into payload files that sub-agents consume.

See `PAYLOAD_SCHEMA.md` for the orchestrator → sub-agent contract.

---

## Purpose

This skill generates **Component Development Handoff** documents — one per component — that give development teams everything needed to implement a component without reading the full ARCHITECTURE.md suite.

**Scope:** C4 Level 2 (Container) components only. C4 Level 1 (System) descriptors are excluded — they describe system boundaries, not implementable units.

**Output location:** `handoffs/` directory at the project root

**Per-component output** (all names use **lowercase kebab-case** — no spaces, no uppercase, no underscores):
- `handoffs/NN-<component-name>-handoff.md` — 8-section audience-segmented handoff document (Dev / QA / Ops tracks; TEMPLATE_VERSION 2.0.0)
- `handoffs/assets/NN-<component-name>/` — scaffolded deliverable assets (OpenAPI spec, DDL, Kubernetes manifests, etc.)
- `handoffs/README.md` — managed index updated after each generation

The `<component-name>` slug is derived from the component file name in `docs/components/` (e.g., `docs/components/03-payment-service.md` → `handoffs/03-payment-service-handoff.md`).

---

## Template Format Preservation Policy

**CRITICAL REQUIREMENT**: Generated handoff documents MUST preserve template format exactly.

**Strict Preservation Rules:**
1. ✅ **ONLY replace explicit `[PLACEHOLDER]` tokens** — text inside `[...]` brackets
2. ✅ **PRESERVE ALL other text exactly** — including formatting, headers, structure
3. ❌ **NEVER transform template content** — no custom prose restructuring, no reformatting
4. ✅ **GAP DETECTION** — if data is not found in architecture docs, write `[NOT DOCUMENTED]` and add entry to section D1 (Open Questions & Assumptions)
5. ❌ **NEVER invent** values not stated in the architecture documentation

These rules apply to both the orchestrator (payload construction) and the sub-agent (template filling).

---

## Strict Source Traceability Policy

All handoff documents must trace data back to architecture docs.

1. ✅ **ONLY extract data** that explicitly exists in the architecture docs
2. ✅ **CITE source files** (e.g., `docs/components/01-api-gateway.md`, `docs/07-security-architecture.md`)
3. ✅ **NEVER infer or guess** values not stated in the docs
4. ❌ **NO INFERENCE** — even if industry standards suggest a value
5. ✅ When data is missing: write `[NOT DOCUMENTED — add to docs/NN-file.md]` and record in section D1

---

## Documentation Fidelity Policy

**CRITICAL REQUIREMENT**: Every generated handoff document and asset file MUST be an exact representation of what is specified in the architecture documentation. No more, no less.

**Rules:**
1. ✅ **EXACT MATCH** — every value in a generated handoff or asset (endpoint, field, schema, resource limit, env var, port, path, version, etc.) must come verbatim from the architecture docs
2. ❌ **NO DEFAULTS** — do not fill in default/fallback values in either handoff documents or asset files. If the value is not documented, use `[NOT DOCUMENTED — add to <source-file>]` in handoff sections or `# TODO: [NOT DOCUMENTED]` in asset files
3. ❌ **NO EXTRA FIELDS** — do not add fields, endpoints, schemas, columns, or resources beyond what is explicitly documented
4. ❌ **NO OMISSIONS** — every documented value relevant to the section or asset type MUST appear in the generated output
5. ✅ **COMPLETENESS CHECK** — after generating each handoff section and asset, verify it against the source documentation: every documented item has a corresponding entry, and every entry traces back to a documented item

---

## Orchestration Workflow

### Step 0 — Resolve Plugin Directory

Before any workflow, resolve the absolute path to the plugin installation so sub-agents can read the handoff template, section-extraction guide, asset-generation guide, and asset index.

**Step 0a — Glob (dev/local mode)**:

Glob for: `**/{sa-skills,solutions-architect-skills}/skills/architecture-dev-handoff/SKILL.md`

The brace expansion matches both marketplace installs (`sa-skills/` in `~/.claude/plugins/cache/...`) and local dev clones (historical repo folder `solutions-architect-skills/`). If found, strip `/skills/architecture-dev-handoff/SKILL.md` from the result to get `plugin_dir`.

**Step 0b — Marketplace fallback**:

If Glob returns nothing, set:
```
plugin_dir = ~/.claude/plugins/marketplaces/shadowx4fox-solution-architect-marketplace
```

**Step 0c — (removed in v3.13.0)**

Earlier versions mirrored four reference files (`HANDOFF_TEMPLATE.md`, `SECTION_EXTRACTION_GUIDE.md`, `ASSET_GENERATION_GUIDE.md`, `assets/_index.md`) to `/tmp/handoff-plugin-refs/` so sub-agents could Read them despite permission scoping. As of v3.13.0 those references are bundled directly into `agents/generators/handoff-generator.md` (sub-agent system prompt). Sub-agents no longer Read any plugin file at runtime, so the staging fallback is dead overhead and has been removed.

`plugin_dir` is still resolved in Steps 0a/0b — the orchestrator uses it to invoke `bun [plugin_dir]/skills/architecture-dev-handoff/utils/{prepare-payload-dir,manifest}.ts`. If a bun helper invocation fails with a permission error, check that `Bash(bun *)` is granted in project settings.

### Phase 1: Initialization

**Step 1.0: Parse orchestrator flags**

Inspect the user's invocation for flags. Default values apply when a flag is absent.

| Flag | Default | Validation | Purpose |
|------|---------|------------|---------|
| `--parallelism N` | `4` | integer 1–8; on out-of-range value, warn (`⚠ --parallelism N out of range; clamping to <1\|8>`) and clamp | Stage 5A batch size (handoff-document fan-out) |
| `--asset-parallelism N` | `4` | integer 1–8; on out-of-range value, warn (`⚠ --asset-parallelism N out of range; clamping to <1\|8>`) and clamp | Stage 5B