tech-lead-stack 1.0.1

package/.agents/workflows/design-system-review.md

@@ -0,0 +1,113 @@
+---
+name: design-system-review
+description: >-
+  AI-augmented design review with a 2-iteration guard, sequential memory, and KI
+  persistence.
+modes:
+  - write
+---
+
+// turbo-all
+
+**CRITICAL: PHASE 0 - SKILL ACQUISITION IS NON-NEGOTIABLE.**
+**YOU MUST CALL THE GET_SKILLS TOOL EVEN IF YOU ALREADY HAVE THE CONTEXT. FAILURE TO DO SO BYPASSES MISSION TELEMETRY.**
+
+> [!IMPORTANT]
+> **ANTI-CONFLATION DIRECTIVE:**
+> This file (`.agents/workflows/design-system-review.md`) is a workflow launcher stub, NOT the skill definition.
+> Viewing this file via `view_file` does NOT satisfy Phase 0. You MUST call the MCP `get_skills` or `get_skill` tool FIRST with all 4 required fields before executing any other steps.
+
+- **Skill Usage Enforcement (NON-NEGOTIABLE):**
+  - **FORBIDDEN:** Direct file access via `view_file` or `run_command` is strictly prohibited for skill reading.
+  - **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.
+
+1. **Phase 0: Skill Acquisition**: Call the `get_skills` tool (which may be prefixed as `mcp_tech-lead-stack_get_skills` or `tech-lead-stack_get_skills` depending on client prefixing):
+   - skillName: "design-system-review"
+   - projectName: "<YOUR_CURRENT_PROJECT_NAME>"
+   - model: "<YOUR_MODEL_NAME>"
+   - agent: "<YOUR_AGENT_NAME>"
+
+---
+
+## Phase 1: Sequential Memory Init
+
+Before any analysis, use the `sequential-thinking` tool to initialize your
+session context:
+
+1. **Thought 1** — Identify the `sessionId` from the user message.
+2. **Thought 2** — Fetch the current session state via the local API:
+   `curl http://localhost:3000/api/design-review/session/<sessionId>`
+   - Restore iteration count, current status, and check if a `figmaUrl` was provided.
+3. **Thought 3** — Confirm: "Session initialized. Iteration N. Status: X."
+
+---
+
+## Phase 2: Existing KI Check
+
+Before auditing, search for past design decisions on this component:
+
+1. Call `list_knowledge_items` with the current project name.
+2. Look for any slug matching `design-decision-<component-name>-*`.
+3. If found: call `read_knowledge_item` and incorporate the past decision
+   into your audit context so you don't contradict approved deviations.
+
+---
+
+## Phase 3: Run the Audit (Follow Skill Gates)
+
+Execute the full skill workflow (Phase 0 → Gate 5):
+
+- Use `sequential-thinking` to track each gate result as a separate thought.
+- After each gate: record PASS / FAIL and the specific evidence.
+- After Gate 4 (Storybook/Figma): If a `figmaUrl` exists in the session, verify against it. If NO Figma URL exists, evaluate the component purely based on base Shadcn/Radix foundations and the project's brand tokens.
+- After Gate 5 (Chromatic): pause if credentials are needed, wait for user.
+- Update the session state via the API (using `PATCH /api/design-review/session/<sessionId>`) after all gates are complete.
+
+---
+
+## Phase 4: Iteration Decision
+
+**When the audit is complete (Score < 90%):**
+
+- Present the "Must Fix" list (🔴 Critical / 🟡 Recommended / 🟢 Advisory).
+- Instruct the user: "Apply these fixes, then reply `/design-system-review iterate` to trigger the next iteration."
+- **STOP here.** Do not proceed until the user responds.
+
+**On subsequent iterations (`/design-system-review iterate`):**
+
+- Re-fetch the session state to confirm the current iteration count.
+- Re-run only failed gates.
+- Calculate the new alignment score.
+- *Note:* There is a minimum of 2 iterations required, but you may scale upwards as needed to reach UI parity.
+- Branch:
+  - **≥ 90%** → Call `create_knowledge_item` → `PATCH` status to `READY_FOR_DESIGNER_GATE`
+  - **Still failing after multiple attempts & stuck** → `PATCH` status to `ESCALATED` and write to `docs/design-debt.md`
+
+---
+
+## Phase 5: Persistence
+
+On **any** session completion (pass or escalation):
+
+- Final `sequential-thinking` thought: summarize the full session outcome.
+- Update the session state using:
+  `curl -X PATCH http://localhost:3000/api/design-review/session/<sessionId> -H "Content-Type: application/json" -d '{"status": "<STATUS>", "alignmentScore": <SCORE>, "gateResults": [...]}'`
+- If `READY_FOR_DESIGNER_GATE`: call `create_knowledge_item` with the KI
+  schema from the skill.
+- If `ESCALATED`: append a new entry to `docs/design-debt.md`:
+
+```markdown
+## [YYYY-MM-DD] <Component Name>
+
+- **Status**: ESCALATED
+- **Alignment Score**: N%
+- **Unresolved Gates**: <list>
+- **Session ID**: `<sessionId>`
+- **Action Required**: Manual designer review
+```
+
+---
+
+*Companion skills: Always run `style-logic-exporter` first to extract current
+token state. Run `accessibility-auditor` in parallel for WCAG coverage.*

package/.agents/workflows/dev-team-sub-max.md

