tech-lead-stack 1.0.1

package/.ai/skills/design-system-review.md

@@ -0,0 +1,308 @@
+---
+name: design-system-review
+description: >
+  AI-augmented design review with a strict 2-iteration guard, sequential memory
+  persistence, and KI creation. Enforces Shadcn/Radix token alignment, layout
+  fidelity against the Figma frame, and coordinates designer quality gates.
+cost: ~3400 tokens
+modes: [read-only, write, mcp]
+surface: public
+category: Design & UI
+phase: review
+kind: skill
+domain: eng
+ownership:
+  drive: human-ai
+  approve: human
+targets: [local, api, subscription]
+minModelClass: small
+consumes: [diff]
+emits: [review-report]
+requires: [accessibility-auditor, style-logic-exporter]
+suggests: [pr-automator, qa-handover-generator, visual-verifier]
+policies:
+  - user-sovereignty
+  - diagnosis-first
+  - four-pillars
+---
+
+# Design System Review (Iteration Guard)
+
+## Runtime modes
+
+Produces a verifiable design blueprint in read-only chat, and executes +
+verifies the audit phase in an IDE/MCP agent.
+
+> [!IMPORTANT] **Iteration Discipline**: This skill enforces a hard
+> **2-iteration limit**. Iteration 1 produces feedback. Iteration 2 verifies
+> fixes. If alignment is not reached by Iteration 2, the component is escalated
+> — NOT reviewed a 3rd time. Context must be persisted to a scratch file at the
+> start of every session so iteration count survives chat resets.
+>
+> [!IMPORTANT] **Credential Protocol**: If an external tool (Chromatic, Figma)
+> is required during the audit, PAUSE execution, prompt the user for
+> credentials, wait for their response, then resume. Never assume credentials
+> are available. Never hard-code or log credential values.
+>
+> **Methodology Alignment**: This skill strictly adheres to the four core
+> pillars: **G-Stack Ethos**, **MinimumCD**, **Agent Skills**, and **Modern Web
+> Guidance**.
+
+## 🎯 Verification Gates
+
+### Phase 0: Tech-Stack Discovery (MANDATORY)
+
+- **Skill Usage Enforcement (NON-NEGOTIABLE):**
+  - **FORBIDDEN:** Direct file access via `view_file` or `run_command` is
+    strictly prohibited without first calling the skill tool.
+  - **IDE / MCP-enabled Agent:** You MUST call the MCP `get_skills` tool (which
+    may be prefixed as `mcp_tech-lead-stack_get_skills` or
+    `tech-lead-stack_get_skills` depending on client prefixing).
+  - **Chat UI (/chat):** You MUST call the internal `get_skill` tool.
+
+- **Action:** Identify the project's UI foundation.
+- **Target Files:** Inspect `package.json`, `components.json` (Shadcn config),
+  `tailwind.config.*`, and `globals.css`.
+- **Confirm:** Which Shadcn/Radix primitives are installed? What Tailwind token
+  namespace is in use (`--color-*`, `--spacing-*`, etc.)?
+- **MANDATORY Guardrail:** Focus ONLY on UI/design configuration. Ignore
+  unrelated logic, auth, and infrastructure files. Avoid Goal Drift.
+
+### Phase 0.5: Session Memory Init (MANDATORY — runs before Phase 1)
+
+Before doing ANY analysis:
+
+1. **Check for existing session file:**
+   - Path pattern:
+     `scratch/design-review/<project-name>/session-<YYYY-MM-DD>.md`
+   - If a file for today exists, READ it to restore iteration count and
+     component state.
+   - If no file exists, CREATE it with this template:
+
+```markdown
+# Design Review Session
+
+- project: <project-name>
+- component: <component-being-reviewed>
+- started: <ISO timestamp>
+- iteration: 1
+- status: IN_PROGRESS
+- figma_url: (not provided)
+- chromatic_build: (not provided)
+
+## Iteration 1 — Findings
+
+(populate after audit)
+
+## Iteration 2 — Verification
+
+(populate after fix)
+
+## Decision
+
+(populate on completion)
+```
+
+1. **Report to user:** "Session file created/restored. Currently at Iteration
+   **N**. Resuming from: `<status>`."
+
+### Gate 1: Token Alignment
+
+- **Positive (Pass):** Colors, spacing, radius, and typography use the project's
+  defined Tailwind variables or CSS custom properties. No arbitrary values like
+  `text-[#3a3a3a]` or `p-[13px]`.
+- **Negative (Fail):** Hard-coded hex values, magic pixel values, or inline
+  styles that bypass the token system.
+- **Action on Fail:** List every violation with the file + line reference.
+  Propose the correct token replacement.
+
+### Gate 2: Shadcn/Radix Primitive Alignment
+
+- **Positive (Pass):** Component uses the appropriate `@gilly-ui` primitive
+  (Button, Dialog, Select, etc.) as its base. Radix accessibility attributes
+  (`aria-*`, `data-state`, keyboard handlers) are present.
+- **Negative (Fail):** Custom HTML elements used where a Shadcn primitive
+  exists; missing focus management or keyboard navigation.
+- **Action on Fail:** Identify the correct primitive and provide a migration
+  snippet.
+
+### Gate 3: Logic Consistency
+
+- **Positive (Pass):** Component follows Early Returns, no mixed UI/data logic,
+  Zod validation on inputs, no `any` types.
+- **Negative (Fail):** Nested conditionals instead of early returns, inline
+  fetch calls, missing error boundaries.
+
+### Gate 4: Layout Fidelity (MANDATORY for any UI-facing change — BLOCKING)
+
+This gate exists because token alignment and primitive alignment do NOT prove
+the built UI matches the design. A component can use every correct token and
+Shadcn primitive and still be the wrong width, the wrong proportions, or reflow
+its sub-elements incorrectly. Layout requirements stated in prose ("side by
+side", "wider", "stacked") are CONSEQUENCES of building to the frame, never the
+instruction. Build to the frame; the prose is a hint, the frame is the spec.
+
+- **Fetch the design source at plan and review time (NON-NEGOTIABLE):** Retrieve
+  the specific Figma node for this component via the Figma MCP `get_figma_data`
+  tool — the actual frame, not a prose summary or a Phase-0 recollection. The
+  Figma MCP `get_figma_data` fetch MUST happen when the plan/acceptance criteria
+  are produced, and the plan MUST embed the actual fetched measurements. A plan
+  that only PROMISES to fetch during execution, or that states goals like 'match
+  Figma constraints' without concrete numbers, FAILS this gate and MUST NOT be
+  approved. Follow the **Credential Protocol** in the header if the Figma MCP is
+  not yet authenticated.
+  - **Tool-name-robustness note:** The Figma fetch tool's base name is
+    `get_figma_data` (from the figma-developer-mcp server) but MAY be exposed
+    with a client prefix (e.g. `mcp_Figma_get_figma_data`). Use whichever name
+    is actually present in the tool list. If NO Figma fetch tool is available,
+    STOP and tell the human — do not proceed from memory or produce a plan
+    without fetched numbers.
+  - **Anti-deferral clause:** Deferring the fetch to execution is NOT
+    acceptable. 'The execution step will call get_figma_data' is not a
+    substitute for fetching now and recording the numbers. The frame is the
+    spec; the numbers are the acceptance criteria.
+  - **Required "Frame read" block:** This block must appear per screen/component
+    IN THE PLAN, listing the concrete values pulled from the fetched node, e.g.:
+    container width + max-width, column widths + gaps, key spacing/vertical
+    rhythm, button width, and any breakpoint-specific values. If these numbers
+    are absent, the plan is incomplete by definition.
+  - If no Figma node/URL is available for this component, do NOT silently pass.
+    Mark this gate `BLOCKED — no design source` and escalate per Gate 5 (Design
+    Debt); a UI change with no design source cannot be verified as matching the
+    design.
+- **Render the built result:** Capture the implemented component (delegate to
+  `visual-verifier` for the actual capture at the mandatory
+  Desktop/Tablet/Mobile resolutions). For interactive screens, exercise the
+  relevant states (default, focus, error, loading).
+- **Produce an itemised Layout Deviation Report** comparing built vs frame. Each
+  line is **MATCH** or **DEVIATION** with the specific difference:
+  - Container / card width and max-width at each breakpoint.
+  - Column widths and gaps for multi-column areas (e.g. side-by-side fields).
+  - Element placement and vertical rhythm (label → input → helper/error
+    spacing).
+  - Responsive reflow: how sub-elements (helper text, requirement lists, labels)
+    rearrange across breakpoints — a single list must not fragment across
+    columns unless the frame shows it that way.
+  - Button width, alignment, and inline-link placement.
+- **Positive (Pass):** Every line in the Layout Deviation Report is MATCH across
+  Desktop, Tablet, and Mobile.
+- **Negative (Fail):** Any DEVIATION line. A DEVIATION is a 🔴 **Critical**
+  finding — it BLOCKS completion. The component returns to the developer with
+  the report until it is all-MATCH, or a specific deviation is explicitly waived
+  by the Tech-Lead at a gate (record the waiver in the session file).
+- **Action on Fail:** List each DEVIATION with the frame's target value vs the
+  built value (e.g. "card max-width: frame 1100px, built ~720px"), and the
+  concrete fix. Paste the final all-MATCH report as the gate's evidence.
+
+> [!CAUTION] **Test-pass is not design-pass.** `check-types` and unit tests
+> passing say nothing about visual fidelity. A UI-facing change is NOT complete
+> until this gate's Layout Deviation Report is all-MATCH (or an explicit
+> Tech-Lead waiver is recorded). Never mark a UI slice complete on tests alone.
+
+### Gate 5: Storybook Figma Link Validation
+
+- **Action:** Check if the component has a Storybook story file
+  (`*.stories.tsx`). If yes, verify it has `addon-designs` parameters with a
+  Figma URL.
+- **If Figma URL is missing:**
+  - Ask: "Do you have a Figma frame URL for this component? (Paste it here or
+    press Enter to skip)"
+  - If provided: update the session file with `figma_url` and include it in
+    audit output.
+  - If skipped: flag as "Design Debt — No Figma link" in the session file.
+
+### Gate 6: Chromatic / Visual Regression (Optional, credentials required)
+
+- **Trigger:** Only runs if the user has connected a Chromatic build.
+- **Credential Protocol:**
+  1. Prompt: "To run Chromatic validation, I need your
+     `CHROMATIC_PROJECT_TOKEN`. Please paste it here (it will only be used for
+     this session and not stored)."
+  2. **PAUSE** — do not proceed until user responds.
+  3. On receipt: use the token to reference the build; report the build URL and
+     whether all stories passed visual review.
+  4. If user declines: mark Chromatic gate as "SKIPPED — manual review
+     required."
+
+---
+
+## 🔄 Iteration Management
+
+### Iteration 1 — Full Audit
+
+1. Run Gates 1–6 (in order). Gate 4 (Layout Fidelity) is BLOCKING for any
+   UI-facing change.
+2. Produce a **"Must Fix"** list sorted by severity:
+   - 🔴 **Critical** — Accessibility failure or token violation blocking release
+   - 🟡 **Recommended** — Code consistency and design alignment
+   - 🟢 **Advisory** — Nice-to-have improvements
+3. Update session file `Iteration 1 — Findings` section.
+4. Ask: "I've completed Iteration 1. Apply these fixes, then reply
+   `/design-system-review iterate` to trigger Iteration 2 verification."
+
+### Iteration 2 — Fix Verification
+
+1. Re-read session file to confirm we're at Iteration 2.
+2. Re-run only the **failed** gates from Iteration 1.
+3. Calculate alignment score: `(gates_passed / total_gates) * 100`.
+4. **Decision branch:**
+   - **Score ≥ 90%** → Mark as `READY_FOR_DESIGNER_GATE`:
+     - Update session file `status: READY_FOR_DESIGNER_GATE`
+     - Call `create_knowledge_item` with the decision summary (see KI schema
+       below)
+     - Notify: "✅ Component is ready for designer gate review."
+   - **Score < 90%** → Mark as `ESCALATED`:
+     - Update session file `status: ESCALATED`
+     - Create a `DESIGN_DEBT` entry in `docs/design-debt.md`
+     - Notify: "⚠️ 2 iterations reached without 90% alignment. Escalated to
+       manual designer review queue. A Design Debt record has been created."
+
+---
+
+## 📦 Knowledge Item Schema
+
+When a review reaches `READY_FOR_DESIGNER_GATE`, call `create_knowledge_item`
+with this structure:
+
+```json
+{
+  "slug": "design-decision-<component-name>-<YYYY-MM-DD>",
+  "summary": "One-line summary of what was approved or what deviation was accepted.",
+  "projectName": "<detected-project-name>",
+  "tags": ["design-system", "ui-review", "shadcn"],
+  "artifacts": [
+    {
+      "name": "decision-details.md",
+      "content": "## Component\n<component-name>\n\n## Decision\n<approved/deviated>\n\n## Rationale\n<why>\n\n## Figma URL\n<url or N/A>\n\n## Chromatic Build\n<url or SKIPPED>\n\n## Gates Passed\n<list>\n\n## Alignment Score\n<N>%"
+    }
+  ],
+  "references": ["<PR link if known>", "<Storybook story URL if known>"]
+}
+```
+
+---
+
+## 🔍 Critical Patterns to Detect
+
+- **Shadow DOM bypass:** Any component using `dangerouslySetInnerHTML` to inject
+  styles — flag as Critical.
+- **Hardcoded breakpoints:** `sm:`, `md:` used inconsistently with the project's
+  layout strategy — flag as Recommended.
+- **Missing `data-testid`:** UI components without test selectors make visual
+  testing brittle — flag as Advisory.
+
+## 🛠 Companion Skills
+
+- Run `style-logic-exporter` BEFORE this skill to extract the current token
+  state. Pass the output as context when starting the audit.
+- Run `accessibility-auditor` in parallel on the same component to catch WCAG
+  violations that are distinct from design token issues.
+
+## 📋 Outcome Actions
+
+- **`READY_FOR_DESIGNER_GATE`:** Proceed to designer approval handoff. Share
+  Chromatic build link and KI slug with the design team.
+- **`ESCALATED`:** Route to `docs/design-debt.md` and add to the Manual Review
+  queue. Schedule a sync with a designer.
+- **`IN_PROGRESS`:** Wait for the user to apply Iteration 1 fixes before calling
+  `/design-system-review iterate`.