@@ -0,0 +1,57 @@
+---
+name: dev-team-sub-max
+description: >-
+  [DEV-TEAM · SUB-MAX · NO API KEYS · CROSS-MODEL VERIFY] Subscription-tier
+  ($100/mo) dev team orchestrator workflow (up to 2 lanes,
+  reflexion-loop-sub-max, cross-model verify, visual fidelity gate)
+modes:
+  - write
+---
+
+// turbo-all
+
+**CRITICAL: PHASE 0 - SKILL ACQUISITION IS NON-NEGOTIABLE.**
+**YOU MUST CALL THE GET_SKILLS TOOL EVEN IF YOU ALREADY HAVE THE CONTEXT. FAILURE TO DO SO BYPASSES MISSION TELEMETRY.**
+
+> [!IMPORTANT]
+> **ANTI-CONFLATION DIRECTIVE:**
+> This file (`.agents/workflows/dev-team-sub-max.md`) is a workflow launcher stub, NOT the skill definition.
+> Viewing this file via `view_file` does NOT satisfy Phase 0. You MUST call the MCP `get_skills` or `get_skill` tool FIRST with all 4 required fields before executing any other steps.
+
+- **Skill Usage Enforcement (NON-NEGOTIABLE):**
+  - **FORBIDDEN:** Direct file access via `view_file` or `run_command` is strictly prohibited for skill reading.
+  - **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.
+
+> [!NOTE] `// turbo-all` is active for execution velocity, BUT it does NOT license bypassing PARK. Parking at a gate or inbox question is a HARD STOP regardless.
+
+1. **Phase 0: Skill Acquisition (FIRST ACTION — NO EXCEPTIONS)**:
+   Call the `get_skills` / `get_skill` tool with all 4 required fields:
+   - `skillName`: "dev-team-sub-max"
+   - `projectName`: "<YOUR_CURRENT_PROJECT_NAME>"
+   - `model`: "<YOUR_MODEL_NAME>"
+   - `agent`: "<YOUR_AGENT_NAME>"
+
+2. **Pre-Flight Model Contract**: Formulate and print model assignments and isolation levels (L0-L3). Check `CLAUDE_CODE_SUBAGENT_MODEL` (warn and cap at L2 if overridden). Resolve reviewer/QA models with `./.ai/rtk-run run resolve-critic --writer <vendor> --writer-model <planner-model>` (Gemini `gemini-cli`/`agy` -> `codex` -> Claude sub-agent/`claude-cli` -> another model -> same model + STRONG `Critic Advisory` in the lane state file).
+3. **Phase 0A: Cold Resume Check**: Inspect `.dev-team/lanes/*.md`. If incomplete lanes exist, print Quota Ledger, read state files and Findings Ledger (`.dev-team/analysis/<lane-id>.md`), and resume directly from recorded Phase without re-running Phase 0 discovery.
+4. **Phase 0B: Discovery & Mission Frame**: Run scoped discovery (excluding build/dependency dirs), create Findings Ledger, and establish Mission Frame.
+5. **Phase 1: Crew Sizing Gate**: Score the five signals (0-2). Max 2 parallel lanes. If score = XL, open Tech-Lead confirmation gate stating expected turn cost (~60 turns) before worktree creation. Print scores first.
+6. **Phase 2: Lane & Quota Ledgers**: Initialize Quota Ledger (`.dev-team/quota.md` tracking active models and headroom). Set up Lane Ledger and git worktrees. Write lane state files (`.dev-team/lanes/<lane-id>.md`) BEFORE entering gates. Mandatory worktree bootstrap before testing.
+7. **Phase 3: Persona Execution & Model Continuity**: Run pm-analyst, planner, developer, reviewer, qa. Hardened plans via `reflexion-loop-sub-max`. Reviewer runs in fresh sub-agent (Context Firewall) with diff + criteria + commands. Handle exhaustion Modes A/B/C via fallback ladder; mark degraded reviewer approvals as PROVISIONAL (Risk-2 work MUST PARK). UI slices MUST enforce visual fidelity gate.
+8. **Phase 4: Tech-Lead Interview**: Batch questions at gate boundaries in `.dev-team/inbox.md`. PARK is a hard stop. Inbox is read-only after human responds. Never bypass gate failures silently.
+9. **Phase 5: Friction Defect Protocol**: Document rework ≥2, tool failures, or >2 model swaps in `.dev-team/friction/<date>-<slug>.md`. Draft issue command (autofile only if `DEV_TEAM_AUTOFILE_ISSUES=1`).
+10. **Mandatory Disclosure Output**: Emit the disclosure status (`Model separation held` vs `MODEL SEPARATION LOST`) as the VERY FIRST line of final output, followed by the full Provenance Table.
+11. **Telemetry**: Include `{ teamRole, loopRunId, actorType: 'AGENT' }` on all persona skill calls.
+12. **Anti-drift Guard**: Reprint Lane and Quota Ledgers after every detour or completed gate.
+
+**Execution guardrails (CRITICAL):**
+This workflow relies on the `dev-team-sub-max` skill. You MUST follow its explicit execution guardrails covering:
+- **Execution Discipline:** Direct native file edits only, produce-don't-deliberate, no stall commands.
+- **Interrupt Safety:** Checkpoint BEFORE gate in `.dev-team/lanes/<lane-id>.md`. Cold resume protocol on fresh window.
+- **Model Isolation & Continuity:** First-line same-model disclosure line, PROVISIONAL slice tracking, Findings Ledger updates.
+- **Hard Gate Rules:** PARK is a hard stop; `git push`, `git add`, `merge` STRICTLY FORBIDDEN.
+
+**IDE surface activation notes:**
+- **Antigravity:** Paste file content into Agent Manager > Customizations > Workflows (trigger via `/dev-team-sub-max`).
+- **Cursor:** `install.sh` symlinks to `~/.cursor/skills/workflow-dev-team-sub-max/SKILL.md` (trigger via `@workflow-dev-team-sub-max`).
+- **Continue:** `install.sh` symlinks to `~/.continue/prompts/dev-team-sub-max.prompt` (trigger via `/dev-team-sub-max`).

package/.agents/workflows/dev-team-sub-pro.md

@@ -0,0 +1,57 @@
+---
+name: dev-team-sub-pro
+description: >-
+  [DEV-TEAM · SUB-PRO · NO API KEYS · CROSS-MODEL VERIFY] Subscription-tier
+  ($20/mo) dev pair orchestrator workflow (1 lane, no worktrees,
+  builder/checker, cross-model verify, tier ceiling)
+modes:
+  - write
+---
+
+// turbo-all
+
+**CRITICAL: PHASE 0 - SKILL ACQUISITION IS NON-NEGOTIABLE.**
+**YOU MUST CALL THE GET_SKILLS TOOL EVEN IF YOU ALREADY HAVE THE CONTEXT. FAILURE TO DO SO BYPASSES MISSION TELEMETRY.**
+
+> [!IMPORTANT]
+> **ANTI-CONFLATION DIRECTIVE:**
+> This file (`.agents/workflows/dev-team-sub-pro.md`) is a workflow launcher stub, NOT the skill definition.
+> Viewing this file via `view_file` does NOT satisfy Phase 0. You MUST call the MCP `get_skills` or `get_skill` tool FIRST with all 4 required fields before executing any other steps.
+
+- **Skill Usage Enforcement (NON-NEGOTIABLE):**
+  - **FORBIDDEN:** Direct file access via `view_file` or `run_command` is strictly prohibited for skill reading.
+  - **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.
+
+> [!NOTE] `// turbo-all` is active for execution velocity, BUT it does NOT license bypassing PARK. Parking at a gate or inbox question is a HARD STOP regardless.
+
+1. **Phase 0: Skill Acquisition (FIRST ACTION — NO EXCEPTIONS)**:
+   Call the `get_skills` / `get_skill` tool with all 4 required fields:
+   - `skillName`: "dev-team-sub-pro"
+   - `projectName`: "<YOUR_CURRENT_PROJECT_NAME>"
+   - `model`: "<YOUR_MODEL_NAME>"
+   - `agent`: "<YOUR_AGENT_NAME>"
+
+2. **Pre-Flight Model Contract**: Print model assignments and isolation levels (L0-L3). Check `CLAUDE_CODE_SUBAGENT_MODEL` (warn and cap at L2 if overridden). Resolve the Checker model with `./.ai/rtk-run run resolve-critic --writer <vendor> --writer-model <builder-model>` (Gemini `gemini-cli`/`agy` -> `codex` -> Claude sub-agent/`claude-cli` -> another model -> same model + STRONG `Critic Advisory` in the lane state file).
+3. **Phase 0A: Cold Resume Check**: Inspect `.dev-team/lanes/lane-1.md`. If incomplete, print Quota Ledger, read state file and Findings Ledger (`.dev-team/analysis/lane-1.md`), and resume directly from recorded Phase without re-running Phase 0 discovery.
+4. **Phase 0B: Discovery & Mission Frame**: Run scoped discovery (excluding build/dependency dirs), create Findings Ledger, and establish Mission Frame.
+5. **Phase 1: Crew Sizing & Tier Ceiling Gate**: Score the five signals (0-2). Score ≥ 6 (L/XL) or Risk signal = 2 -> REFUSE and escalate immediately. Print scores first regardless.
+6. **Phase 2: Single-Lane & Quota Ledger**: Initialize Quota Ledger (`.dev-team/quota.md`, 20 turn budget, active model tracking). No git worktrees (operate directly on branch). Write checkpoint `.dev-team/lanes/lane-1.md` BEFORE entering gates. If Mode B limit hit or turns reach 20, consolidate into Findings Ledger, PARK, and hand back.
+7. **Phase 3: Two-Hat Execution (Builder & Checker)**: Builder plans and implements (optional `reflexion-loop-sub-pro` if Risk = 1). Checker runs in fresh sub-agent (Context Firewall) and pastes hard evidence. Mark degraded Checker approvals as PROVISIONAL (Risk-2 work MUST PARK). Visual gate for UI slices requires Figma spec in plan and 2-viewport capture.
+8. **Phase 4: Tech-Lead Interview**: Batch questions at gate boundaries in `.dev-team/inbox.md`. PARK is a hard stop. Inbox is read-only after human responds. Never bypass gate failures silently.
+9. **Phase 5: Friction Defect Protocol**: Document rework ≥2, tool failures, or >2 model swaps in `.dev-team/friction/<date>-<slug>.md`. Draft issue command (autofile only if `DEV_TEAM_AUTOFILE_ISSUES=1`).
+10. **Mandatory Disclosure Output**: Emit disclosure status (`Model separation held` vs `MODEL SEPARATION LOST`) as the VERY FIRST line of final output, followed by the full Provenance Table.
+11. **Telemetry**: Include `{ teamRole, loopRunId, actorType: 'AGENT' }` on all skill calls.
+12. **Anti-drift Guard**: Reprint Lane Ledger after every detour or completed gate.
+
+**Execution guardrails (CRITICAL):**
+This workflow relies on the `dev-team-sub-pro` skill. You MUST follow its explicit execution guardrails covering:
+- **Execution Discipline:** Direct native file edits only, produce-don't-deliberate, single branch checkout (no worktrees).
+- **Tier Ceilings:** Refuse L/XL and Risk-2 tasks immediately. Maximum 20 turns per slice.
+- **Interrupt Safety & Model Continuity:** Checkpoint BEFORE gate in `.dev-team/lanes/lane-1.md`. Mode B consolidate-and-park. First-line same-model disclosure line.
+- **Hard Gate Rules:** PARK is a hard stop; `git push`, `git add`, `merge` STRICTLY FORBIDDEN.
+
+**IDE surface activation notes:**
+- **Antigravity:** Paste file content into Agent Manager > Customizations > Workflows (trigger via `/dev-team-sub-pro`).
+- **Cursor:** `install.sh` symlinks to `~/.cursor/skills/workflow-dev-team-sub-pro/SKILL.md` (trigger via `@workflow-dev-team-sub-pro`).
+- **Continue:** `install.sh` symlinks to `~/.continue/prompts/dev-team-sub-pro.prompt` (trigger via `/dev-team-sub-pro`).