package/.ai/skills/dev-team-local.md

@@ -0,0 +1,52 @@
+---
+name: dev-team-local
+description:
+  '[DEV-TEAM · LOCAL] Orchestrator for fully offline, single-lane execution.'
+phase: build
+kind: orchestrator
+domain: eng
+spans:
+  - intent
+  - specify
+  - plan
+  - build
+  - review
+targets:
+  - local
+minModelClass: small
+ownership:
+  drive: ai
+  approve: human
+cost: ~350 tokens
+modes: [read-only, write, mcp]
+surface: public
+category: Orchestrators
+policies:
+  - four-pillars
+---
+
+# Dev Team Local Orchestrator
+
+This is the offline analogue to the subscription-tier dev team orchestrators
+(sub-pro/sub-max). It coordinates the single-lane pipeline through the same
+phases (intent -> plan -> build -> review) but degrades execution to fit local
+environments:
+
+- **Single Lane**: Concurrency and worktrees are entirely disabled.
+- **Local Model Loop**: Uses the identical model for all generative and critical
+  steps (see `reflexion-loop-local`).
+- **Offline Strictness**: Relies on a wall-clock and token budget without
+  applying USD cost limits.
+
+Usage: The execution flows exactly like `dev-team-sub-pro`, utilizing local
+endpoints specified in `LOCAL_MODEL_ENDPOINT` and `LOCAL_MODEL_NAME`.
+
+## Code Modification Convention
+
+**REQUIREMENT:** When modifying files, you MUST use the `apply_patch` tool with
+minimal SEARCH/REPLACE blocks instead of rewriting whole files.
+
+- Never emit a full-file rewrite.
+- Never restate unchanged code.
+- **Rule:** Include only the lines that change plus minimal surrounding anchor
+  context.