package/.agents/workflows/dev-team.md

@@ -0,0 +1,52 @@
+---
+name: dev-team
+description: >-
+  [DEV-TEAM · FULL · MCP] The flagship orchestration workflow for an agentic dev
+  team
+modes:
+  - write
+---
+
+// turbo-all
+
+**CRITICAL: PHASE 0 - SKILL ACQUISITION IS NON-NEGOTIABLE.**
+**YOU MUST CALL THE GET_SKILLS TOOL EVEN IF YOU ALREADY HAVE THE CONTEXT. FAILURE TO DO SO BYPASSES MISSION TELEMETRY.**
+
+> [!IMPORTANT]
+> **ANTI-CONFLATION DIRECTIVE:**
+> This file (`.agents/workflows/dev-team.md`) is a workflow launcher stub, NOT the skill definition.
+> Viewing this file via `view_file` does NOT satisfy Phase 0. You MUST call the MCP `get_skills` or `get_skill` tool FIRST with all 4 required fields before executing any other steps.
+
+- **Skill Usage Enforcement (NON-NEGOTIABLE):**
+  - **FORBIDDEN:** Direct file access via `view_file` or `run_command` is strictly prohibited for skill reading.
+  - **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.
+
+1. **Phase 0: Skill Acquisition**: Call the `get_skills` / `get_skill` tool:
+   - skillName: "dev-team-orchestrator"
+   - projectName: "<YOUR_CURRENT_PROJECT_NAME>"
+   - model: "<YOUR_MODEL_NAME>"
+   - agent: "<YOUR_AGENT_NAME>"
+
+2. **Phase 0 (cont): Discovery & Mission Frame**: Inspect the codebase for tech stack & domain boundaries. Establish the mission frame (one sentence + success metric).
+
+3. **Phase 1: Crew Sizing Gate**: Score the five signals (Surface area, Novelty, Risk, Ambiguity, Parallelism) from 0-2. Sum to get size (XS to XL) and assign the appropriate crew and lane setup. Print the sizing decision before any work.
+
+4. **Phase 2: Lane Ledger**: Set up the Lane Ledger tracking each lane's status, branch/worktree, state-file (`.dev-team/lanes/<lane-id>.md`), and next-gate.
+
+5. **Phase 3: Persona Execution**: Orchestrate the active lanes using existing skills for pm-analyst, planner, developer, reviewer, and qa. Ensure Reviewer must ACT, not read.
+
+6. **Phase 4: Tech-Lead Interview**: Batch questions at gate boundaries ONLY, appended to `.dev-team/inbox.md` using the YAML answers convention. Park the lane if unanswered.
+
+7. **Phase 5: Friction Defect Protocol**: File friction defects at `.dev-team/friction/<date>-<slug>.md` using the `friction-defect` template for >=2 rework loops, skill behavioral deviations, or missing tools. Create an issue command (draft only by default).
+
+8. **Telemetry**: Ensure telemetry events capture persona actions with `{ teamRole, loopRunId, actorType: 'AGENT' }`.
+
+9. **Anti-drift Guard**: Reprint the Lane Ledger after every detour or completed gate. Multiple lanes advance independently.
+
+**Execution guardrails (CRITICAL):**
+This workflow relies on the `dev-team-orchestrator` skill. You MUST follow its explicit execution guardrails covering:
+- **Execution Discipline:** Direct native file edits only (no patch.js/regex), produce-don't-deliberate, no stall commands.
+- **Discovery Budget:** Strict caps on search, omitting build/dependency directories.
+- **Lane & Worktree Integrity:** No silent lane creation; mandatory bootstrap (deps, `.env`, clients, builds) of fresh worktrees before testing.
+- **Hard Gate Rules:** Inbox is read-only after human writes; PARK is a hard stop; NEVER silently bypass a tool failure (e.g., `reflexion-loop`) without human consent.

package/.agents/workflows/feature-orchestrator.md

@@ -0,0 +1,43 @@
+---
+name: feature-orchestrator
+description: Three-Phase Feature Engine (Research -> Plan -> Implement)
+modes:
+  - write
+---
+
+// turbo-all
+
+**CRITICAL: PHASE 0 - SKILL ACQUISITION IS NON-NEGOTIABLE.**
+**YOU MUST CALL THE GET_SKILLS TOOL EVEN IF YOU ALREADY HAVE THE CONTEXT. FAILURE TO DO SO BYPASSES MISSION TELEMETRY.**
+
+> [!IMPORTANT]
+> **ANTI-CONFLATION DIRECTIVE:**
+> This file (`.agents/workflows/feature-orchestrator.md`) is a workflow launcher stub, NOT the skill definition.
+> Viewing this file via `view_file` does NOT satisfy Phase 0. You MUST call the MCP `get_skills` or `get_skill` tool FIRST with all 4 required fields before executing any other steps.
+
+- **Skill Usage Enforcement (NON-NEGOTIABLE):**
+  - **FORBIDDEN:** Direct file access via `view_file` or `run_command` is strictly prohibited for skill reading.
+  - **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.
+
+1. **Phase 0: Skill Acquisition (CRITICAL)**: Call the `get_skills` tool (or `get_feature_orchestrator` alias):
+   - skillName: "feature-orchestrator"
+   - projectName: "<NAME_FROM_PACKAGE_JSON>"
+   - model: "<YOUR_MODEL_NAME>"
+   - agent: "<YOUR_AGENT_NAME>"
+
+2. **Determine Runtime Mode**: Read-only chat (`/chat`) → run Research + Plan and
+   deliver Implement as a verifiable blueprint + handoff. IDE/MCP agent → execute
+   and verify the Implement phase in the sandbox.
+
+3. **Run the orchestration**: Follow the skill to drive the feature through
+   Research (chain `feature-design-assistant`; add `ui-spec-generator` /
+   `design-system-review` when designs are provided) → Plan (chain
+   `vertical-slice-decomposer` for user-facing work, else `planning-expert`) →
+   Implement & Verify (chain `verification-auditor`; remediate via
+   `regression-bug-fix`). Acquire each specialist skill via `get_skill(s)` so
+   every phase emits a trace for the dashboard tracker.
+
+4. **Finale**: Once all tools finish, provide an EXHAUSTIVE final report —
+   per-phase outcomes, the slice list with verification commands, and the next
+   action. Do NOT exit without a text finale report.

package/.agents/workflows/init.md

@@ -0,0 +1,31 @@
+---
+name: init
+description: Master Setup
+modes:
+  - write
+---
+
+// turbo-all
+
+**CRITICAL: PHASE 0 - SKILL ACQUISITION IS NON-NEGOTIABLE.**
+**YOU MUST CALL THE GET_SKILLS TOOL EVEN IF YOU ALREADY HAVE THE CONTEXT. FAILURE TO DO SO BYPASSES MISSION TELEMETRY.**
+
+> [!IMPORTANT]
+> **ANTI-CONFLATION DIRECTIVE:**
+> This file (`.agents/workflows/init.md`) is a workflow launcher stub, NOT the skill definition.
+> Viewing this file via `view_file` does NOT satisfy Phase 0. You MUST call the MCP `get_skills` or `get_skill` tool FIRST with all 4 required fields before executing any other steps.
+
+- **Skill Usage Enforcement (NON-NEGOTIABLE):**
+  - **FORBIDDEN:** Direct file access via `view_file` or `run_command` is strictly prohibited for skill reading.
+  - **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.
+
+1. **Phase 0: Skill Acquisition**: Call the `get_skills` tool (which may be prefixed as `mcp_tech-lead-stack_get_skills` or `tech-lead-stack_get_skills` depending on client prefixing):
+   - skillName: "mission-control"
+   - projectName: "<YOUR_CURRENT_PROJECT_NAME>"
+   - model: "<YOUR_MODEL_NAME>"
+   - agent: "<YOUR_AGENT_NAME>"
+
+2. **Phase 1: Environment Discovery**: Identify the tech stack by reading root configuration files (e.g., package.json, pyproject.toml, go.mod, Cargo.toml, pom.xml, build.gradle) to understand architectural constraints.
+
+3. Follow its workflow to perform a pre-flight diagnostic of the environment and tools.

package/.agents/workflows/mission-architect.md