package/.ai/skills/dev-team-orchestrator.md

@@ -0,0 +1,289 @@
+---
+name: dev-team-orchestrator
+description: >
+  [DEV-TEAM · FULL · MCP] The flagship orchestration skill: an agent-agnostic
+  "dev team" you manage as a technical product manager. Sizes the crew to the
+  task, runs multiple task lanes in parallel without collision, interviews the
+  human only at gates, and files friction defects automatically on its own repo.
+cost: ~2600 tokens
+modes: [read-only, write, mcp]
+surface: public
+category: Orchestrators
+kind: orchestrator
+domain: eng
+spans: [intent, specify, plan, build, maintain, review, deploy]
+ownership:
+  drive: human-ai
+  approve: human
+targets: [api, subscription]
+minModelClass: large
+requires: [design-system-review, reflexion-loop]
+suggests:
+  [
+    accessibility-auditor,
+    ask,
+    code-review-checklist,
+    dev-team-sub-max,
+    dev-team-sub-pro,
+    feature-design-assistant,
+    mission-architect,
+    planning-expert,
+    verification-auditor,
+    vertical-slice-decomposer,
+    visual-verifier,
+  ]
+policies:
+  - user-sovereignty
+  - diagnosis-first
+  - four-pillars
+---
+
+# Dev Team Orchestrator (The Agentic Crew)
+
+> Tier siblings: dev-team-orchestrator (API keys, dual-model) · dev-team-sub-max
+> ($100 tier) · dev-team-sub-pro ($20 tier). See the tier table in the README.
+>
+> [!NOTE] **Sibling subscription tiers (no API keys required):** For
+> subscription-only accounts, use `dev-team-sub-max` ($100/mo tier, max 2
+> parallel lanes) or `dev-team-sub-pro` ($20/mo tier, single-lane pair).
+
+## Runtime modes
+
+Produces a blueprint and hand-off in read-only chat; executes in an IDE/MCP
+agent.
+
+> [!IMPORTANT] **Anti-Micromanagement Litmus** Personas receive goals + gates,
+> never line-by-line instructions. The human appears only at gates. We advise;
+> the User Tech-Lead decides.
+
+<!-- -->
+
+> [!CAUTION] **RUNTIME MODE (DETERMINE FIRST — NON-NEGOTIABLE)**
+>
+> - **Read-only chat (`/chat`):** write/exec tools are forbidden; only
+>   `get_skill`, `list_skills`, `read_file` exist. Deliver a **verifiable
+>   blueprint + handoff**.
+> - **IDE / MCP-enabled Agent:** you have full write access and must use `rtk`
+>   (Run Tool Kit) to execute and verify changes.
+
+<!-- -->
+
+> [!IMPORTANT] **EXECUTION DISCIPLINE (IDE/MCP MODE)**
+>
+> - **Produce, don't deliberate:** never call a sequential-thinking/planning
+>   tool more than twice consecutively without emitting a concrete output. If
+>   unsure, emit the current phase's artifact.
+> - **No stall commands:** run no further search/terminal command between
+>   finishing a phase's inputs and emitting its artifact.
+> - **DIRECT EDITS ONLY:** never write generated regex/patch.js scripts that
+>   mutate source (they fail silently and leave no reviewable diff). Use native
+>   file edit tools.
+
+## Phase 0 — Discovery (MANDATORY)
+
+- **Skill acquisition (NON-NEGOTIABLE):** IDE/MCP agent MUST call `get_skills`
+  tool; Chat UI MUST call `get_skill`. Never read `.ai/skills/` via raw file
+  access.
+- **Discovery Budget:** Apply a small cap of scoped searches only. Every
+  grep/find MUST exclude `node_modules`, `.next`, `.nx`, `dist`, and `build`. No
+  unscoped recursive search. Discovery is COMPLETE once the stack, relevant
+  files, and named config flags are known. The FIRST output after discovery MUST
+  be the Phase 1 sizing scores, with no terminal command between discovery and
+  sizing.
+- **Stack ID:** Inspect manifest/config (`package.json`, `tsconfig.json`, etc.)
+  for framework + conventions.
+- **Mission Frame:** Formulate a one-sentence mission statement and a success
+  metric.
+- **Runtime-mode determination:** Confirm whether you are in a read-only chat or
+  an IDE/MCP agent capable of execution.
+
+## Phase 1 — Crew Sizing Gate
+
+Evaluate the task based on the five-signal 0–2 rubric to determine the crew
+size. **HARD RULES:** idle personas are never instantiated; the sizing decision
+and its scores MUST be printed before any work begins; a size may be revised at
+a gate but never silently.
+
+**Phase artifact:** The printed sizing scores (the first thing emitted after
+discovery).
+
+| Signal       | 0                | 1                      | 2                        |
+| ------------ | ---------------- | ---------------------- | ------------------------ |
+| Surface area | 1 file, 1 layer  | ≤5 files or 2 layers   | many files / cross-layer |
+| Novelty      | existing pattern | adjacent pattern       | new pattern/system       |
+| Risk         | cosmetic         | business logic         | auth/payments/data/infra |
+| Ambiguity    | spec is exact    | minor gaps             | open questions           |
+| Parallelism  | none             | 2 independent subtasks | 3+ independent subtasks  |
+
+Total score → size → crew preset:
+
+| Size | Score | Crew                                          | Parallel lanes | Loop hardening                       |
+| ---- | ----- | --------------------------------------------- | -------------- | ------------------------------------ |
+| XS   | 0–1   | Developer only                                | 1              | self-check + autoeval                |
+| S    | 2–3   | Developer + Reviewer                          | 1              | reviewer gate                        |
+| M    | 4–5   | Planner + Developer + Reviewer                | 1–2            | plan gate + review gate              |
+| L    | 6–8   | PM-analyst + Planner + Dev ×N + Reviewer + QA | 2–3            | reflexion-hardened plan recommended  |
+| XL   | 9–10  | mission-architect strategy + full L crew      | 3+             | `reflexion-loop` plan gate mandatory |
+
+## Phase 2 — Lane Ledger
+
+One row per task lane, tracking concurrent work.
+
+| lane-id | task | size | crew | branch+worktree | state-file | status | next-gate |
+| ------- | ---- | ---- | ---- | --------------- | ---------- | ------ | --------- |
+| ...     | ...  | ...  | ...  | ...             | ...        | ...    | ...       |
+
+- **Isolation:** One git worktree per lane (`rtk git worktree add ...`), single
+  writer per lane. Lane creation is NOT silent — when a worktree/branch is
+  created, print the worktree path and branch, and record them in the Ledger row
+  and lane state file immediately.
+- **Worktree Bootstrap (MANDATORY):** A fresh worktree does not inherit
+  `node_modules`, built workspace packages, `.env` files, or generated clients
+  (e.g. Prisma). Before any `check-types` or `test` in a new lane, you MUST
+  bootstrap it: install deps, copy required `.env` file(s) from the source
+  checkout, generate clients, and build dependent workspace packages. Only then
+  run `check-types`/`tests`.
+- **Persistence:** State file `.dev-team/lanes/<lane-id>.md` updated at every
+  gate.
+- **Anti-drift:** The Ledger is the source of truth. Reprint the Ledger after
+  every detour; lanes advance independently without cross-talk. Never silently
+  abandon a pending slice.
+
+**State File Template:**
+
+```md
+# Lane: <lane-id>
+
+- Task: <description>
+- Status: <status>
+- Next Gate: <gate>
+- Current Artifacts: <links/paths>
+```
+
+## Phase 3 — Persona Execution Protocol
+
+Each persona maps to a chained sequence of EXISTING skills. The orchestrator
+routes lanes by reading skill frontmatter (`modes:`, `surface:`) — a read-only
+lane may only invoke skills whose modes include read-only delivery.
+
+- **pm-analyst:** `feature-design-assistant`
+- **planner:** `planning-expert` or `vertical-slice-decomposer`
+- **developer:** Implement per plan
+- **reviewer:** `code-review-checklist` + `verification-auditor`
+- **qa:** `design-system-review` (authoritative layout/design gate) driving
+  `visual-verifier` (capture) + `accessibility-auditor` — MANDATORY for any
+  UI-facing slice, not optional
+
+**Reviewer Rules:** The Reviewer NEVER shares the developer's context. The
+Reviewer must ACT, not read: run the stated verification gates and paste hard
+evidence. **Loop Hardening:** For L/XL sizes, the plan gate SHOULD (L) or MUST
+(XL) be hardened via `rtk run reflexion-loop` before execution. Note that the
+reflexion loop is the stack's one declared non-agnostic feature (refer to
+`reflexion-loop.md` wording).
+
+**Visual Fidelity Gate (MANDATORY for any UI-facing slice — BLOCKING):** A UI
+slice does NOT close on `check-types` + passing tests; those prove the code
+compiles and behaves, not that it matches the design. For any UI-facing slice,
+the PLAN for that slice MUST already contain the fetched Figma measurements (a
+'Frame read' block with concrete numbers per screen). If the plan lacks fetched
+numbers, it is not ready for approval — return it for Figma fetching before any
+code is written. Deferring the fetch to execution is a defect. For any slice
+that changes rendered UI, the QA persona MUST, before the slice is marked
+complete:
+
+1. **Fetch the design source at implementation time** — the specific Figma node
+   for the slice via the Figma MCP `get_figma_data` tool (the actual frame, not
+   the Phase-0 summary). The frame's measurements are acceptance criteria:
+   container/card width, column widths, gaps, breakpoints, and sub-element
+   reflow.
+2. **Run `design-system-review`** on the changed component. Its **Gate 4 (Layout
+   Fidelity)** produces an itemised built-vs-frame Layout Deviation Report and
+   is BLOCKING; `visual-verifier` performs the capture at Desktop/Tablet/Mobile.
+3. **Any DEVIATION blocks the slice.** It returns to the developer with the
+   report until all-MATCH, or a specific deviation is explicitly waived by the
+   Tech-Lead at a gate (record the waiver). Paste the final all-MATCH Layout
+   Deviation Report as the slice's completion evidence, alongside the test
+   output.
+
+> [!CAUTION] Layout words in prose ("side by side", "wider", "stacked") are
+> CONSEQUENCES of building to the frame, never the instruction. Build to the
+> frame; the prose is a hint, the frame is the spec. Implementing the words
+> without matching the frame is a FAILED slice, not a complete one. Test-pass is
+> not design-pass.
+
+## Phase 4 — Tech-Lead Interview at Gates
+
+Questions for the human (the Tech-Lead) are batched at gate boundaries ONLY.
+Append them to `.dev-team/inbox.md` using the fenced yaml convention:
+
+```yaml answers:
+# Leave blank for the human to answer inline
+question_1: ''
+```
+
+**Gate Guardrails (HARD RULES):**
+
+- **PARK IS A HARD STOP:** After writing questions to `.dev-team/inbox.md`, the
+  lane MUST stop ALL commands (no searches, reads, edits, discovery) and yield
+  until the human fills answers and signals continue. Continuing to work after
+  posting questions is a defect. Parking is correct behaviour, not a stall, and
+  must not be worked around by guessing an answer.
+- **INBOX IS READ-ONLY TO THE AGENT ONCE POPULATED:** The agent may CREATE the
+  question block, but once the human saves answers it must read them in place
+  and MUST NOT rm/overwrite/rewrite `.dev-team/inbox.md` (read into memory if a
+  normalized copy is needed; never destroy or paraphrase the human's file). The
+  inbox is for QUESTIONS only; status/confirmations go to the Lane Ledger or
+  chat, never as inbox answer entries.
+- **NEVER SILENTLY BYPASS A GATE ON TOOL FAILURE:** If a gate tool (e.g.
+  `reflexion-loop`) fails or times out, do NOT auto-skip by writing a
+  "bypassing" note and continuing. Retry once; if it still fails, PARK and ask
+  the human whether to proceed un-hardened. For Risk-2+ tasks
+  (auth/payments/data/infra), proceeding un-hardened REQUIRES explicit human
+  approval.
+
+## Phase 5 — Friction Defect Protocol
+
+**Triggers:**
+
+- ≥2 rework loops on one gate.
+- A skill behaving contrary to its description.
+- Missing tool/permission.
+
+**Action:** Write `.dev-team/friction/<date>-<slug>.md` using the Friction
+Defect template (observed vs expected, skill involved, reproduction, rework
+count, proposed prevention class). Append a ready-to-run command to the inbox:
+`gh issue create --repo bronz3beard/ai.tech-lead-stack --label friction --title "..." --body-file ...`
+
+**Execution:** DEFAULT is draft only. In IDE/MCP mode, the agent MAY execute
+`gh issue create` iff the env var `DEV_TEAM_AUTOFILE_ISSUES=1`.
+
+> [!CAUTION] **ABSOLUTE RULE** `git push`, `git add`, and `merge` remain
+> STRICTLY FORBIDDEN regardless of mode or env var. Restated from
+> `.ai/agents.md`.
+
+## Telemetry
+
+Every persona action MUST run through the MCP skill tools so `withAnalytics`
+records it. Instruct agents to pass telemetry overrides to correctly tag team
+role actions:
+
+Pass `{ teamRole: "<ROLE>", loopRunId: "<MISSION_ID>", actorType: "AGENT" }`
+when invoking skills to ensure the activity is correctly attributed on the
+Agentic Health dashboard.
+
+### Hooks (Ownership Gates)
+
+Before advancing to the next phase or gate, you MUST consult `.ai/hooks/`. If a
+guard is triggered and requires human approval (`require-human-approve`), you
+MUST append the question to the human inbox (`.dev-team/inbox.md`) rather than
+proceeding.
+
+## Code Modification Convention
+
+**REQUIREMENT:** When modifying files, you MUST use the `apply_patch` tool with
+minimal SEARCH/REPLACE blocks instead of rewriting whole files.
+
+- Never emit a full-file rewrite.
+- Never restate unchanged code.
+- **Rule:** Include only the lines that change plus minimal surrounding anchor
+  context.