@@ -0,0 +1,31 @@
+---
+name: mission-architect
+description: Master Feature Orchestration
+modes:
+  - write
+---
+
+// turbo-all
+
+**CRITICAL: PHASE 0 - SKILL ACQUISITION IS NON-NEGOTIABLE.**
+**YOU MUST CALL THE GET_SKILLS TOOL EVEN IF YOU ALREADY HAVE THE CONTEXT. FAILURE TO DO SO BYPASSES MISSION TELEMETRY.**
+
+> [!IMPORTANT]
+> **ANTI-CONFLATION DIRECTIVE:**
+> This file (`.agents/workflows/mission-architect.md`) is a workflow launcher stub, NOT the skill definition.
+> Viewing this file via `view_file` does NOT satisfy Phase 0. You MUST call the MCP `get_skills` or `get_skill` tool FIRST with all 4 required fields before executing any other steps.
+
+- **Skill Usage Enforcement (NON-NEGOTIABLE):**
+  - **FORBIDDEN:** Direct file access via `view_file` or `run_command` is strictly prohibited for skill reading.
+  - **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.
+
+1. **Phase 0: Skill Acquisition**: Call the `get_skills` tool (which may be prefixed as `mcp_tech-lead-stack_get_skills` or `tech-lead-stack_get_skills` depending on client prefixing):
+   - skillName: "mission-architect"
+   - projectName: "<YOUR_CURRENT_PROJECT_NAME>"
+   - model: "<YOUR_MODEL_NAME>"
+   - agent: "<YOUR_AGENT_NAME>"
+
+2. **Phase 1: Environment Discovery**: Identify the tech stack by reading root configuration files (e.g., package.json, pyproject.toml, go.mod, Cargo.toml, pom.xml, build.gradle) to understand architectural constraints.
+
+3. Follow its 4-phase master pipeline to bridge Product Strategy with a high-fidelity implementation aligned to the G-Stack Methodology.

package/.agents/workflows/onboard-dev.md

@@ -0,0 +1,31 @@
+---
+name: onboard-dev
+description: Codebase Onboarding Intelligence
+modes:
+  - write
+---
+
+// turbo-all
+
+**CRITICAL: PHASE 0 - SKILL ACQUISITION IS NON-NEGOTIABLE.**
+**YOU MUST CALL THE GET_SKILLS TOOL EVEN IF YOU ALREADY HAVE THE CONTEXT. FAILURE TO DO SO BYPASSES MISSION TELEMETRY.**
+
+> [!IMPORTANT]
+> **ANTI-CONFLATION DIRECTIVE:**
+> This file (`.agents/workflows/onboard-dev.md`) is a workflow launcher stub, NOT the skill definition.
+> Viewing this file via `view_file` does NOT satisfy Phase 0. You MUST call the MCP `get_skills` or `get_skill` tool FIRST with all 4 required fields before executing any other steps.
+
+- **Skill Usage Enforcement (NON-NEGOTIABLE):**
+  - **FORBIDDEN:** Direct file access via `view_file` or `run_command` is strictly prohibited for skill reading.
+  - **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.
+
+1. **Phase 0: Skill Acquisition**: Call the `get_skills` tool (which may be prefixed as `mcp_tech-lead-stack_get_skills` or `tech-lead-stack_get_skills` depending on client prefixing):
+   - skillName: "codebase-onboarding-intelligence"
+   - projectName: "<YOUR_CURRENT_PROJECT_NAME>"
+   - model: "<YOUR_MODEL_NAME>"
+   - agent: "<YOUR_AGENT_NAME>"
+
+2. **Phase 1: Environment Discovery**: Identify the tech stack by reading root configuration files (e.g., package.json, pyproject.toml, go.mod, Cargo.toml, pom.xml, build.gradle) to understand architectural constraints.
+
+3. Follow its workflow to map out tech stack, patterns, and vitals.

package/.agents/workflows/plan-quick.md

@@ -0,0 +1,33 @@
+---
+name: plan-quick
+description: >-
+  Ultra-lean strategic planning. Optimized for speed, token efficiency, and
+  rapid MVC delivery.
+modes:
+  - write
+---
+
+// turbo-all
+
+**CRITICAL: PHASE 0 - SKILL ACQUISITION IS NON-NEGOTIABLE.**
+**YOU MUST CALL THE GET_SKILLS TOOL EVEN IF YOU ALREADY HAVE THE CONTEXT. FAILURE TO DO SO BYPASSES MISSION TELEMETRY.**
+
+> [!IMPORTANT]
+> **ANTI-CONFLATION DIRECTIVE:**
+> This file (`.agents/workflows/plan-quick.md`) is a workflow launcher stub, NOT the skill definition.
+> Viewing this file via `view_file` does NOT satisfy Phase 0. You MUST call the MCP `get_skills` or `get_skill` tool FIRST with all 4 required fields before executing any other steps.
+
+- **Skill Usage Enforcement (NON-NEGOTIABLE):**
+  - **FORBIDDEN:** Direct file access via `view_file` or `run_command` is strictly prohibited for skill reading.
+  - **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.
+
+1. **Phase 0: Skill Acquisition**: Call the `get_skills` tool (which may be prefixed as `mcp_tech-lead-stack_get_skills` or `tech-lead-stack_get_skills` depending on client prefixing):
+   - skillName: "planning-expert-quick"
+   - projectName: "<YOUR_CURRENT_PROJECT_NAME>"
+   - model: "<YOUR_MODEL_NAME>"
+   - agent: "<YOUR_AGENT_NAME>"
+
+2. **Phase 1: Environment Discovery**: Identify the tech stack by reading root configuration files (e.g., package.json, pyproject.toml, go.mod, Cargo.toml, pom.xml, build.gradle) to understand architectural constraints.
+
+3. Follow its workflow to convert the ticket description into a methodology-compliant plan.

package/.agents/workflows/plan.md

@@ -0,0 +1,31 @@
+---
+name: plan
+description: Implementation & Bug Planning
+modes:
+  - write
+---
+
+// turbo-all
+
+**CRITICAL: PHASE 0 - SKILL ACQUISITION IS NON-NEGOTIABLE.**
+**YOU MUST CALL THE GET_SKILLS TOOL EVEN IF YOU ALREADY HAVE THE CONTEXT. FAILURE TO DO SO BYPASSES MISSION TELEMETRY.**
+
+> [!IMPORTANT]
+> **ANTI-CONFLATION DIRECTIVE:**
+> This file (`.agents/workflows/plan.md`) is a workflow launcher stub, NOT the skill definition.
+> Viewing this file via `view_file` does NOT satisfy Phase 0. You MUST call the MCP `get_skills` or `get_skill` tool FIRST with all 4 required fields before executing any other steps.
+
+- **Skill Usage Enforcement (NON-NEGOTIABLE):**
+  - **FORBIDDEN:** Direct file access via `view_file` or `run_command` is strictly prohibited for skill reading.
+  - **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.
+
+1. **Phase 0: Skill Acquisition**: Call the `get_skills` tool (which may be prefixed as `mcp_tech-lead-stack_get_skills` or `tech-lead-stack_get_skills` depending on client prefixing):
+   - skillName: "planning-expert"
+   - projectName: "<YOUR_CURRENT_PROJECT_NAME>"
+   - model: "<YOUR_MODEL_NAME>"
+   - agent: "<YOUR_AGENT_NAME>"
+
+2. **Phase 1: Environment Discovery**: Identify the tech stack by reading root configuration files (e.g., package.json, pyproject.toml, go.mod, Cargo.toml, pom.xml, build.gradle) to understand architectural constraints.
+
+3. Follow its workflow to convert the ticket description into a methodology-compliant plan.

package/.agents/workflows/pr-automator.md

@@ -0,0 +1,44 @@
+---
+description: >-
+  PR Automator (with Mandatory Dynamic Template Adherence, Commit History
+  Review, Label Matching, & Draft Mode)
+modes:
+  - write
+---
+
+// turbo-all
+
+**CRITICAL: PHASE 0 - SKILL ACQUISITION IS NON-NEGOTIABLE.**
+**YOU MUST CALL THE GET_SKILLS TOOL EVEN IF YOU ALREADY HAVE THE CONTEXT. FAILURE TO DO SO BYPASSES MISSION TELEMETRY.**
+
+> [!IMPORTANT]
+> **ANTI-CONFLATION DIRECTIVE:**
+> This file (`.agents/workflows/pr-automator.md`) is a workflow launcher stub, NOT the skill definition.
+> Viewing this file via `view_file` does NOT satisfy Phase 0. You MUST call the MCP `get_skills` or `get_skill` tool FIRST with all 4 required fields before executing any other steps.
+
+- **Skill Usage Enforcement (NON-NEGOTIABLE):**
+  - **FORBIDDEN:** Direct file access via `view_file` or `run_command` is strictly prohibited for skill reading.
+  - **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.
+
+1. **Phase 0: Skill Acquisition**: Call the `get_skills` tool (which may be prefixed as `mcp_tech-lead-stack_get_skills` or `tech-lead-stack_get_skills` depending on client prefixing):
+   - skillName: "pr-automator"
+   - projectName: "<YOUR_CURRENT_PROJECT_NAME>"
+   - model: "<YOUR_MODEL_NAME>"
+   - agent: "<YOUR_AGENT_NAME>"
+   - runCodeReview: "<boolean>" Set to `true` if the user provided flags like `--code-review` or explicitly asked for a code review in their command. Defaults to `false`.
+
+2. **Phase 1: Environment & Template Discovery**:
+   - Identify base branch (e.g. from prompt `base branch: <name>` or `main`).
+   - Discover host project's PR template (`.github/pull_request_template.md` or variants). Retain its exact headings and sections.
+   - Sync branch to remote if unpushed: `git push -u origin <HEAD_BRANCH>`.
+
+3. **Phase 2: Review Commit History & Semantic Extraction**:
+   - Run `git log <base>...HEAD --pretty=format:"%h %s"` to review all commits on the branch.
+   - Formulate semantic change lists (`- add:`, `- update:`, `- fix:`, `- refactor:`, `- delete:`) matching the real commit work.
+
+4. **Phase 3: Populate Template, Match Labels, & Create Draft PR**:
+   - Map user-provided inputs (`section` / `module`, `sprint`, testing / release readiness status) into template fields.
+   - If user requests no evidence, activate the **Evidence Skip Fast-Path** immediately.
+   - Match available repository labels (`gh label list`) based on branch, commits, and diff.
+   - Execute `gh pr create --draft` non-interactively with `--body-file` and return the resulting PR URL to the user.

package/.agents/workflows/pr-design-review-init.md

@@ -0,0 +1,57 @@
+---
+name: pr-design-review-init
+description: Start an AI-powered design review from an existing GitHub PR URL.
+modes:
+  - write
+---
+
+# 🛠 PR Design Review Initiation (Developer Start)
+
+**ROLE: DEVELOPER**
+This workflow allows a developer to bypass the code-generation phase and trigger an AI design audit on an existing Pull Request.
+
+## Objective
+> [!IMPORTANT]
+> **ANTI-CONFLATION DIRECTIVE:**
+> This file is a workflow launcher stub. When transitioning to `design-system-review`, you MUST call the MCP `get_skills` tool with all 4 required fields (`skillName`, `projectName`, `model`, `agent`) to initialize mission telemetry.
+
+---
+
+## 🛠 Execution Steps
+
+### Step 0: Skill Acquisition (NON-NEGOTIABLE)
+Call the `get_skills` tool before anything else:
+   - skillName: "design-system-review"
+   - projectName: "<YOUR_CURRENT_PROJECT_NAME>"
+   - model: "<YOUR_MODEL_NAME>"
+   - agent: "<YOUR_AGENT_NAME>"
+
+### Step 1: PR Metadata Discovery
+1. **Analyze the URL**: Scrape the provided GitHub PR URL using `firecrawl_scrape`.
+2. **Extract Key Info**:
+   - **Component Name**: Extract from the PR title or by inspecting the file diff (e.g., if `ProjectCard.tsx` was modified).
+   - **Branch Name**: Identify the source branch of the PR.
+   - **Project ID**: Map the GitHub repository to the internal Tech-Lead Stack `projectId`.
+3. **Report Findings**: Summarize the detected component and branch to the developer.
+
+### Step 2: Session Creation
+1. Call the Tech-Lead Stack API to create the session:
+   ```bash
+   curl -X POST <TECH_LEAD_STACK_URL>/api/design-review \
+     -H "Content-Type: application/json" \
+     -d '{
+       "projectId": "<PROJECT_ID>",
+       "component": "<COMPONENT_NAME>",
+       "prUrl": "<PR_URL>",
+       "initiatedBy": "DEVELOPER"
+     }'
+   ```
+2. Capture the `sessionId` from the response.
+
+### Step 3: Trigger AI Audit
+1. Automatically transition to the `design-system-review` workflow using the new `sessionId`.
+2. **Instruction**: "Session created. Starting the automated Design System Audit now..."
+
+---
+
+**Completion:** Confirm to the developer that the session is live and provide a link to the Design Review Dashboard for that project.

package/.agents/workflows/qa-handover.md

@@ -0,0 +1,40 @@
+---
+description: >-
+  Generate a QA handover + universal smoke-test criteria document and deliver it
+  to ClickUp
+modes:
+  - write
+---
+
+// turbo-all
+
+**CRITICAL: PHASE 0 - SKILL ACQUISITION IS NON-NEGOTIABLE.**
+**YOU MUST CALL THE GET_SKILLS TOOL EVEN IF YOU ALREADY HAVE THE CONTEXT. FAILURE TO DO SO BYPASSES MISSION TELEMETRY.**
+
+> [!IMPORTANT]
+> **ANTI-CONFLATION DIRECTIVE:**
+> This file (`.agents/workflows/qa-handover.md`) is a workflow launcher stub, NOT the skill definition.
+> Viewing this file via `view_file` does NOT satisfy Phase 0. You MUST call the MCP `get_skills` or `get_skill` tool FIRST with all 4 required fields before executing any other steps.
+
+- **Skill Usage Enforcement (NON-NEGOTIABLE):**
+  - **FORBIDDEN:** Direct file access via `view_file` or `run_command` is strictly prohibited for skill reading.
+  - **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.
+
+1. **Phase 0: Skill Acquisition**: Call the `get_skills` / `get_skill` tool:
+   - skillName: "qa-handover-generator"
+   - projectName: "<YOUR_CURRENT_PROJECT_NAME>"
+   - model: "<YOUR_MODEL_NAME>"
+   - agent: "<YOUR_AGENT_NAME>"
+
+2. **Phase 0 (cont): Scope & Architecture Discovery**: Identify the exact modules/screens the change touches. From the REAL code, determine how the feature manages state — distinguish server-driven (URL/query is source of truth, round-trips to server) from client-side/in-memory/offline-first (static fetch, in-memory filtering), or whatever pattern the code actually uses. For each pattern extract the single source of truth and the owning hook/query/function by real name. Scoped searches only (exclude node_modules/.next/.nx/dist/build).
+
+3. **Gate 1: Architecture Overview**: Write the Architecture Overview split by the patterns actually found — target modules, single source of truth, mechanism (named symbols), pattern-specific behaviours. Every claim traces to real code.
+
+4. **Gate 2: Universal Smoke-Test Criteria**: For each pattern, write smoke-test acceptance criteria covering general usage and core flows (not edge cases), each with expected result and pattern-specific gotcha. Each criterion must be agent-ingestible AND human-followable. Render as ClickUp checklist items.
+
+5. **Gate 3: Testability & Environment Notes**: State URLs/modules, auth/role, offline/PWA and data/environment considerations so QA does not report false failures.
+
+6. **Gate 4: ClickUp Delivery**: Render the ENTIRE document through the shared module `scripts/clickup-format.ts` — never hand-roll ClickUp markdown. Tables via `renderTable(table, mode, target)`: `mode` defaults to `'pipe'` (native ClickUp Doc/task tables) and auto-falls back to `'list'` when a table exceeds the destination column limit (8 for docs, 4 for task descriptions); pass `target` `'doc'` or `'task'` to match where it will be created. When the ClickUp MCP is connected AND a destination (space/folder/list/doc id + title) is provided, create the handover via `clickup_create_document` / `clickup_create_document_page` and confirm headings/table/checkboxes/code render correctly. Otherwise write the rendered content to `.ai/output/qa-handovers/<feature>-handover.md`. Never create in ClickUp without an explicit destination.
+
+7. **Telemetry**: Pass overrides `{ teamRole: "qa", actorType: "AGENT", loopRunId: "<MISSION_ID>" }` on MCP skill calls.