SKILL: a11y-audit

Purpose

Run WCAG 2.2 Level AA accessibility audits against generated UI. Uses axe-core (via @axe-core/cli) or pa11y as available. Posts findings as PR comments. Blocks merge on AA violations. Required for every story with ui: true.

Target awareness

When design.target (project.config.yaml, default web) is tui, skip the browser tooling (axe/pa11y) and the preview URL. Instead evaluate the terminal a11y checklist from docs/design/design-targets.md and write the findings to docs/design/mockups/<id>.a11y.json using the SAME object shape the web path produces — an object with violations[], where each violation has id, impact (critical|serious|moderate|minor), description, help, and nodes[] ({target:[...], failureSummary}). The gate (scripts/sdlc/a11y-gate.sh) reads only violations[].impact, so matching this shape keeps it unchanged. Map checklist failures to impacts: keyboard-reachable→critical, focus-visible→serious, color-contrast→serious, color-only-signaling→serious, no-color-support→moderate, min-width-resize→moderate. The WCAG criteria, tool-detection, axe/pa11y, and PR-comment sections below apply to web targets.

WCAG 2.2 AA — Minimum Requirements

Tool Detection

detect_tool() {
  if command -v axe &>/dev/null; then
    echo "axe"
  elif command -v pa11y &>/dev/null; then
    echo "pa11y"
  elif npx --yes @axe-core/cli --version &>/dev/null 2>&1; then
    echo "axe-npx"
  else
    echo "none"
  fi
}
TOOL=$(detect_tool)

Run with axe-core CLI

URL="${1:-http://localhost:3000}"  # preview URL or Storybook story URL
STORY_ID="${2:-unknown}"
REPORT="docs/design/mockups/${STORY_ID}.a11y.json"

mkdir -p docs/design/mockups

axe "$URL" \
  --stdout \
  --tags wcag2a,wcag2aa,wcag21aa,wcag22aa \
  > "$REPORT"

VIOLATIONS=$(python3 -c "import json,sys; d=json.load(open('$REPORT')); print(len(d.get('violations',[])))")
echo "[a11y-audit] axe  $URL  violations=$VIOLATIONS"

Run with pa11y

URL="${1:-http://localhost:3000}"
STORY_ID="${2:-unknown}"
REPORT="docs/design/mockups/${STORY_ID}.a11y.json"

pa11y "$URL" \
  --standard WCAG2AA \
  --reporter json \
  > "$REPORT" 2>&1

ISSUES=$(python3 -c "import json,sys; d=json.load(open('$REPORT')); print(len(d) if isinstance(d,list) else 0)")
echo "[a11y-audit] pa11y  $URL  issues=$ISSUES"

Parse Results and Classify

import json, sys

report_path = sys.argv[1]
data = json.load(open(report_path))

# axe format
violations = data.get("violations", [])
passes     = data.get("passes", [])

critical = [v for v in violations if v["impact"] in ("critical", "serious")]
moderate = [v for v in violations if v["impact"] == "moderate"]
minor    = [v for v in violations if v["impact"] == "minor"]

print(f"CRITICAL/SERIOUS: {len(critical)}")
print(f"MODERATE:         {len(moderate)}")
print(f"MINOR:            {len(minor)}")
print(f"PASSES:           {len(passes)}")

# Merge gate: block on critical + serious
if critical:
    print("\nMERGE BLOCKED — resolve the following before merging:")
    for v in critical:
        print(f"  [{v['impact'].upper()}] {v['id']}: {v['description']}")
        for node in v.get("nodes", [])[:2]:
            print(f"    → {node.get('target', ['?'])[0]}: {node.get('failureSummary','')[:120]}")
    sys.exit(1)

Post Findings as PR Comment

STORY_ID="auth-reset-0001"
PR_NUMBER=$(gh pr list --head "$(git branch --show-current)" --json number --jq '.[0].number')
REPORT="docs/design/mockups/${STORY_ID}.a11y.json"

# Build comment body
COMMENT=$(python3 - <<'EOF'
import json, sys

data = json.load(open(sys.argv[1]))
violations = data.get("violations", [])

if not violations:
    print("## ✅ A11y Audit Passed\n\nNo WCAG 2.2 AA violations found.")
    sys.exit(0)

lines = [f"## ⚠️ A11y Audit: {len(violations)} violation(s) found\n"]
for v in violations[:10]:
    impact = v.get("impact","").upper()
    lines.append(f"### [{impact}] {v['id']}")
    lines.append(f"_{v['description']}_\n")
    for node in v.get("nodes",[])[:2]:
        selector = ', '.join(node.get("target",[]))
        lines.append(f"- `{selector}`")
        lines.append(f"  {node.get('failureSummary','')[:200]}")
    lines.append("")

if len(violations) > 10:
    lines.append(f"_...and {len(violations)-10} more. See full report in `docs/design/mockups/`._")

print('\n'.join(lines))
EOF
"$REPORT")

gh pr comment "$PR_NUMBER" --body "$COMMENT"
echo "[a11y-audit] PR_COMMENT  #$PR_NUMBER  violations=$(echo "$COMMENT" | grep -c '\[CRITICAL\]\|\[SERIOUS\]' || echo 0)"

Merge Gate Check

Called from scripts/sdlc/a11y-gate.sh (added in Phase VII):

STORY_FILE="$1"
UI=$(python3 -c "
import re
m = re.search(r'^ui:\s*(true|false)', open('$STORY_FILE').read(), re.MULTILINE)
print(m.group(1) if m else 'false')
")

if [ "$UI" != "true" ]; then
  echo "[a11y-audit] SKIP  ui:false story — no audit required"
  exit 0
fi

STORY_ID=$(python3 -c "
import re
m = re.search(r'^id:\s*[\"\'](.*?)[\"\']', open('$STORY_FILE').read(), re.MULTILINE)
print(m.group(1) if m else 'unknown')
")
REPORT="docs/design/mockups/${STORY_ID}.a11y.json"

if [ ! -f "$REPORT" ]; then
  echo "[a11y-audit] FAIL  no audit report found for $STORY_ID — run audit before merging"
  exit 1
fi

python3 scripts/sdlc/parse-a11y-report.py "$REPORT"

Manual Audit Checklist (no tool available)

When TOOL=none, perform a structured manual check:

## Manual A11y Checklist — {story_id}

### Perceivable
- [ ] All images have meaningful `alt` text (or `alt=""` for decorative)
- [ ] Color is not the sole means of conveying information
- [ ] Normal text contrast ≥ 4.5:1 (check with browser DevTools)
- [ ] Large text contrast ≥ 3:1

### Operable
- [ ] Tab through the entire form/component with keyboard only
- [ ] All actions reachable without mouse
- [ ] No keyboard trap
- [ ] Focus indicator visible on every interactive element

### Understandable
- [ ] Form inputs have visible labels (not just placeholders)
- [ ] Errors described in text, not color alone
- [ ] Error messages are specific and actionable

### Robust
- [ ] Correct semantic elements: `<button>`, `<input>`, `<label>`
- [ ] ARIA attributes only where native HTML is insufficient
- [ ] Works with browser zoom at 200%

Failure Modes

Logging

[a11y-audit] RUN      http://localhost:6006/... story=auth-reset-0001  tool=axe
[a11y-audit] RESULT   violations=0  passes=24  WCAG2AA=PASS
[a11y-audit] RESULT   violations=3  critical=1  WCAG2AA=FAIL
[a11y-audit] PR_COMMENT  #42  violations=1
[a11y-audit] SKIP     ui:false story — audit not required
[a11y-audit] BLOCKED  merge blocked — 1 critical violation unresolved

SKILL: component-scaffold

Purpose

Generate a complete component file tree wired to design tokens. Each component gets an implementation file, Storybook story, unit test, and Gherkin spec file. Skeletons are runnable with TODO stubs — not empty files. Stack is auto-detected from project.config.yaml.

Inputs

Output Tree

For PasswordResetForm with stack react-mantine:

app/
└── components/
    └── PasswordResetForm/
        ├── index.tsx              ← component implementation
        ├── PasswordResetForm.stories.tsx  ← Storybook story
        ├── PasswordResetForm.test.tsx     ← unit tests (Vitest / Jest)
        └── PasswordResetForm.spec.ts      ← Gherkin step binding

Generate Component Index (react-mantine)

app/components/{ComponentName}/index.tsx:

// {ComponentName} — generated from story {story_id}
// Tokens: docs/design/identity/mantine.theme.ts
// TODO: implement from mockup docs/design/mockups/{story_id}.mockup.tsx

import { Stack, TextInput, Button } from '@mantine/core';
import { useState } from 'react';

export interface {ComponentName}Props {
  // TODO: define props from story acceptance criteria
  onSubmit?: (data: Record<string, unknown>) => void;
}

export function {ComponentName}({ onSubmit }: {ComponentName}Props) {
  // TODO: implement
  return (
    <Stack>
      {/* TODO: build from approved mockup */}
    </Stack>
  );
}

export default {ComponentName};

Generate Storybook Story

app/components/{ComponentName}/{ComponentName}.stories.tsx:

import type { Meta, StoryObj } from '@storybook/react';
import { {ComponentName} } from '.';

const meta: Meta<typeof {ComponentName}> = {
  title: 'Components/{ComponentName}',
  component: {ComponentName},
  parameters: {
    layout: 'centered',
  },
  tags: ['autodocs'],
};
export default meta;
type Story = StoryObj<typeof {ComponentName}>;

export const Default: Story = {
  args: {},
};

export const WithError: Story = {
  args: {
    // TODO: add error props
  },
};

Generate Unit Test

app/components/{ComponentName}/{ComponentName}.test.tsx:

import { render, screen } from '@testing-library/react';
import { describe, it, expect } from 'vitest';
import { {ComponentName} } from '.';

describe('{ComponentName}', () => {
  it('renders without crashing', () => {
    render(<{ComponentName} />);
    // TODO: assert presence of key elements from wireframe
    expect(document.body).toBeTruthy();
  });

  it('calls onSubmit when form is submitted', () => {
    // TODO: implement interaction test
  });

  it('shows validation error when input is invalid', () => {
    // TODO: implement error state test
  });
});

Generate Gherkin Step Binding

app/components/{ComponentName}/{ComponentName}.spec.ts:

// Gherkin step bindings for story {story_id}
// Feature file: tests/features/{epic}/{story_slug}.feature
import { Given, When, Then } from '@cucumber/cucumber';

// TODO: copy matching steps from cucumber-automation output
// Example:
// Given('the user is on the {string} page', async (page: string) => {
//   throw new Error('Pending');
// });

Python Stack Alternative

For stack=python (e.g., Django / HTMX):

app/
└── components/
    └── password_reset_form/
        ├── __init__.py
        ├── template.html
        ├── test_password_reset_form.py
        └── password_reset_form_steps.py

Scaffold Script

COMPONENT="PasswordResetForm"
STORY_ID="auth-reset-0001"
STACK="react-mantine"
DIR="app/components/$COMPONENT"

mkdir -p "$DIR"

# Check for existing files — never overwrite
for f in "index.tsx" "${COMPONENT}.stories.tsx" "${COMPONENT}.test.tsx" "${COMPONENT}.spec.ts"; do
  if [ -f "$DIR/$f" ]; then
    echo "[component-scaffold] SKIP  $DIR/$f  (already exists)"
  else
    echo "[component-scaffold] CREATE  $DIR/$f"
    # write the appropriate template (see above)
  fi
done

Token Wiring

After scaffold, inject token import into index.tsx:

# Verify mantine.theme.ts exists
[ -f "docs/design/identity/mantine.theme.ts" ] || \
  echo "[component-scaffold] WARN  mantine.theme.ts missing — run design-tokens skill"

Failure Modes

Logging

[component-scaffold] CREATE  app/components/PasswordResetForm/index.tsx
[component-scaffold] CREATE  app/components/PasswordResetForm/PasswordResetForm.stories.tsx
[component-scaffold] CREATE  app/components/PasswordResetForm/PasswordResetForm.test.tsx
[component-scaffold] CREATE  app/components/PasswordResetForm/PasswordResetForm.spec.ts
[component-scaffold] SKIP    app/components/PasswordResetForm/index.tsx  (already exists)
[component-scaffold] WARN    mantine.theme.ts missing

SKILL: cucumber-automation

Purpose

Extract Gherkin scenarios from story markdown files into runnable .feature files, and generate step definition stubs for the project's test stack. Keeps tests/features/ in sync with docs/stories/ as the single source of Gherkin truth.

Supported Stacks

Detect the stack from the repo root:

if [ -f "package.json" ] && grep -q "@cucumber/cucumber" package.json 2>/dev/null; then
  STACK="typescript"
elif [ -f "requirements.txt" ] && grep -q "behave" requirements.txt 2>/dev/null; then
  STACK="python"
elif [ -f "pom.xml" ] || [ -f "build.gradle" ]; then
  STACK="java"
else
  STACK="unknown"
fi

Extract Gherkin from a Story File

Story files contain Gherkin in fenced code blocks tagged with gherkin:

STORY_FILE="docs/stories/user-auth-reset-password-20250416143000-0001.md"
EPIC="user-auth"

# Extract content of ```gherkin ... ``` blocks
python3 - <<'EOF'
import re, sys

story = open(sys.argv[1]).read()
blocks = re.findall(r'```gherkin\n(.*?)```', story, re.DOTALL)
if not blocks:
    print("NO_GHERKIN", file=sys.stderr)
    sys.exit(1)
print('\n\n'.join(blocks))
EOF "$STORY_FILE"

Write the Feature File

STORY_FILE="docs/stories/user-auth-reset-password-20250416143000-0001.md"
FEATURE_DIR="tests/features"
EPIC="user-auth"

mkdir -p "$FEATURE_DIR/$EPIC"
FEATURE_FILE="$FEATURE_DIR/$EPIC/reset-password.feature"

# Extract and write (idempotent — overwrites if Gherkin changed)
python3 - <<'EOF'
import re, sys, os

story_path, feature_path = sys.argv[1], sys.argv[2]
story = open(story_path).read()
blocks = re.findall(r'```gherkin\n(.*?)```', story, re.DOTALL)
if not blocks:
    print(f"[cucumber] NO_GHERKIN in {story_path}", file=sys.stderr)
    sys.exit(1)

os.makedirs(os.path.dirname(feature_path), exist_ok=True)
with open(feature_path, 'w') as f:
    f.write('\n\n'.join(b.rstrip() for b in blocks))
    f.write('\n')

print(f"[cucumber] WRITE  {feature_path}  scenarios={len(re.findall(r'^  Scenario', ''.join(blocks), re.MULTILINE))}")
EOF "$STORY_FILE" "$FEATURE_FILE"

Generate Step Definition Stubs (TypeScript)

FEATURE_FILE="tests/features/user-auth/reset-password.feature"
STEPS_DIR="tests/step-definitions/user-auth"
mkdir -p "$STEPS_DIR"

python3 - <<'EOF'
import re, sys, os

feature_path = sys.argv[1]
steps_dir = sys.argv[2]
feature = open(feature_path).read()

# Collect unique step texts
steps = re.findall(r'^\s+(Given|When|Then|And|But) (.+)$', feature, re.MULTILINE)
seen = set()
unique = []
for keyword, text in steps:
    norm = re.sub(r'"[^"]+"', '"{string}"', text)
    norm = re.sub(r'\b\d+\b', '{int}', norm)
    if norm not in seen:
        seen.add(norm)
        unique.append((keyword if keyword not in ('And','But') else 'Given', norm, text))

# Build TypeScript file
feature_name = os.path.basename(feature_path).replace('.feature','')
out_path = os.path.join(steps_dir, f"{feature_name}.steps.ts")

if os.path.exists(out_path):
    print(f"[cucumber] SKIP  {out_path}  (already exists)")
    sys.exit(0)

lines = [
    "import { Given, When, Then } from '@cucumber/cucumber';",
    "",
]
for keyword, pattern, original in unique:
    fn = keyword.lower()
    # build parameter list from placeholders
    params = []
    if '{string}' in pattern:
        params += [f"arg{i}: string" for i in range(pattern.count('{string}'))]
    if '{int}' in pattern:
        params += [f"n{i}: number" for i in range(pattern.count('{int}'))]
    param_str = ', '.join(params)
    escaped = pattern.replace("'", "\\'")
    lines += [
        f"// {original}",
        f"{fn}('{escaped}', async ({param_str}) => {{",
        f"  // TODO: implement",
        f"  throw new Error('Pending: {escaped}');",
        f"}});",
        "",
    ]

with open(out_path, 'w') as f:
    f.write('\n'.join(lines))

print(f"[cucumber] STUBS  {out_path}  steps={len(unique)}")
EOF "$FEATURE_FILE" "$STEPS_DIR"

Generate Step Definition Stubs (Python / behave)

FEATURE_FILE="tests/features/user_auth/reset_password.feature"
STEPS_DIR="tests/features/user_auth"
mkdir -p "$STEPS_DIR"

python3 - <<'EOF'
import re, sys, os

feature_path = sys.argv[1]
steps_dir = sys.argv[2]
feature = open(feature_path).read()

steps = re.findall(r'^\s+(Given|When|Then|And|But) (.+)$', feature, re.MULTILINE)
seen = set()
unique = []
for keyword, text in steps:
    norm = re.sub(r'"[^"]+"', '"{text}"', text)
    norm = re.sub(r'\b\d+\b', '{n:d}', norm)
    if norm not in seen:
        seen.add(norm)
        unique.append((keyword if keyword not in ('And','But') else 'given', norm, text))

feature_name = os.path.basename(feature_path).replace('.feature','')
out_path = os.path.join(steps_dir, f"{feature_name}_steps.py")

if os.path.exists(out_path):
    print(f"[cucumber] SKIP  {out_path}  (already exists)")
    sys.exit(0)

lines = ["from behave import given, when, then", ""]
for keyword, pattern, original in unique:
    fn = keyword.lower()
    escaped = pattern.replace('"', '\\"')
    lines += [
        f"# {original}",
        f'@{fn}(u"{escaped}")',
        f"def step_impl(context):",
        f'    raise NotImplementedError(u"STEP: {fn} {escaped}")',
        "",
    ]

with open(out_path, 'w') as f:
    f.write('\n'.join(lines))

print(f"[cucumber] STUBS  {out_path}  steps={len(unique)}")
EOF "$FEATURE_FILE" "$STEPS_DIR"

Batch Sync (all stories → all feature files)

find docs/stories -name "*.md" ! -name "_template.md" | while read -r story; do
  EPIC=$(python3 -c "
import re
m = re.search(r'^epic:\s*[\"\'](.*?)[\"\']', open('$story').read(), re.MULTILINE)
print(m.group(1) if m else 'unknown')
")
  SLUG=$(basename "$story" | sed 's/-[0-9]\{14\}-[0-9]\{4\}\.md$//')
  FEATURE_FILE="tests/features/$EPIC/$SLUG.feature"
  # extract-and-write step (see above) ...
  echo "[cucumber] SYNC  $story → $FEATURE_FILE"
done

Playwright + behave Integration

When the stack includes Playwright (requirements.txt contains playwright or behave), step definitions must follow these patterns. Read the QA agent's BDD section for the full antipatterns list.

environment.py template

import json
import threading
from playwright.sync_api import sync_playwright

BASE_URL = "http://localhost:3000"
DEFAULT_GEO = {"latitude": 40.7128, "longitude": -74.0060}

MOCK_FORECAST = {
    "daily": {
        "time": ["2025-01-01","2025-01-02","2025-01-03",
                 "2025-01-04","2025-01-05","2025-01-06","2025-01-07"],
        "temperature_2m_max": [22.1, 18.3, 15.0, 20.5, 25.2, 19.8, 17.4],
        "temperature_2m_min": [12.0, 10.5,  9.3, 13.2, 16.1, 11.4, 10.9],
        "weathercode":        [0,    3,     61,   0,    1,    80,   71 ],
        "precipitation_probability_max": [5, 30, 85, 10, 20, 70, 60],
        "windspeed_10m_max":  [12.0, 20.5, 35.2, 8.4, 15.6, 28.9, 22.3],
        "relative_humidity_2m_max": [55, 72, 90, 48, 62, 85, 78],
    }
}

def before_all(context):
    context.playwright = sync_playwright().start()
    context.browser = context.playwright.chromium.launch()

def after_all(context):
    context.browser.close()
    context.playwright.stop()

def before_scenario(context, scenario):
    context.browser_context = context.browser.new_context(
        permissions=["geolocation"],
        geolocation=DEFAULT_GEO,
    )
    context.page = context.browser_context.new_page()
    context._forecast_event = None

def after_scenario(context, scenario):
    context.page.close()
    context.browser_context.close()

# ── Helpers ────────────────────────────────────────────────────────────────────

def setup_forecast_route(page, error=False, delay_event=None):
    """Network-level Open-Meteo intercept. NEVER overrides window.fetch."""
    def handle(route):
        if delay_event is not None:
            delay_event.wait(timeout=30)
        if error:
            route.fulfill(status=500, content_type="application/json",
                          body='{"error":"service unavailable"}')
        else:
            route.fulfill(status=200, content_type="application/json",
                          body=json.dumps(MOCK_FORECAST))
    page.route("**/api.open-meteo.com/**", handle)

def navigate_and_wait(page):
    page.goto(BASE_URL, wait_until="domcontentloaded")
    page.wait_for_selector(".forecast-card", timeout=10_000)

Browser capability scenarios

# Geolocation granted — default, handled by before_scenario

# Geolocation denied — create context without the permission
context.browser_context = context.browser.new_context()  # no geolocation permission

# Geolocation unsupported — NO Playwright native API; add_init_script is acceptable HERE ONLY
context.page.add_init_script(
    "Object.defineProperty(navigator,'geolocation',{value:undefined,configurable:true});"
)

# Geolocation timeout — NO Playwright native API; add_init_script acceptable HERE ONLY
context.page.add_init_script(
    "navigator.geolocation.getCurrentPosition = function(){};"  # never calls back
)

Loading state (route with threading.Event)

# Setup step — route stays blocked until event is set
event = threading.Event()
setup_forecast_route(context.page, delay_event=event)
context._forecast_event = event

# Assert spinner visible while blocked
spinner = context.page.locator('[role="status"]')
spinner.wait_for(state="visible", timeout=3000)

# Unblock route → cards should appear
context._forecast_event.set()
context.page.wait_for_selector(".forecast-card", timeout=5000)

API error state

setup_forecast_route(context.page, error=True)
# route returns HTTP 500 — app must handle gracefully

Antipatterns checklist (rubber duck will flag these)

Failure Modes

Logging

[cucumber] WRITE   tests/features/user-auth/reset-password.feature  scenarios=3
[cucumber] STUBS   tests/step-definitions/user-auth/reset-password.steps.ts  steps=7
[cucumber] SKIP    tests/step-definitions/user-auth/login.steps.ts  (already exists)
[cucumber] NO_GHERKIN  docs/stories/auth-spike-20250416143000-0002.md  (spike — expected)

SKILL: design-tokens

Purpose

Read and write design tokens in W3C Design Token Community Group (DTCG) format (tokens.json). Emit framework-specific outputs: CSS custom properties, Tailwind config, and Mantine theme object. The tokens.json in docs/design/identity/ is the canonical source of truth; all framework outputs are derived and regenerated — never manually edited.

Token File: docs/design/identity/tokens.json

W3C DTCG format. Each token is an object with $value and $type:

{
  "$schema": "https://design-tokens.org/schema/v1.0.0",
  "_meta": { "status": "draft", "version": "1.0.0" },

  "color": {
    "brand": {
      "primary":   { "$value": "#2563eb", "$type": "color" },
      "secondary": { "$value": "#7c3aed", "$type": "color" },
      "accent":    { "$value": "#0ea5e9", "$type": "color" }
    },
    "semantic": {
      "success": { "$value": "#16a34a", "$type": "color" },
      "warning": { "$value": "#d97706", "$type": "color" },
      "error":   { "$value": "#dc2626", "$type": "color" },
      "info":    { "$value": "#0284c7", "$type": "color" }
    },
    "neutral": {
      "50":  { "$value": "#f8fafc", "$type": "color" },
      "500": { "$value": "#64748b", "$type": "color" },
      "900": { "$value": "#0f172a", "$type": "color" }
    },
    "surface": {
      "background": { "$value": "#ffffff", "$type": "color" },
      "foreground": { "$value": "#0f172a", "$type": "color" },
      "muted":      { "$value": "#f1f5f9", "$type": "color" },
      "border":     { "$value": "#e2e8f0", "$type": "color" }
    }
  },

  "typography": {
    "fontFamily": {
      "sans": { "$value": "Inter, system-ui, sans-serif", "$type": "fontFamily" },
      "mono": { "$value": "JetBrains Mono, monospace",   "$type": "fontFamily" }
    },
    "fontSize": {
      "sm":   { "$value": "0.875rem", "$type": "dimension" },
      "base": { "$value": "1rem",     "$type": "dimension" },
      "lg":   { "$value": "1.125rem", "$type": "dimension" },
      "xl":   { "$value": "1.25rem",  "$type": "dimension" },
      "2xl":  { "$value": "1.5rem",   "$type": "dimension" },
      "4xl":  { "$value": "2.25rem",  "$type": "dimension" }
    }
  },

  "spacing": {
    "1": { "$value": "0.25rem", "$type": "dimension" },
    "2": { "$value": "0.5rem",  "$type": "dimension" },
    "4": { "$value": "1rem",    "$type": "dimension" },
    "8": { "$value": "2rem",    "$type": "dimension" }
  },

  "radius": {
    "sm":   { "$value": "0.125rem", "$type": "dimension" },
    "md":   { "$value": "0.375rem", "$type": "dimension" },
    "lg":   { "$value": "0.5rem",   "$type": "dimension" },
    "full": { "$value": "9999px",   "$type": "dimension" }
  },

  "shadow": {
    "sm": { "$value": "0 1px 2px 0 rgb(0 0 0 / 0.05)", "$type": "shadow" },
    "md": { "$value": "0 4px 6px -1px rgb(0 0 0 / 0.1)", "$type": "shadow" },
    "lg": { "$value": "0 10px 15px -3px rgb(0 0 0 / 0.1)", "$type": "shadow" }
  }
}

Emit: CSS Custom Properties

Output to docs/design/identity/tokens.css:

import json, re

def flatten(obj, prefix=""):
    result = {}
    for k, v in obj.items():
        if k.startswith("$") or k.startswith("_"):
            continue
        key = f"{prefix}-{k}" if prefix else k
        if isinstance(v, dict) and "$value" in v:
            result[key] = v["$value"]
        elif isinstance(v, dict):
            result.update(flatten(v, key))
    return result

tokens = json.load(open("docs/design/identity/tokens.json"))
flat = flatten(tokens)

lines = [":root {"]
for name, value in sorted(flat.items()):
    css_var = "--" + name.replace(".", "-")
    lines.append(f"  {css_var}: {value};")
lines.append("}")

with open("docs/design/identity/tokens.css", "w") as f:
    f.write("\n".join(lines) + "\n")

print(f"[design-tokens] CSS  docs/design/identity/tokens.css  vars={len(flat)}")

Emit: Tailwind Config

Output to docs/design/identity/tailwind.tokens.js:

import json

tokens = json.load(open("docs/design/identity/tokens.json"))

def extract_colors():
    result = {}
    for group, values in tokens.get("color", {}).items():
        result[group] = {}
        for name, token in values.items():
            if "$value" in token:
                result[group][name] = token["$value"]
    return result

colors = extract_colors()
font_family = {
    k: v["$value"]
    for k, v in tokens.get("typography", {}).get("fontFamily", {}).items()
}

config = f"""/** @type {{import('tailwindcss').Config}} */
// AUTO-GENERATED — edit docs/design/identity/tokens.json, not this file
module.exports = {{
  theme: {{
    extend: {{
      colors: {json.dumps(colors, indent(6))},
      fontFamily: {json.dumps(font_family, indent(6))},
    }},
  }},
}};
"""

with open("docs/design/identity/tailwind.tokens.js", "w") as f:
    f.write(config)

print("[design-tokens] TAILWIND  docs/design/identity/tailwind.tokens.js")

Emit: Mantine Theme

Output to docs/design/identity/mantine.theme.ts:

import json

tokens = json.load(open("docs/design/identity/tokens.json"))

primary = tokens["color"]["brand"]["primary"]["$value"]
secondary = tokens["color"]["brand"]["secondary"]["$value"]

theme = f"""// AUTO-GENERATED — edit docs/design/identity/tokens.json, not this file
import {{ createTheme }} from '@mantine/core';

export const theme = createTheme({{
  primaryColor: 'brand',
  colors: {{
    brand: [
      '{tokens["color"]["neutral"]["50"]["$value"]}',
      '{tokens["color"]["neutral"]["100"]["$value"] if "100" in tokens["color"]["neutral"] else "#f1f5f9"}',
      '{tokens["color"]["neutral"]["200"]["$value"] if "200" in tokens["color"]["neutral"] else "#e2e8f0"}',
      '{tokens["color"]["neutral"]["300"]["$value"] if "300" in tokens["color"]["neutral"] else "#cbd5e1"}',
      '{tokens["color"]["neutral"]["400"]["$value"] if "400" in tokens["color"]["neutral"] else "#94a3b8"}',
      '{tokens["color"]["neutral"]["500"]["$value"]}',
      '{primary}',
      '{tokens["color"]["neutral"]["700"]["$value"] if "700" in tokens["color"]["neutral"] else "#334155"}',
      '{tokens["color"]["neutral"]["800"]["$value"] if "800" in tokens["color"]["neutral"] else "#1e293b"}',
      '{tokens["color"]["neutral"]["900"]["$value"]}',
    ],
  }},
  fontFamily: '{tokens["typography"]["fontFamily"]["sans"]["$value"]}',
  fontFamilyMonospace: '{tokens["typography"]["fontFamily"]["mono"]["$value"]}',
}});
"""

with open("docs/design/identity/mantine.theme.ts", "w") as f:
    f.write(theme)

print("[design-tokens] MANTINE  docs/design/identity/mantine.theme.ts")

Emit: Terminal Theme (tui target)

When design.target is tui, emit docs/design/identity/terminal-theme.json from tokens.json instead of the CSS/Tailwind/Mantine outputs. Map each color role to an ANSI-256 index (and the hex) plus a lipgloss style name, and record the foreground/background pairs with their contrast ratios so the a11y auditor can flag any pair under WCAG 2.2 AA. Shape:

{
  "roles": {
    "primary":    { "fg": "#7aa2f7", "ansi256": 111, "lipgloss": "primary" },
    "muted":      { "fg": "#565f89", "ansi256": 60,  "lipgloss": "muted" },
    "accent":     { "fg": "#bb9af7", "ansi256": 141, "lipgloss": "accent" },
    "error":      { "fg": "#f7768e", "ansi256": 204, "lipgloss": "error" },
    "success":    { "fg": "#9ece6a", "ansi256": 149, "lipgloss": "success" },
    "background": { "bg": "#1a1b26", "ansi256": 234 },
    "foreground": { "fg": "#c0caf5", "ansi256": 189 }
  },
  "pairs": [
    { "role": "foreground", "on": "background", "contrast": 12.6 },
    { "role": "muted",      "on": "background", "contrast": 3.4 }
  ]
}

Run All Emitters

python3 - <<'EOF'
# Run all three emitters in sequence
# (inline the three scripts above, or import from scripts/emit-tokens.py)
EOF

Update Tokens (read-write)

To update a single token value:

import json, sys

tokens = json.load(open("docs/design/identity/tokens.json"))
# Set tokens["color"]["brand"]["primary"]["$value"] = "#1d4ed8"
# Write back, then re-run all emitters
json.dump(tokens, open("docs/design/identity/tokens.json", "w"), indent=2)

Always re-emit all framework outputs after any token change.

Failure Modes

Logging

[design-tokens] READ    docs/design/identity/tokens.json  tokens=47
[design-tokens] CSS     docs/design/identity/tokens.css   vars=47
[design-tokens] TAILWIND docs/design/identity/tailwind.tokens.js
[design-tokens] MANTINE  docs/design/identity/mantine.theme.ts
[design-tokens] MISSING_TOKEN  color.neutral.100  — using placeholder

SKILL: Docker Patterns

Multi-Stage Dockerfile Pattern

# syntax=docker/dockerfile:1
FROM node:22-alpine AS base
WORKDIR /app

FROM base AS deps
COPY package*.json ./
RUN --mount=type=cache,target=/root/.npm \
    npm ci --only=production

FROM base AS dev-deps
COPY package*.json ./
RUN --mount=type=cache,target=/root/.npm \
    npm ci

FROM base AS build
COPY --from=dev-deps /app/node_modules ./node_modules
COPY . .
RUN npm run build

FROM gcr.io/distroless/nodejs22-debian12 AS production
WORKDIR /app
USER 1001
COPY --from=deps /app/node_modules ./node_modules
COPY --from=build /app/dist ./dist
EXPOSE 3000
CMD ["dist/main.js"]

docker-compose Health Check Pattern

services:
  app:
    build:
      context: .
      target: production
    ports:
      - "3000:3000"
    environment:
      DATABASE_URL: postgres://postgres:pass@db:5432/app
    depends_on:
      db:
        condition: service_healthy
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
      interval: 5s
      timeout: 5s
      retries: 5
      start_period: 10s

  db:
    image: postgres:16-alpine
    environment:
      POSTGRES_PASSWORD: pass
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 2s
      timeout: 5s
      retries: 10

.dockerignore

node_modules
.git
.github
dist
build
coverage
.next
*.log
.env*
!.env.example
README.md
docs
tests

Key Rules

• ALWAYS use multi-stage builds for production images.
• ALWAYS run as non-root user (USER 1001 or named user).
• ALWAYS add health checks to all services.
• NEVER copy .env files into images.
• Use --mount=type=cache for package manager caches.
• Use distroless or alpine base images.
• Use docker compose up -d --wait to wait for health checks.

Verification

# Build test
docker build --target production -t test-image .

# Security scan
docker run --rm -v /var/run/docker.sock:/var/run/docker.sock \
  aquasec/trivy:latest image test-image

# Start and verify health
docker compose up -d --wait
docker compose ps

SKILL: FinOps Review

Purpose

Identify and annotate the cloud cost implications of architectural decisions.

Cost Driver Categories

Compute

• Lambda/Functions: invocation count x duration x memory
• EC2/VMs: instance type x hours + data transfer
• Containers: CPU/memory reservation x hours
• Edge functions: request count x execution time

Storage

• Object storage (S3/GCS/Blob): GB stored + requests + egress
• Database: instance size + storage + IOPS + backups
• Cache: node size x hours

Networking

• Egress: GB transferred out (most expensive)
• CDN: requests + GB served
• Load balancer: hours + LCU

Third-party APIs

• Stripe: 2.9% + $0.30 per transaction
• Supabase: row reads/writes, storage, Edge Function invocations
• Vercel: bandwidth, function invocations, seats

Annotation Format (Terraform)

resource "aws_db_instance" "main" {
  # finops: ~$180/mo (db.t3.medium, 100GB gp3, 1 AZ)
  # finops: scale-trigger: >70% CPU or >80% storage
  instance_class = "db.t3.medium"
  ...
}

Architecture Review Questions

1. What scales with user count? What scales with data volume?
2. Are there N+1 API calls that will cost $$ at scale?
3. Is egress minimized? (Cache aggressively, colocate services)
4. Are reserved instances/savings plans applicable?
5. What is the cost at 10x current load?

Monthly Estimate Template

## Cost Estimate: {Feature}

| Service | Config | Est. Monthly |
|---------|--------|-------------|
| RDS PostgreSQL | db.t3.medium, 100GB | $180 |
| ElastiCache Redis | cache.t3.micro | $25 |
| ECS Fargate | 2 tasks, 0.5 vCPU, 1GB | $30 |
| ALB | 1 ALB, ~1M requests | $20 |
| **Total** | | **~$255/mo** |

Scales linearly with: [traffic volume / data volume]

SKILL: gh-issues

Purpose

Create, read, update, and link GitHub Issues as first-class story artifacts. Agents use this skill to manage issue lifecycle — from PO story creation through QA closure — without human intervention.

Inputs

Outputs

Create an Issue

# Capture issue number and URL
RESULT=$(gh issue create \
  --title "{title}" \
  --body-file "{body_file}" \
  --label "{labels}" \
  --milestone "{milestone}" \
  --json number,url,id)

ISSUE_NUMBER=$(echo "$RESULT" | python3 -c "import sys,json; d=json.load(sys.stdin); print(d['number'])")
ISSUE_URL=$(echo "$RESULT"    | python3 -c "import sys,json; d=json.load(sys.stdin); print(d['url'])")
ISSUE_NODE=$(echo "$RESULT"   | python3 -c "import sys,json; d=json.load(sys.stdin); print(d['id'])")

View an Issue

gh issue view {issue_number} --json number,title,state,labels,body

Edit Labels and Assignee

# Add label, remove old phase label
gh issue edit {issue_number} \
  --add-label "phase:architect" \
  --remove-label "phase:discover"

# Assign to current actor
gh issue edit {issue_number} --add-assignee "@me"

Add a Comment

gh issue comment {issue_number} \
  --body "{message}"

Comment conventions by role:

Close an Issue

# Close with final validation summary
gh issue close {issue_number} \
  --comment "All acceptance criteria passing. Validation: {summary}"

List Issues

# All open issues for current phase
gh issue list --label "phase:implement" --state open --json number,title,labels

# Blocked issues
gh issue list --label "blocked" --state open

Link Issues (parent / blocks)

GitHub Issues has no native parent field — use body references and labels:

# In the child issue body, add:
# "Closes #{parent_number}" → auto-closes parent when child closes
# "Part of #{epic_issue_number}"

# For blocking relationships, comment on the blocked issue:
gh issue comment {blocked_number} \
  --body "Blocked by #{blocker_number} — {reason}"
gh issue edit {blocked_number} --add-label "blocked"

Failure Modes

Logging

Always log after every gh issue mutation:

[gh-issues] CREATE  #42  "User can reset password"  labels=[type:feature,priority:high]
[gh-issues] COMMENT #42  phase:implement start
[gh-issues] CLOSE   #42  all criteria passing

Format: [gh-issues] {ACTION} #{number} {description}

SKILL: gh-labels-milestones

Purpose

Bootstrap and sync GitHub labels and milestones idempotently. Labels and milestones are created if absent; existing ones are updated if color or description differs. Never delete — only add or update.

Label Bootstrap

Use this at project start (maple labels) and in CI to guarantee label state.

# Idempotent label create-or-update
upsert_label() {
  local name="$1" color="$2" description="$3"
  if gh label list --json name --jq '.[].name' | grep -qx "$name"; then
    gh label edit "$name" --color "$color" --description "$description"
  else
    gh label create "$name" --color "$color" --description "$description"
  fi
}

Label Groups

Phase Labels (pipeline position)

upsert_label "phase:discover"   "0075ca" "Phase 1: Discovery"
upsert_label "phase:architect"  "0075ca" "Phase 2: Architecture"
upsert_label "phase:plan"       "0075ca" "Phase 3: Planning"
upsert_label "phase:infra"      "0075ca" "Phase 4: Infrastructure"
upsert_label "phase:implement"  "0075ca" "Phase 5: Implementation"
upsert_label "phase:validate"   "0075ca" "Phase 6: Validation"
upsert_label "phase:document"   "0075ca" "Phase 7: Documentation"
upsert_label "phase:done"       "0075ca" "Phase 8: Complete"

Type Labels (work classification)

upsert_label "type:feature"     "0052cc" "New capability"
upsert_label "type:bug"         "d73a4a" "Defect"
upsert_label "type:spike"       "e4e669" "Research / time-boxed exploration"
upsert_label "type:chore"       "ededed" "Non-functional maintenance"
upsert_label "type:refactor"    "ededed" "Code restructuring, no behavior change"
upsert_label "type:docs"        "0075ca" "Documentation only"

Priority Labels (MoSCoW)

upsert_label "priority:critical" "b60205" "Must ship — blocks launch"
upsert_label "priority:high"     "e11d48" "Must have"
upsert_label "priority:medium"   "f97316" "Should have"
upsert_label "priority:low"      "84cc16" "Could have"
upsert_label "priority:wontfix"  "ffffff" "Won't have this cycle"

Spec / Story Kit Labels

upsert_label "spec:problem"     "7057ff" "Problem statement written"
upsert_label "spec:approved"    "7057ff" "Spec approved by PO"
upsert_label "spec:in-review"   "7057ff" "Spec under review"

Design Labels

upsert_label "design:pending"      "fbca04" "Awaiting design"
upsert_label "design:in-progress"  "fbca04" "Design work active"
upsert_label "design:approved"     "fbca04" "Design approved"
upsert_label "design:a11y-passed"  "fbca04" "Accessibility review passed"

ADR Labels

upsert_label "adr:required"    "5319e7" "ADR must be written before implementation"
upsert_label "adr:in-progress" "5319e7" "ADR being authored"
upsert_label "adr:complete"    "5319e7" "ADR accepted"
upsert_label "adr:rejected"    "5319e7" "ADR rejected — see comments"

UI / Accessibility Labels

upsert_label "ui:required"     "fef2c0" "Has UI surface — design review required"
upsert_label "ui:in-progress"  "fef2c0" "UI implementation active"
upsert_label "ui:complete"     "fef2c0" "UI complete and reviewed"

Status Labels

upsert_label "in-progress" "0052cc" "Work started"
upsert_label "blocked"     "b60205" "Blocked — needs human"
upsert_label "validated"   "0e8a16" "All tests pass"
upsert_label "tdd:red"     "d73a4a" "Failing test written"
upsert_label "tdd:green"   "0e8a16" "Tests passing"

Milestone Bootstrap

# Idempotent milestone create
upsert_milestone() {
  local title="$1" due="$2" description="$3"
  EXISTING=$(gh api "repos/{owner}/{repo}/milestones" \
    --jq ".[] | select(.title == \"$title\") | .number" 2>/dev/null)
  if [ -n "$EXISTING" ]; then
    gh api "repos/{owner}/{repo}/milestones/$EXISTING" \
      -X PATCH \
      -f title="$title" \
      -f due_on="${due}T00:00:00Z" \
      -f description="$description"
  else
    gh api "repos/{owner}/{repo}/milestones" \
      -X POST \
      -f title="$title" \
      -f due_on="${due}T00:00:00Z" \
      -f description="$description"
  fi
}

# Example usage
upsert_milestone "v1.0" "2025-12-31" "Initial release"

Assign Labels to an Issue

# Add labels (idempotent — gh ignores if already present)
gh issue edit {issue_number} \
  --add-label "type:feature,priority:high,phase:discover"

# Remove a specific label
gh issue edit {issue_number} --remove-label "phase:discover"

Failure Modes

Logging

[gh-labels] UPSERT  label="type:feature"    color=0052cc
[gh-labels] SKIP    label="priority:high"   (unchanged)
[gh-milestones] CREATE  "v1.0"  due=2025-12-31
[gh-milestones] SKIP    "v1.0"  already exists

SKILL: gh-projects

Purpose

Manage GitHub Projects v2 board operations: add issues as cards, update field values (status, type, ADR required), and query board state. Uses gh project CLI where available; falls back to gh api graphql for operations the CLI does not expose.

Inputs

Read project config

PROJECT_NUMBER=$(python3 -c "
import sys
for line in open('project.config.yaml'):
    if 'project_number:' in line:
        print(line.split(':')[1].strip())
        break
")

PROJECT_NODE=$(python3 -c "
import sys
for line in open('project.config.yaml'):
    if 'project_node_id:' in line:
        print(line.split(':', 1)[1].strip())
        break
")

Add an Issue to the Project Board

# CLI (preferred)
gh project item-add "$PROJECT_NUMBER" \
  --owner "{owner}" \
  --url "https://github.com/{owner}/{repo}/issues/{issue_number}"

# GraphQL fallback (when CLI unavailable or for automation)
gh api graphql -f query='
  mutation($project: ID!, $content: ID!) {
    addProjectV2ItemById(input: {projectId: $project, contentId: $content}) {
      item { id }
    }
  }' \
  -f project="$PROJECT_NODE" \
  -f content="{issue_node_id}" \
  --jq '.data.addProjectV2ItemById.item.id'

Save the returned item_id — required for field updates.

Get Field and Option IDs

Field updates require the field's node ID and the option's node ID (for single-select fields).

FIELDS=$(gh api graphql -f query='
  query($project: ID!) {
    node(id: $project) {
      ... on ProjectV2 {
        fields(first: 20) {
          nodes {
            ... on ProjectV2Field { id name }
            ... on ProjectV2SingleSelectField {
              id name
              options { id name }
            }
          }
        }
      }
    }
  }' \
  -f project="$PROJECT_NODE")

# Extract field ID by name
FIELD_ID=$(echo "$FIELDS" | python3 -c "
import sys, json
d = json.load(sys.stdin)
for f in d['data']['node']['fields']['nodes']:
    if f.get('name') == '{field_name}':
        print(f['id'])
        break
")

# Extract option ID by value (single-select fields)
OPTION_ID=$(echo "$FIELDS" | python3 -c "
import sys, json
d = json.load(sys.stdin)
for f in d['data']['node']['fields']['nodes']:
    if f.get('name') == '{field_name}':
        for opt in f.get('options', []):
            if opt['name'] == '{field_value}':
                print(opt['id'])
                break
")

Update a Single-Select Field (Status, Type, ADR Required)

gh api graphql -f query='
  mutation($project: ID!, $item: ID!, $field: ID!, $option: String!) {
    updateProjectV2ItemFieldValue(input: {
      projectId: $project
      itemId: $item
      fieldId: $field
      value: { singleSelectOptionId: $option }
    }) {
      projectV2Item { id }
    }
  }' \
  -f project="$PROJECT_NODE" \
  -f item="{item_id}" \
  -f field="$FIELD_ID" \
  -f option="$OPTION_ID"

Update a Text Field (Epic, Specialist)

gh api graphql -f query='
  mutation($project: ID!, $item: ID!, $field: ID!, $value: String!) {
    updateProjectV2ItemFieldValue(input: {
      projectId: $project
      itemId: $item
      fieldId: $field
      value: { text: $value }
    }) {
      projectV2Item { id }
    }
  }' \
  -f project="$PROJECT_NODE" \
  -f item="{item_id}" \
  -f field="$FIELD_ID" \
  -f value="{text_value}"

Standard Field Updates by Pipeline Phase

Query Board State

# List all items with status
gh project item-list "$PROJECT_NUMBER" \
  --owner "{owner}" \
  --format json \
  --jq '.items[] | {id, title: .content.title, status: .fieldValues[] | select(.field.name=="Status") | .name}'

Failure Modes

Logging

[gh-projects] ADD    #42  → project #{project_number}  item_id={id}
[gh-projects] UPDATE #42  field=Status  value="In progress"
[gh-projects] SKIP   #42  already on board

SKILL: gherkin-authoring

Purpose

Produce valid, consistently named Gherkin story files. Handles ID allocation, timestamp generation, filename construction, tag formatting, and scenario validation. Used by the product-owner agent whenever a new story is written or updated.

Story File Naming Convention

<epic-slug>-<story-slug>-<timestamp>-<NNNN>.md

Full example: user-auth-reset-password-20250416143000-0003.md

Allocate the Next Story ID

# Count existing stories for an epic to get next sequential ID
EPIC="user-auth"
NEXT_ID=$(ls docs/stories/${EPIC}-* 2>/dev/null \
  | grep -oE '\-[0-9]{4}\.md$' \
  | grep -oE '[0-9]{4}' \
  | sort -n | tail -1 \
  | python3 -c "import sys; n=sys.stdin.read().strip(); print(f'{int(n)+1:04d}' if n else '0001')")
[ -z "$NEXT_ID" ] && NEXT_ID="0001"
echo "$NEXT_ID"

Generate Filename

EPIC="user-auth"
STORY="reset-password"
TS=$(date -u +"%Y%m%d%H%M%S")
ID="$NEXT_ID"   # from allocation step above
FILENAME="${EPIC}-${STORY}-${TS}-${ID}.md"
echo "$FILENAME"   # user-auth-reset-password-20250416143000-0001.md

Story File Template

Every story file must contain:

---
id: "{EPIC}-{NNNN}"
title: "{Human-readable story title}"
epic: "{epic-slug}"
priority: "high|medium|low|critical"
ui: false
adr_required: false
milestone: "{milestone name}"
labels:
  - "type:feature"
  - "priority:high"
  - "phase:discover"
issue_number: null
issue_url: null
---

## Story

**As a** {actor},
**I want** {capability},
**so that** {business outcome}.

## Acceptance Criteria

```gherkin
@story:{EPIC}-{NNNN} @epic:{epic-slug} @priority:{level}
Feature: {Feature title}

  Scenario: {scenario title}
    Given {precondition}
    When {action}
    Then {expected outcome}

Definition of Done

• All Gherkin scenarios have passing step implementations
• Unit tests written and passing
• Integration tests written and passing (if applicable)
• Code reviewed and approved
• No regressions in related features
• Documentation updated (if applicable)

ADR Links

## Gherkin Validation Rules

Before writing a scenario, verify:

1. **Single responsibility**: each `Scenario` tests exactly one behavior.
2. **Given-When-Then order**: never skip or reorder.
3. **No implementation detail in steps**: steps describe intent, not code.
4. **Declarative steps**: `Given the user is logged in` ✓ — `Given I call POST /auth/login` ✗
5. **Tags present**: `@story:`, `@epic:`, `@priority:` required on every Feature block.
6. **No `And` as first step**: `And` is only valid after a `Given`, `When`, or `Then`.

## Background Block (shared preconditions)

```gherkin
Feature: Password Reset

  Background:
    Given the user has a verified account
    And the account is not locked

  Scenario: Successful reset request
    When the user submits their email address
    Then a reset link is sent to that address

Use Background when 2+ scenarios share the same preconditions.

Scenario Outline (data-driven)

  Scenario Outline: Reject invalid email formats
    When the user submits "<email>"
    Then they see a validation error "<message>"

    Examples:
      | email        | message                  |
      | notanemail   | Invalid email format     |
      | @nodomain    | Invalid email format     |
      | a@b          | Domain must have TLD     |

Tags Reference

Failure Modes

Logging

[gherkin] ALLOCATE  epic=user-auth  next_id=0003
[gherkin] CREATE    docs/stories/user-auth-reset-password-20250416143000-0003.md
[gherkin] VALIDATE  scenarios=3  tags=ok  structure=ok

SKILL: GitHub CLI

Repo Context (always run first)

# Who am I, what repo am I in
gh auth status
gh repo view --json name,owner,defaultBranchRef,url,isPrivate

# Open issues + PRs at a glance
gh issue list --state open --limit 20 --json number,title,labels,assignees
gh pr list --state open --json number,title,headRefName,statusCheckRollup

Issues as Tasks

Create

# Feature story
gh issue create \
  --title "feat: {title}" \
  --body-file docs/stories/{slug}/Story.md \
  --label "type:feature,priority:high,phase:discover" \
  --milestone "v1.0" \
  --assignee "@me"

# Bug
gh issue create \
  --title "fix: {title}" \
  --body "## Steps to reproduce\n{steps}\n\n## Expected\n{expected}\n\n## Actual\n{actual}" \
  --label "type:bug,priority:high"

# Task (sub-work, no story file)
gh issue create \
  --title "task: {title}" \
  --body "{description}" \
  --label "type:task" \
  --assignee "@me"

Read

gh issue view {number}
gh issue view {number} --json number,title,state,body,labels,assignees,comments,milestone

# Search
gh issue list --search "label:blocked" --state open
gh issue list --search "assignee:@me is:open"
gh issue list --search "phase:implement" --label "tdd:red"
gh issue list --state open --label "type:feature" --milestone "v1.0"

Update

# Phase transition
gh issue edit {number} \
  --add-label "phase:architect" \
  --remove-label "phase:discover"

# Assign / unassign
gh issue edit {number} --add-assignee "@me"
gh issue edit {number} --remove-assignee "{login}"

# Change milestone
gh issue edit {number} --milestone "v2.0"

# Block / unblock
gh issue edit {number} --add-label "blocked"
gh issue edit {number} --remove-label "blocked"

Comment

gh issue comment {number} --body "{message}"

# Phase lifecycle comments (standard format)
gh issue comment {number} --body "Phase {N} {NAME}: starting. Target artifacts: {paths}"
gh issue comment {number} --body "Phase {N} {NAME}: complete. Artifacts: {paths}"
gh issue comment {number} --body "RED: Failing test at {path} — {message}"
gh issue comment {number} --body "GREEN: {count} tests passing."
gh issue comment {number} --body "BLOCKED: {agent} failed 3x on {task}. Human required."

Close

gh issue close {number} --comment "Acceptance criteria passing. Validation: {summary}"
gh issue close {number} --reason "not planned"

Pull Requests

# Create PR (always draft first)
gh pr create \
  --title "feat: {description}" \
  --body "## Summary\n{summary}\n\nCloses #{issue_number}" \
  --base main \
  --draft

# Mark ready when all gates pass
gh pr ready {number}

# View PR + CI status
gh pr view {number} --json number,title,state,reviews,statusCheckRollup,files

# Request review
gh pr edit {number} --add-reviewer "{login}"

# Check CI on PR
gh pr checks {number}

# Merge (squash — preferred)
gh pr merge {number} --squash --subject "feat: {description} (#{issue_number})" --delete-branch

# Review
gh pr review {number} --approve --body "LGTM"
gh pr review {number} --request-changes --body "{feedback}"

Branches

# List branches
gh api repos/{owner}/{repo}/branches --jq '.[].name'

# Create via API (when not in git context)
gh api repos/{owner}/{repo}/git/refs \
  -f ref="refs/heads/feat/{slug}" \
  -f sha="$(gh api repos/{owner}/{repo}/git/ref/heads/main --jq '.object.sha')"

# Delete remote branch
gh api -X DELETE repos/{owner}/{repo}/git/refs/heads/feat/{slug}

# Branch protection status
gh api repos/{owner}/{repo}/branches/main/protection

Actions / CI

# List recent runs
gh run list --limit 10
gh run list --workflow ci.yml --branch main --limit 5

# Watch a run live
gh run watch {run-id}

# View failed run details
gh run view {run-id} --log-failed

# Trigger workflow manually
gh workflow run {workflow-file} --ref main

# Re-run failed jobs only
gh run rerun {run-id} --failed

# Download artifact
gh run download {run-id} --name {artifact-name} --dir ./artifacts

Repo Inspection

# Full repo metadata
gh repo view --json name,owner,description,topics,visibility,defaultBranchRef,\
licenseInfo,stargazerCount,forkCount,createdAt,updatedAt

# Collaborators
gh api repos/{owner}/{repo}/collaborators --jq '.[].login'

# Repo settings
gh api repos/{owner}/{repo} --jq '{private:.private,hasIssues:.has_issues,hasWiki:.has_wiki}'

# Topics
gh repo edit --add-topic "{topic}"

# Clone URL
gh repo view --json sshUrl,url

# Releases
gh release list --limit 5
gh release view {tag}

Labels & Milestones

# Bootstrap MAPLE labels (idempotent)
bash scripts/bootstrap-labels.sh

# List labels
gh label list

# Create label
gh label create "type:task" --color "0075ca" --description "Work item"

# Create milestone
gh api repos/{owner}/{repo}/milestones \
  -f title="v1.0" \
  -f description="First release" \
  -f due_on="2026-06-01T00:00:00Z"

# List milestones
gh api repos/{owner}/{repo}/milestones --jq '.[] | {number:.number,title:.title,open:.open_issues}'

Search

# Search code in repo
gh search code "{query}" --repo {owner}/{repo} --json path,url

# Search issues across GitHub
gh search issues "{query}" --repo {owner}/{repo} --json number,title,state

# Search PRs
gh search prs "{query}" --repo {owner}/{repo} --state open

Issue Lifecycle (MAPLE Standard)

Failure Modes

humanizer skill

Polish text by removing detectable AI-generated writing patterns. Ideal for finalizing documentation, commit messages, comments, and any prose before merging.

When to use

• After @docs generates feature documentation
• Before committing code (check commit messages and comments)
• Polishing README updates, CHANGELOG entries, or runbooks
• Making AI-assisted prose sound more natural
• Manual voice calibration for brand consistency

How to invoke

/humanizer

[paste your text here]

Or ask directly in chat:

Please humanize this text: [your text]

Voice calibration (optional)

Provide a sample of your own writing for the skill to match your style:

/humanizer

Here's a sample of my writing for voice matching:
[paste 2-3 paragraphs of your own writing]

Now humanize this text:
[paste AI text to humanize]

What it detects

The skill checks for 29 AI-writing patterns, including:

• Significance inflation — "marking a pivotal moment in the evolution of..." → "was established in 1989"
• Notability name-dropping — Lists of citations → specific examples with context
• Superficial -ing phrases — "symbolizing, reflecting, showcasing" → active explanations
• Promotional language — Corporate jargon → straightforward description
• Overuse of 'indeed' — Filler words → tighter prose
• Transition abuse — Excessive "Furthermore, In conclusion..." → natural flow
• Hedging redundancy — "arguably, in some sense, it could be argued..." → clarity
• Rare word stacking — Thesaurus abuse → common vocabulary
• False expert mode — Generic expertise → grounded examples
• Generalist fluff — "many fields, various domains..." → specific scope

Integration with MAPLE

• Auto-call after Phase 7 (DOCUMENT) if humanize: true in feature story frontmatter
• Manual: invoke at any phase before merge
• Works across all harnesses (Claude Code, OpenCode, Cursor, Copilot CLI)

Output

Returns a humanized version of your text with:

1. First pass: Remove identified AI patterns
2. Final audit: "Obviously AI generated?" check
3. Second rewrite: Catch lingering AI-isms

Further reading

• Wikipedia: Signs of AI writing
• Humanizer repo

SKILL: Jupyter Notebook Patterns

Notebook Structure

Cells should follow this order:

1. Setup — imports, configuration, constants
2. Data Loading — load raw data with validation
3. EDA — exploratory data analysis, distributions, correlations
4. Preprocessing — cleaning, feature engineering
5. Modeling — model training and evaluation
6. Visualization — charts and figures
7. Conclusions — findings summary, next steps

Parameterized Execution with Papermill

# In notebook cell tagged with "parameters":
# Click: View -> Cell Toolbar -> Tags -> add "parameters" tag

dataset = "data/train.csv"  # papermill will override this
output_dir = "outputs"
n_estimators = 100
random_state = 42

# Execute with papermill
papermill input.ipynb output.ipynb \
  -p dataset "data/test.csv" \
  -p n_estimators 200 \
  -p random_state 0

Programmatic Notebook Creation

import nbformat as nbf

nb = nbf.v4.new_notebook()
nb.cells = [
    nbf.v4.new_markdown_cell("# Analysis: {Title}"),
    nbf.v4.new_code_cell("import pandas as pd\nimport numpy as np"),
    nbf.v4.new_code_cell("df = pd.read_csv('data.csv')\ndf.head()"),
]

with open('analysis.ipynb', 'w') as f:
    nbf.write(nb, f)

Export

# To HTML (with outputs)
jupyter nbconvert --to html --execute notebook.ipynb

# To PDF
jupyter nbconvert --to pdf --execute notebook.ipynb

# Execute in place
jupyter nbconvert --to notebook --execute --inplace notebook.ipynb

Git Hygiene

# Clear outputs before commit
jupyter nbconvert --to notebook --ClearOutputPreprocessor.enabled=True \
  --inplace notebook.ipynb

# Or use nbstripout (installs as git filter)
pip install nbstripout
nbstripout --install

Rules

• Restart kernel and run all cells before committing.
• Clear all outputs before git commit.
• Tag parameter cells for papermill.
• Each notebook should be self-contained and reproducible.
• Include random_state parameter for reproducibility.
• Use relative paths for data files.

karpathy-audit skill

Audit PRs and code changes against Andrej Karpathy's 4 principles for reducing LLM coding mistakes.

When to use

• Auto-invoked after Phase 5 (IMPLEMENT) before advancing to Phase 6 (VALIDATE)
• Manual invocation: /karpathy-audit or @karpathy-audit in chat
• At any phase when you want to assess code quality against the principles

The 4 Principles

1. Think Before Coding

Don't assume. Don't hide confusion. Surface tradeoffs.

• State assumptions explicitly. If uncertain, ask.
• Present multiple interpretations—don't pick silently.
• If a simpler approach exists, say so. Push back when warranted.
• Stop when confused. Name what's unclear and ask.

2. Simplicity First

Minimum code that solves the problem. Nothing speculative.

• No features beyond what was asked.
• No abstractions for single-use code.
• No "flexibility" or "configurability" that wasn't requested.
• No error handling for impossible scenarios.
• If 200 lines could be 50, rewrite it.

3. Surgical Changes

Touch only what you must. Clean up only your own mess.

• Don't "improve" adjacent code, comments, or formatting.
• Don't refactor things that aren't broken.
• Match existing style, even if you'd do it differently.
• Only remove imports/variables/functions that YOUR changes made unused.

4. Goal-Driven Execution

Define success criteria. Loop until verified.

• Transform tasks into verifiable goals: tests before code.
• State a brief plan with explicit success criteria.
• Loop independently until verified.

How to invoke

Auto-call (Phase 5 → Phase 6 gate): Orchestrator automatically calls this skill after IMPLEMENT phase to audit the diff.

Manual call:

/karpathy-audit

or

@karpathy-audit

Audit output

The skill produces a compliance report written to .claude/state/karpathy-report.json:

{
  "phase": "IMPLEMENT",
  "timestamp": "2026-05-18T21:25:00Z",
  "spec_file": "docs/stories/user-auth/Story.md",
  "audit": {
    "think_before_coding": {
      "score": 85,
      "violations": ["Assumed DB schema without asking"],
      "evidence": ["Line 42: const User = model('User')"]
    },
    "simplicity_first": {
      "score": 92,
      "violations": [],
      "evidence": ["Reduced 180→120 lines in refactor"]
    },
    "surgical_changes": {
      "score": 78,
      "violations": ["Modified logging in unrelated file"],
      "scope_creep_files": ["src/logging/index.ts"],
      "out_of_spec": true
    },
    "goal_driven": {
      "score": 100,
      "violations": [],
      "evidence": ["All tests passing. RED→GREEN→REFACTOR complete."]
    },
    "overall": 89,
    "gate_decision": "PASS_WITH_APPROVAL",
    "recommendation": "Score 89: Pass scope and simplicity checks. Recommend human approval before advancing to Phase 6."
  }
}

Scoring & Gate Decisions

Scope creep detection

Compares two sources:

1. Original spec — From docs/stories/{story}/Story.md (required scope)
2. PR diff — Files and line changes in the current PR

Violations flagged:

• Files modified outside the spec boundary
• Feature branches added beyond the story requirement
• Unrelated cleanup/refactoring

Phase 5 → Phase 6 Gate

Orchestrator behavior:

Phase 5 (IMPLEMENT) complete
  ↓
Auto-call: /karpathy-audit
  ↓
Analyze spec + PR diff + 4 principles
  ↓
Write `.claude/state/karpathy-report.json`
  ↓
Score ≥90?      → Auto-advance to Phase 6
Score 70-89?    → Pause. Display report. Require [a]pprove or [c]cancel
Score <70?      → HALT. Show violations. Require /karpathy-audit re-run after fixes

Dashboard integration

The TUI displays:

• Phase 5 detail view — Shows karpathy-report.json if present
• [P] overlay (Pipeline pane) — Per-principle scores + violations
• Red blocking indicator — If score <70, blocks manual phase advance
• Approval gate — If 70-89, shows "awaiting approval" state

Remediation workflow

If audit fails or scores <70:

1. Orchestrator shows violation details
2. Specialist agent re-assesses work against the principle
3. Fix or remove out-of-scope code
4. Manually re-run: /karpathy-audit
5. If all 4 principles ≥70 now, approve advancement

Example invocation

User: /feature "add password reset via email"
Orchestrator: [Phase 1-5 complete]
Orchestrator: Auditing against Karpathy principles...
karpathy-audit: Running audit...
[Analyze spec vs PR diff]
[Score each principle]
karpathy-audit: 📋 Report written to .claude/state/karpathy-report.json
karpathy-audit: 🟡 Score 82/100 — PASS_WITH_APPROVAL
karpathy-audit: ⚠️ Scope creep: modified src/logging (out of spec)

Dashboard: [Shows approval gate, awaiting [a] key]
User: a  [approve]
Dashboard: [Phase 6 VALIDATE begins]

Further reading

• Karpathy's observations on LLM coding mistakes
• MAPLE 8-Phase Pipeline

SKILL: Kubernetes Patterns

Kustomize Structure

infra/k8s/
├── base/
│   ├── deployment.yaml
│   ├── service.yaml
│   ├── configmap.yaml
│   └── kustomization.yaml
└── overlays/
    ├── dev/
    │   ├── kustomization.yaml
    │   └── patches/
    ├── staging/
    │   ├── kustomization.yaml
    │   └── patches/
    └── prod/
        ├── kustomization.yaml
        └── patches/

Deployment with Required Fields

apiVersion: apps/v1
kind: Deployment
metadata:
  name: {app-name}
  labels:
    app: {app-name}
spec:
  replicas: 2
  selector:
    matchLabels:
      app: {app-name}
  template:
    metadata:
      labels:
        app: {app-name}
    spec:
      securityContext:
        runAsNonRoot: true
        runAsUser: 1001
      containers:
        - name: {app-name}
          image: {image}:{tag}
          resources:
            requests:
              memory: "128Mi"
              cpu: "100m"
            limits:
              memory: "256Mi"
              cpu: "500m"
          readinessProbe:
            httpGet:
              path: /health
              port: 3000
            initialDelaySeconds: 5
            periodSeconds: 10
          livenessProbe:
            httpGet:
              path: /health
              port: 3000
            initialDelaySeconds: 15
            periodSeconds: 20
          startupProbe:
            httpGet:
              path: /health
              port: 3000
            failureThreshold: 30
            periodSeconds: 10

PodDisruptionBudget

apiVersion: policy/v1
kind: PodDisruptionBudget
metadata:
  name: {app-name}-pdb
spec:
  minAvailable: 1
  selector:
    matchLabels:
      app: {app-name}

HPA

apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: {app-name}-hpa
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: {app-name}
  minReplicas: 2
  maxReplicas: 10
  metrics:
    - type: Resource
      resource:
        name: cpu
        target:
          type: Utilization
          averageUtilization: 70

Validation Workflow

# Always validate before applying
kubectl apply --dry-run=client -f {manifest}
kustomize build overlays/dev | kubectl apply --dry-run=client -f -
helm template {release} {chart} | kubectl apply --dry-run=client -f -

SKILL: Mermaid Diagrams

Required Diagrams Per Feature

1. Component diagram (graph TB)
2. Sequence diagram (sequenceDiagram)
3. ER diagram (erDiagram)
4. Deployment diagram (graph TB with deployment focus)
5. State machine (stateDiagram-v2) — where applicable

Rules

• Maximum 30 nodes per diagram.
• All diagrams must be syntactically valid.
• Test diagrams in the Mermaid Live Editor before committing.
• Use descriptive node labels.

Component Diagram

graph TB
    subgraph "Frontend"
        UI["React App"]
    end
    subgraph "Backend"
        API["REST API"]
        DB[("PostgreSQL")]
        Cache[("Redis")]
    end
    UI -->|"HTTPS"| API
    API --> DB
    API --> Cache

Sequence Diagram

sequenceDiagram
    actor U as User
    participant F as Frontend
    participant A as API
    participant D as Database

    U->>F: Action
    F->>A: POST /api/resource
    A->>D: INSERT
    D-->>A: 201 Created
    A-->>F: {id, data}
    F-->>U: Success

ER Diagram

erDiagram
    USER {
        uuid id PK
        string email UK
        timestamp created_at
    }
    ORDER {
        uuid id PK
        uuid user_id FK
        decimal total
        timestamp created_at
    }
    USER ||--o{ ORDER : "places"

State Machine

stateDiagram-v2
    [*] --> Pending
    Pending --> Processing: payment received
    Processing --> Completed: fulfilled
    Processing --> Failed: error
    Failed --> Pending: retry
    Completed --> [*]

Deployment Diagram

graph TB
    subgraph "Vercel Edge"
        FE["Next.js App"]
        EF["Edge Functions"]
    end
    subgraph "AWS"
        LB["Load Balancer"]
        APP["App Servers"]
        RDS[("RDS PostgreSQL")]
        EC["ElastiCache Redis"]
    end
    FE --> EF
    EF --> LB
    LB --> APP
    APP --> RDS
    APP --> EC

SKILL: mockup

Purpose

Scaffold high-fidelity UI component mockups using the project's declared UI stack (Mantine, Tailwind/shadcn, or plain HTML). Mockups consume approved wireframes and design tokens. Output is runnable code — not a design file. Human approval required before the mockup is treated as the implementation target.

Inputs

Supported Stacks (web target)

Outputs

Target awareness

design.target (project.config.yaml, default web):

• web — generate the code mockup (.tsx/.html) for the configured ui_library, plus .mockup.md.
• tui — generate ONLY <id>.mockup.md: a fenced monospace terminal render at the target width covering default/selected/empty/error/loading states, followed by a "Styles" section mapping each region to lipgloss Foreground/Background/Border/Padding taken from docs/design/identity/terminal-theme.json. Skip the stack detector and the React templates below.

Pre-flight Checks

Before generating:

WIREFRAME="docs/design/wireframes/${STORY_ID}.wireframe.md"
TOKENS="docs/design/identity/tokens.json"

# 1. Wireframe must be approved
STATUS=$(python3 -c "
import re
m = re.search(r'^status:\s*(\w+)', open('$WIREFRAME').read(), re.MULTILINE)
print(m.group(1) if m else 'draft')
")
[ "$STATUS" = "approved" ] || { echo "BLOCKED: wireframe not approved"; exit 1; }

# 2. Tokens must exist
[ -f "$TOKENS" ] || { echo "BLOCKED: tokens.json missing — run visual-identity skill first"; exit 1; }

Mockup Template: react-mantine

// AUTO-GENERATED MOCKUP — docs/design/mockups/{story-id}.mockup.tsx
// Story: {story title}
// Wireframe: {wireframe file}
// Tokens: mantine.theme.ts
// Status: draft — awaiting approval

import { MantineProvider, Stack, TextInput, Button, Text, Alert } from '@mantine/core';
import { theme } from '../../docs/design/identity/mantine.theme';
import { IconAlertCircle } from '@tabler/icons-react';

interface Props {
  error?: string;
  onSubmit: (email: string) => void;
}

export function {ComponentName}({ error, onSubmit }: Props) {
  const [email, setEmail] = useState('');

  return (
    <MantineProvider theme={theme}>
      <Stack gap="md" maw={400} mx="auto" mt="xl">
        <Text fw={700} size="xl">{Screen Title}</Text>

        <TextInput
          label="Email"
          placeholder="you@example.com"
          value={email}
          onChange={(e) => setEmail(e.target.value)}
          error={error}
        />

        {error && (
          <Alert icon={<IconAlertCircle />} color="red" variant="light">
            {error}
          </Alert>
        )}

        <Button fullWidth onClick={() => onSubmit(email)}>
          Send Reset Link
        </Button>
      </Stack>
    </MantineProvider>
  );
}

Mockup Template: react-tailwind

// AUTO-GENERATED MOCKUP — docs/design/mockups/{story-id}.mockup.tsx
import { useState } from 'react';

interface Props {
  error?: string;
  onSubmit: (email: string) => void;
}

export function {ComponentName}({ error, onSubmit }: Props) {
  const [email, setEmail] = useState('');

  return (
    <div className="max-w-sm mx-auto mt-16 space-y-4">
      <h1 className="text-2xl font-bold text-foreground">{Screen Title}</h1>

      <div>
        <label className="block text-sm font-medium mb-1">Email</label>
        <input
          type="email"
          className={`w-full border rounded-md px-3 py-2 text-sm ${error ? 'border-error' : 'border-border'}`}
          placeholder="you@example.com"
          value={email}
          onChange={(e) => setEmail(e.target.value)}
        />
        {error && <p className="text-error text-sm mt-1">{error}</p>}
      </div>

      <button
        className="w-full bg-brand-primary text-white rounded-md py-2 font-medium hover:opacity-90"
        onClick={() => onSubmit(email)}
      >
        Send Reset Link
      </button>
    </div>
  );
}

Mockup Metadata File

Always write a .mockup.md alongside the code file:

---
story_id: "{story_id}"
wireframe: "docs/design/wireframes/{story_id}.wireframe.md"
stack: "{stack}"
status: draft        # draft | approved | rejected
approved_by: null
approved_at: null
---

## Mockup: {story title}

### States

- Default
- Error: {describe}
- Success: {describe}
- Loading: {describe if applicable}

### Token Usage

- Primary action: `color.brand.primary`
- Error text: `color.semantic.error`
- Border: `color.surface.border`

### Approval

- [ ] Matches approved wireframe
- [ ] Design tokens applied correctly
- [ ] All interaction states present
- [ ] Approved by product owner / UX lead

Failure Modes

Logging

[mockup] CREATE   docs/design/mockups/auth-reset-0001.mockup.tsx  stack=react-mantine
[mockup] CREATE   docs/design/mockups/auth-reset-0001.mockup.md   status=draft
[mockup] BLOCKED  auth-reset-0001  wireframe not approved
[mockup] SKIP     auth-reset-0001  mockup approved — locked

SKILL: pipeline-runner

What It Does

Dispatches any named workflow, skill, or agent from a single entry point. Resolution order:

1. Taffy workflow — look for .claude/taffy/<name>.yaml; if found, execute each stage in order
2. Skill (local) — look for .claude/skills/<name>/; if found, invoke the skill
3. Agent — look for .claude/agents/<name>.md; if found, delegate to @<name>
4. Skill (registry) — if not found locally, try to install from skills.sh, then retry step 2

Pipeline state is written to .claude/state/maple.json at every transition.

Usage

/pipeline-runner <name>

Examples:

/pipeline-runner new-ui-feature
/pipeline-runner api-endpoint
/pipeline-runner implement-stories
/pipeline-runner tdd-workflow
/pipeline-runner orchestrator

List available taffy workflows:

ls .claude/taffy/*.yaml | grep -v schema

List available skills:

ls .claude/skills/

Dispatch Protocol

Step 1: Resolve the target

# Check taffy first
[ -f ".claude/taffy/<name>.yaml" ] && dispatch=taffy
# Then local skill
[ -d ".claude/skills/<name>" ] && dispatch=skill
# Then agent
[ -f ".claude/agents/<name>.md" ] && dispatch=agent
# Fallback: fetch from skills.sh registry, then retry
if [ -z "$dispatch" ] && command -v npx &>/dev/null; then
  echo "pipeline-runner: '<name>' not found locally — checking skills.sh…"
  npx --yes skills add kinncj/maple@<name> -a claude-code -y 2>/dev/null \
    || npx --yes skills add <name> -a claude-code -y 2>/dev/null \
    || true
  [ -d ".claude/skills/<name>" ] && dispatch=skill
fi

If nothing matches after the registry fallback, report: pipeline-runner: no taffy workflow, skill, or agent named '<name>' (also checked skills.sh registry)

Step 2: Initialise state

Write to .claude/state/maple.json (merge — do not overwrite unowned fields):

{
  "taffy": "<name>",
  "stage": "<first-stage or skill-name>",
  "status": "RUNNING",
  "awaiting_approval": null,
  "started_at": "<iso8601>",
  "updated_at": "<iso8601>"
}

Step 2b: Runtime policy enforcement (mandatory)

Before any stage execution, read and enforce:

• Harness-specific root markdown:
  • Claude harness → CLAUDE.md
  • OpenCode harness → OPENCODE.md
  • Cursor harness → CURSOR.md
  • Copilot harness → COPILOT.md
• AGENTS.md
• .github/copilot-instructions.md
• .github/instructions/stories.instructions.md (when touching story files)

When the launch prompt contains a <maple-gherkin-handoff> block:

1. Treat it as hard scope: implement only listed story paths / IDs.
2. Do not run Spec-Kit or regenerate stories.
3. Preserve the repository's current Cucumber stack:
   • If generated stories include cucumber/*_steps.py, use Python behave-style steps.
   • Do not introduce TypeScript @cucumber/cucumber unless the repository already uses it as the active standard.
4. Keep BusinessRepo structure and phase gates exactly as defined by instruction files.
5. Treat test layout as mandatory:
   • Gherkin feature files must live under /tests/features/.
   • Step definitions must use the repository's active Cucumber stack and live under /tests.
   • Do not place acceptance tests under /app or story directories.
6. Enforce module boundaries independent of language:
   • Runtime/source files must not import from docs/, .github/, or .claude/.
   • Copying/adapting approved artifact content into app/test source is allowed.
   • Design/spec artifacts are references, not runtime code dependencies.

Step 3a: Taffy workflow execution

Load .claude/taffy/<name>.yaml, parse stages:, resolve depends_on order.

If the workflow defines an orchestrator-kickoff stage, execute it first before all other stages. This stage must publish the initial plan and heartbeat cadence.

For each stage:

when: guard:

• when: ui:true — skip if story has ui: false, unless .claude/state/maple.json has force_ui: true with launch_source: maple-x (MAPLE [x] quick-launch override).
• when: ui:false — skip if story has ui: true
• when: always — always run
• UI-related scope includes web, mobile, desktop, and TUI stories. Any such run must include design-review human-approval stages before implementation phases.

depends_on: all listed stages must be DONE before this one starts.

Dispatch:

• agent: <name> → delegate to @<name> with current story context
• skill: <name> → invoke the skill
• pipeline: standard → run the full 8-phase orchestrator pipeline

After each stage: update maple.json with current stage + RUNNING.

Progress heartbeats (mandatory):

• Send an immediate kickoff status before the first long-running tool/agent call.
• While a taffy run is active, send a concise progress update at least every 60-120 seconds.
• On each heartbeat, refresh maple.json updated_at and current stage.
• Every heartbeat must include concrete progress evidence:
  • changed files/artifacts since last update (explicit paths), or
  • a specific blocker that prevented changes.
• Use this status format:
  • Progress: <stage / phase>
  • Done since last update: <brief>
  • Current action: <brief>
  • Blockers: <none or blocker>
  • Next update: <ETA>
• Do not send heartbeat-only timestamp churn with no artifact/blocker details.
• If a stage requires writing artifacts and write access/tools are unavailable, set maple.json to FAILED with an explicit error and stop.
• If blocked/waiting, report what is pending and continue heartbeats until unblocked.

Completion artifact gate (mandatory):

• Before marking DONE, verify the run produced concrete story-linked artifacts under the BusinessRepo layout.
• Required for implementation runs:
  • application changes in /app (or existing domain folders),
  • tests in /tests (unit/integration/e2e as applicable),
  • Gherkin assets in /tests/features plus matching step implementations.
• Boundary check:
  • fail the run if generated runtime code imports paths under docs/, .github/, or .claude/.
• If required test/gherkin artifacts are missing, set maple.json to FAILED and report missing paths explicitly.

Step 3b: Skill invocation

Invoke the skill directly. Update maple.json on start and completion.

Step 3c: Agent delegation

Delegate to @<name>. Update maple.json on start and completion.

Step 4: Human-approval gates (taffy only)

When a stage has gate: human-approval:

1. Complete stage work (produce artifact).
   • For design review stages (wireframe, visual-identity, design-tokens, ui-mockup-builder, design-refresh), artifact production is mandatory:
     • create at least one previewable artifact (.excalidraw, .html, .svg, .png, .jpg, .jpeg, .webp, or .md) under docs/design (or approved artifact dirs), and
     • the required formats depend on design.target (project.config.yaml, default web): web = .md + .html + .excalidraw; tui = .md + .excalidraw (no .html). A run that produces fewer than the required formats is incomplete, and
     • update .claude/state/design-artifacts.json with current stage artifact paths so the review portal can update live.
   • Path + completeness gate for wireframe stage (mandatory before PAUSING):

     # Verify wireframes are in the canonical location and the required formats exist.
     # Required formats depend on design.target (web: md+html+excalidraw; tui: md+excalidraw).
     TARGET=$(sed -n 's/^[[:space:]]*target:[[:space:]]*\([a-z]*\).*/\1/p' project.config.yaml 2>/dev/null | head -1)
     [ -z "$TARGET" ] && TARGET=web
     CANONICAL=$(find docs/design/wireframes -name "*.wireframe.*" 2>/dev/null | wc -l | tr -d ' ')
     MISPLACED=$(find docs -name "*.wireframe.*" -not -path "*/docs/design/wireframes/*" 2>/dev/null)
     MISSING_HTML=""
     if [ "$TARGET" != "tui" ]; then
       MISSING_HTML=$(find docs/design/wireframes -name "*.wireframe.md" 2>/dev/null | while read md; do
         base="${md%.wireframe.md}"
         [ ! -f "${base}.wireframe.html" ] && echo "${base}.wireframe.html"
       done)
     fi
     MISSING_EXCALIDRAW=$(find docs/design/wireframes -name "*.wireframe.md" 2>/dev/null | while read md; do
       base="${md%.wireframe.md}"
       [ ! -f "${base}.wireframe.excalidraw" ] && echo "${base}.wireframe.excalidraw"
     done)
     if [ "$CANONICAL" -eq 0 ]; then
       if [ -n "$MISPLACED" ]; then
         echo "PIPELINE GATE FAILED: wireframes found at wrong path(s): $MISPLACED"
         echo "Canonical path is docs/design/wireframes/ — move files there before this stage can complete."
       else
         echo "PIPELINE GATE FAILED: no wireframe artifacts in docs/design/wireframes/"
       fi
       # set maple.json FAILED and stop
     fi
     if [ -n "$MISSING_HTML" ]; then
       echo "PIPELINE GATE FAILED: missing .wireframe.html for: $MISSING_HTML — generate it now."
       # set maple.json FAILED and stop
     fi
     if [ -n "$MISSING_EXCALIDRAW" ]; then
       echo "PIPELINE GATE FAILED: missing .wireframe.excalidraw for: $MISSING_EXCALIDRAW — generate it now."
       # set maple.json FAILED and stop
     fi
     

     If the gate fails, produce the missing files before re-running the gate check.
   • If no reviewable artifact exists for a design gate, set maple.json to FAILED and stop.
2. Write PAUSED state:

{ "stage": "<name>", "status": "PAUSED", "awaiting_approval": "<name>", "updated_at": "<iso8601>" }

3. Write stage name to .claude/state/approval-pending.txt.
4. Output:

TAFFY PAUSED — awaiting human approval
Stage:    <stage-name>
Artifact: <artifact path or description>

Approve via the maple TUI ([P] pipeline → [a] approve) or reply "approved" / "continue".
I will not advance to the next stage until approval is confirmed.

5. Poll: timeout 540 bash -c 'until [ ! -f .claude/state/approval-pending.txt ]; do sleep 2; done'
   • On timeout (exit 124), re-run the same poll. The Bash tool caps at 10 min per call; re-polling across calls lets approval delays exceed that bound.
   • Also accept an explicit "approved" / "continue" reply in chat.
   • When the user approves via the maple TUI ([P] → [a]), the TUI deletes the pending file and sends a "continue" keystroke to the agent's pane via the active multiplexer (outer tmux/zellij, or a detached tmux new-session wrapper). Either signal is sufficient to resume.
6. On resume: update to RUNNING, advance to next stage.
7. While paused, monitor .claude/state/design-feedback.json:
   • status: requested_changes or status: rejected means apply the requested updates before advancing.
   • Treat attachments as required review inputs (uploaded files such as .excalidraw, images, HTML, text), typically under docs/design/review-input/.
   • Summarize how each feedback item and attachment was addressed before continuing.

Step 5: Completion

{ "taffy": "<name>", "stage": "DONE", "status": "DONE", "awaiting_approval": null, "updated_at": "<iso8601>" }

Output:

TAFFY COMPLETE — <name>
Stages run: N
Duration:   <elapsed>

Failure Handling

After 3 consecutive failures on any stage:

{ "stage": "<name>", "status": "FAILED", "error": "<summary>", "updated_at": "<iso8601>" }

Stop. Report failed stage and error to human. Do not proceed.

Rate-limit Handling

When a usage limit, rate limit, HTTP 429, or "resets at " message stops you continuing, before stopping:

1. Merge-write .claude/state/maple.json (keep taffy/stage):

{ "status": "RATE_LIMITED", "resume_at": "<iso8601 reset time, else now+1h>", "rate_limit_reason": "<one line>", "updated_at": "<iso8601>" }

2. Write a one-line breadcrumb to .claude/state/rate-limit.txt: <resume_at>|<reason>. One cheap write — do it even if nothing else is possible.
3. Stop. Do not hammer the API. MAPLE resumes the pipeline when the window clears (manual [r], or auto when armed).

Session Context

On startup, read .claude/state/sessions.json if it exists:

{ "claude": "<uuid>", "opencode": "<id>", "copilot": "<id>" }

Use the matching session ID when resuming work within an existing agent session.

State File Reference

All state in .claude/state/. TUI and skill share these files.

.claude/state/maple.json

Merge-not-overwrite: read existing file, update only owned fields, re-write.

.claude/state/approval-pending.txt

Skill writes stage name. TUI deletes when user presses [a].

.claude/state/rate-limit.txt

Skill/agent writes <resume_at>|<reason>. TUI reads, promotes maple.json to RATE_LIMITED, and deletes the file.

.claude/state/sessions.json

TUI writes harness→session-ID map. Skill reads for session resume.

Skip Conditions

• spike/* and chore/* branches: skip Spec-Kit stages, run implementation stages.
• Stage when: ui:true on a ui: false story: skip silently, log [pipeline-runner] SKIP stage=<name> reason=ui:false unless quick-launch override is active (force_ui=true, launch_source=maple-x).

SKILL: Playwright CLI

When to Use

Use Playwright CLI (playwright-cli) for interactive browser exploration and snapshot-based interaction. Use npx playwright test for running actual test suites.

Installation

npm install -g @playwright/cli
npx playwright install  # installs browsers

Core CLI Commands

Browser Exploration

# Open browser to URL
playwright-cli open http://localhost:3000

# Take accessibility snapshot (YAML with element references)
playwright-cli snapshot
# Output: saves to disk as snapshot.yml — review before acting

# Interact by element reference (e.g., e21 from snapshot)
playwright-cli click e21
playwright-cli fill e35 "test@example.com"
playwright-cli press e35 Enter
playwright-cli screenshot  # saves to disk

Session Management

# Named sessions for auth state
playwright-cli --session=auth open http://localhost:3000/login
playwright-cli --session=auth fill e10 "admin@example.com"
playwright-cli --session=auth fill e11 "password"
playwright-cli --session=auth click e20  # submit button
playwright-cli session-list

Snapshot-to-Test Workflow

1. playwright-cli open http://localhost:3000
2. playwright-cli snapshot → review element refs in snapshot.yml
3. Interact: playwright-cli click e21, playwright-cli fill e35 "value"
4. Observe results
5. Convert to test file:

// tests/e2e/feature.spec.ts
import { test, expect } from '@playwright/test';

test('should {outcome} when {action}', async ({ page }) => {
  await page.goto('/');
  await page.getByRole('button', { name: 'Sign In' }).click();
  await page.getByLabel('Email').fill('test@example.com');
  await page.getByLabel('Password').fill('password123');
  await page.getByRole('button', { name: 'Login' }).click();
  await expect(page).toHaveURL('/dashboard');
  await expect(page.getByRole('heading', { name: 'Dashboard' })).toBeVisible();
});

Test Execution

# Run all E2E tests
npx playwright test tests/e2e/

# Run specific test file
npx playwright test tests/e2e/auth.spec.ts

# Visual debugger
npx playwright test --ui

# Headed mode (visible browser)
npx playwright test --headed

# Generate tests by recording
npx playwright codegen http://localhost:3000

# View HTML report
npx playwright show-report

API Testing (Playwright request fixture)

test('POST /api/users returns 201', async ({ request }) => {
  const response = await request.post('/api/users', {
    data: {
      email: 'test@example.com',
      name: 'Test User'
    }
  });
  expect(response.status()).toBe(201);
  const body = await response.json();
  expect(body).toHaveProperty('id');
});

Token Efficiency Note

Use playwright-cli snapshot (saves to disk) instead of screenshots in context. The compact YAML element refs (~1,350 tokens) vs accessibility tree injection (~5,700 tokens).

SKILL: PostgreSQL Patterns

Migration Naming

migrations/
  V001__create_users.sql          # Flyway
  0001_create_users.sql           # Generic
  20240115_create_users.sql       # Timestamp-based

Table Pattern with RLS

-- Create table
CREATE TABLE IF NOT EXISTS users (
  id          uuid DEFAULT gen_random_uuid() PRIMARY KEY,
  email       text UNIQUE NOT NULL,
  name        text NOT NULL,
  role        text NOT NULL DEFAULT 'user' CHECK (role IN ('user', 'admin')),
  created_at  timestamptz DEFAULT now() NOT NULL,
  updated_at  timestamptz DEFAULT now() NOT NULL
);

-- Indexes
CREATE INDEX CONCURRENTLY idx_users_email ON users(email);
CREATE INDEX CONCURRENTLY idx_users_role ON users(role) WHERE role != 'user';

-- Updated_at trigger
CREATE OR REPLACE FUNCTION update_updated_at()
RETURNS TRIGGER AS $$
BEGIN
  NEW.updated_at = now();
  RETURN NEW;
END;
$$ LANGUAGE plpgsql;

CREATE TRIGGER users_updated_at
  BEFORE UPDATE ON users
  FOR EACH ROW EXECUTE FUNCTION update_updated_at();

-- RLS
ALTER TABLE users ENABLE ROW LEVEL SECURITY;

CREATE POLICY users_select_own ON users
  FOR SELECT USING (id = current_user_id());

CREATE POLICY users_admin_all ON users
  FOR ALL USING (current_user_role() = 'admin');

Query Optimization

-- Always EXPLAIN ANALYZE in development
EXPLAIN (ANALYZE, BUFFERS, FORMAT TEXT)
SELECT u.*, COUNT(o.id) as order_count
FROM users u
LEFT JOIN orders o ON o.user_id = u.id
WHERE u.created_at > now() - interval '30 days'
GROUP BY u.id;

-- Partial index for common filter
CREATE INDEX idx_orders_pending
  ON orders(created_at)
  WHERE status = 'pending';

-- GIN index for full-text search
CREATE INDEX idx_products_search
  ON products USING gin(to_tsvector('english', name || ' ' || description));

Connection Pooling (PgBouncer)

# pgbouncer.ini
[databases]
app = host=127.0.0.1 port=5432 dbname=app

[pgbouncer]
pool_mode = transaction  # transaction pooling for most apps
max_client_conn = 100
default_pool_size = 20

Rules

• NEVER modify existing migration files.
• Always create new migration for schema changes.
• Index all foreign keys.
• Use CONCURRENTLY for index creation on large tables.
• EXPLAIN ANALYZE all queries > 100ms.
• Enable RLS on tables with user data.

SKILL: Redis Patterns

Key Design Convention

{app}:{domain}:{entity}:{id}
# Examples:
myapp:user:session:usr_123
myapp:product:cache:prod_456
myapp:rate:api:ip_1.2.3.4
myapp:queue:emails:pending

Cache-Aside Pattern

async function getUser(id: string): Promise<User> {
  const key = `myapp:user:data:${id}`;
  const ttl = 3600; // 1 hour

  // Try cache first
  const cached = await redis.get(key);
  if (cached) {
    return JSON.parse(cached) as User;
  }

  // Cache miss — fetch from DB
  const user = await db.users.findById(id);
  if (!user) throw new Error('User not found');

  // Store in cache with TTL
  await redis.setex(key, ttl, JSON.stringify(user));
  return user;
}

// Invalidate on update
async function updateUser(id: string, data: Partial<User>): Promise<User> {
  const user = await db.users.update(id, data);
  await redis.del(`myapp:user:data:${id}`);
  return user;
}

Rate Limiting with Sorted Set

async function rateLimit(ip: string, limit: number, windowSeconds: number): Promise<boolean> {
  const key = `myapp:rate:api:${ip}`;
  const now = Date.now();
  const windowStart = now - (windowSeconds * 1000);

  const pipeline = redis.pipeline();
  pipeline.zremrangebyscore(key, 0, windowStart);
  pipeline.zadd(key, now, `${now}`);
  pipeline.zcard(key);
  pipeline.expire(key, windowSeconds);

  const results = await pipeline.exec();
  const count = results?.[2]?.[1] as number;
  return count <= limit;
}

Session Store

// Using ioredis with connect-redis
import session from 'express-session';
import RedisStore from 'connect-redis';

app.use(session({
  store: new RedisStore({ client: redis }),
  secret: process.env.SESSION_SECRET!,
  resave: false,
  saveUninitialized: false,
  cookie: {
    secure: process.env.NODE_ENV === 'production',
    httpOnly: true,
    maxAge: 1000 * 60 * 60 * 24, // 24 hours
  }
}));

Rules

• ALWAYS set TTLs on cache keys — never store indefinitely.
• Use SCAN not KEYS in production (non-blocking).
• Use pipelining for multiple operations.
• Key convention: {app}:{domain}:{entity}:{id}.
• Monitor with: redis-cli info memory and redis-cli monitor (dev only).
• Set maxmemory-policy allkeys-lru for cache-only Redis instances.

SKILL: RFC / Architecture Decision Records

ADR Format

Every significant architectural decision gets an ADR. Store in: docs/specs/{feature}/adr.md

# ADR-{N}: {Short Title}

## Status
Proposed | Accepted | Deprecated | Superseded by ADR-{N}

## Context
What is the problem or situation that requires a decision?
What constraints exist?

## Goals
- {Specific, measurable goal}

## Non-goals
- {What this ADR does NOT address}

## Proposal
{Detailed technical proposal. Include code snippets if helpful.}

## Alternatives Considered

### Option A: {Name}
**Description:** {What it is}
**Pros:** {list}
**Cons:** {list}

### Option B: {Name}
**Description:** {What it is}
**Pros:** {list}
**Cons:** {list}

## Trade-offs and Risks
{Analysis of trade-offs. What could go wrong?}

## Impact

### Cost (FinOps)
{Estimated cloud cost impact. Monthly estimate if possible.}

### Operations (SRE)
{New runbook requirements. Alert thresholds. On-call implications.}

### Security
{Changes to attack surface. New threat vectors. Compliance implications.}

### Team
{Skill requirements. Training needed. Hiring implications.}

## Decision
{Final decision and rationale. Who made it and when.}

## Next Steps
- [ ] {Action item with owner}
- [ ] {Action item with owner}

When to Write an ADR

• Choosing between two or more non-trivial technical approaches.
• Adopting a new technology or framework.
• Changing a significant existing pattern.
• Making a trade-off with known long-term implications.

When NOT to Write an ADR

• Obvious choices with no real alternatives.
• Implementation details within an agreed-upon approach.
• Temporary decisions expected to change soon.

rubber-duck skill

Invoke @rubber-duck to get an independent second opinion on a plan, implementation, or test suite. This is the same pattern as GitHub Copilot CLI's built-in Rubber Duck feature — a different perspective to catch what the primary agent missed.

When to invoke

How to call it

@rubber-duck Mode: PLAN REVIEW

Plan: <paste plan.md content or path>
Story: <paste story frontmatter + scenarios>

@rubber-duck Mode: CODE REVIEW

Files changed:
- src/scheduler.ts
- src/jobs/notify.ts
- src/queue/index.ts

<paste diff or file content>

@rubber-duck Mode: TEST REVIEW

Test files:
- tests/unit/scheduler.test.ts
- tests/e2e/notify.spec.ts
- features/scheduler.feature

<paste test content>

Verdict handling

CRITICAL findings always block. WARN findings are surfaced to the human for a decision. INFO findings are logged but do not block.

Tips

• You do not need to prepare anything special — just pass the relevant content.
• The rubber duck will not rewrite your code. It only surfaces findings. Acting on them is your job.
• For Copilot CLI users: the built-in /experimental Rubber Duck activates automatically at the same checkpoints. This skill adds equivalent coverage when using Claude Code or OpenCode.

SKILL: Ship-Safe Audit

What It Does

Runs ship-safe — a pre-ship security and quality scanner that checks for secrets, vulnerabilities, and risky patterns before code reaches production.

Usage

npx ship-safe audit .

Run from the project root. No install required (npx fetches it on demand).

Opt-In

Ship-safe is disabled by default. To enable it:

• CI/CD: set the repository variable ENABLE_SHIP_SAFE=true in GitHub → Settings → Variables
• Agents / local: set env var ENABLE_SHIP_SAFE=true before invoking /ship-safe

When to Use

Only run if ENABLE_SHIP_SAFE=true is set. When enabled, appropriate moments are:

• Before opening a PR
• After adding new dependencies
• Before merging any feature branch to main
• After touching auth, secrets handling, or infra config

Output Interpretation

Agent Instructions

1. Run npx ship-safe audit . from the repo root.
2. Parse stdout for CRITICAL/HIGH findings — these are blockers.
3. For each blocker: report the file, line, and finding description.
4. For MEDIUM/LOW: report as advisory, do not block.
5. If all checks pass: confirm "ship-safe: clean" and proceed.
6. If blockers found: halt the task, report findings to Orchestrator.

Example Integration (architect / pre-ship checklist)

/ship-safe

The skill runs the audit, colors findings by severity, and surfaces blockers before any merge action.

SKILL: spec-kit

Purpose

Produce a complete Gherkin story file in docs/stories/ before any implementation begins. One invocation = one story file. The story file is the minimum spec — no additional artifacts required.

State Machine

feature description → story draft → human approval → DISCOVER

No step may begin until the previous one completes. Approval = human sets status: approved in the story frontmatter, or confirms verbally.

Story File Location

docs/stories/{epic-slug}-{feature-slug}.md   # with epic context
docs/stories/{feature-slug}.md               # standalone feature

Story File Template

---
id: "{feature-slug}"
title: "{Feature Title}"
epic: "{epic-slug or null}"
priority: "high|medium|low"
ui: false
adr_required: false
phase: discover
labels:
  - "type:feature"
  - "priority:{priority}"
status: draft
---

## Story

**As a** {user role},
**I want** {what they want},
**so that** {business outcome}.

## Acceptance Criteria

```gherkin
@story:{feature-slug} @priority:{priority}
Feature: {Feature Title}

  Scenario: {happy path title}
    Given {precondition}
    When {action}
    Then {outcome}

  Scenario: {failure or edge case title}
    Given {precondition}
    When {action}
    Then {outcome}

Definition of Done

• All Gherkin scenarios have passing step implementations
• Unit tests written and passing
• Code reviewed and approved
• Documentation updated if user-facing

## Validate a Story File

```bash
validate_story() {
  local file="$1"

  if [ ! -f "$file" ]; then
    echo "[spec-kit] MISSING  $file"
    return 1
  fi

  if ! grep -qE "^\s*(Scenario|Scenario Outline):" "$file"; then
    echo "[spec-kit] FAIL  $file — no Gherkin scenarios found"
    return 1
  fi

  STATUS=$(grep -m1 "^status:" "$file" | awk '{print $2}' | tr -d '"')
  if [ "$STATUS" != "approved" ]; then
    echo "[spec-kit] BLOCKED  $file  status=$STATUS  required=approved"
    return 1
  fi

  echo "[spec-kit] OK  $file  status=approved"
}

# Example
validate_story "docs/stories/user-auth-reset-password.md" || exit 1

Check All Stories Are Approved

FAIL=0
STORIES=$(find docs/stories -name "*.md" ! -name "_template.md" 2>/dev/null || true)

if [ -z "$STORIES" ]; then
  echo "[spec-kit] SKIP  no story files found"
  exit 0
fi

for story in $STORIES; do
  validate_story "$story" || FAIL=1
done

exit $FAIL

Scenario Count Guidelines

Do not invent scenarios not implied by the feature description. Mark unknown cases as TODO and flag for human review.

Skip Conditions

BRANCH=$(git branch --show-current)
if echo "$BRANCH" | grep -qE '^(spike|chore)/'; then
  echo "[spec-kit] SKIP  branch=$BRANCH — spike/chore exempt"
  exit 0
fi

Failure Modes

Logging

[spec-kit] WRITE   docs/stories/user-auth-reset-password.md
[spec-kit] HALT    awaiting human approval
[spec-kit] OK      docs/stories/user-auth-reset-password.md  status=approved
[spec-kit] SKIP    spike/* branch — spec-kit not required

SKILL: SRE Review

Purpose

Evaluate operational readiness of new features before launch.

Failure Mode Analysis

For each new component, document:

1. What can fail? (service down, latency spike, data corruption, cascade)
2. Blast radius? (who is affected? how many users?)
3. Detection time? (how quickly will alerts fire?)
4. Recovery time? (how long to restore service?)
5. Can it be rolled back? (feature flag? migration rollback?)

Observability Requirements

Metrics (Prometheus/CloudWatch/Datadog)

{feature}_requests_total{status="success|error"} counter
{feature}_request_duration_seconds histogram
{feature}_active_connections gauge
{feature}_errors_total{type="validation|timeout|upstream"} counter

Logs (Structured JSON)

{
  "timestamp": "ISO8601",
  "level": "info|warn|error",
  "service": "{service-name}",
  "trace_id": "{distributed-trace-id}",
  "user_id": "{anonymized}",
  "action": "{what happened}",
  "duration_ms": 42,
  "result": "success|error",
  "error": "{message if error}"
}

Traces

• Instrument all cross-service calls with OpenTelemetry.
• Trace IDs propagated via W3C Trace Context headers.

Alerts

Runbook Template

docs/runbooks/{feature}-runbook.md

# Runbook: {Feature Name}

## Symptoms
- {Alert name}: {what the user sees}

## Diagnosis
1. Check logs: `kubectl logs -l app={service} --tail=100`
2. Check metrics: {dashboard URL}
3. Check dependencies: {health check commands}

## Mitigation
### Option A: Restart service
```bash
kubectl rollout restart deployment/{service}
kubectl rollout status deployment/{service}

Option B: Feature flag off

# Disable via environment variable
kubectl set env deployment/{service} FEATURE_{NAME}_ENABLED=false

Escalation

• On-call: {PagerDuty rotation}
• Escalation: {eng manager}
• War room: {Slack channel}

SKILL: story-issue-sync

Purpose

Maintain bidirectional consistency between story files (docs/stories/*.md) and GitHub Issues. The file is authoritative for narrative and Gherkin. The issue is authoritative for labels, status, project board position, and DoD checklist state.

Ownership Model

Inputs / Outputs

Create: File → Issue

When a new story file exists with issue_number: null:

STORY_FILE="docs/stories/user-auth-reset-password-20250416143000-0001.md"

# Extract frontmatter fields
TITLE=$(python3 -c "
import sys, re
text = open('$STORY_FILE').read()
m = re.search(r'^title:\s*[\"\'](.*?)[\"\']', text, re.MULTILINE)
print(m.group(1) if m else '')
")

LABELS=$(python3 -c "
import sys, re
text = open('$STORY_FILE').read()
m = re.findall(r'^\s+- [\"\'](.*?)[\"\']\s*$', text, re.MULTILINE)
print(','.join(m))
")

MILESTONE=$(python3 -c "
import sys, re
text = open('$STORY_FILE').read()
m = re.search(r'^milestone:\s*[\"\'](.*?)[\"\']', text, re.MULTILINE)
print(m.group(1) if m else '')
")

# Create the issue
RESULT=$(gh issue create \
  --title "$TITLE" \
  --body-file "$STORY_FILE" \
  --label "$LABELS" \
  --milestone "$MILESTONE" \
  --json number,url,id)

ISSUE_NUMBER=$(echo "$RESULT" | python3 -c "import sys,json; print(json.load(sys.stdin)['number'])")
ISSUE_URL=$(echo "$RESULT"    | python3 -c "import sys,json; print(json.load(sys.stdin)['url'])")

# Write back to story frontmatter
python3 - <<EOF
import re
text = open('$STORY_FILE').read()
text = re.sub(r'^issue_number: null', f'issue_number: $ISSUE_NUMBER', text, flags=re.MULTILINE)
text = re.sub(r'^issue_url: null', f'issue_url: "$ISSUE_URL"', text, flags=re.MULTILINE)
open('$STORY_FILE', 'w').write(text)
EOF

echo "[story-sync] CREATED  #$ISSUE_NUMBER  ← $STORY_FILE"

Update: File → Issue (body changed)

When story Gherkin or acceptance criteria are edited:

ISSUE_NUMBER=42
STORY_FILE="docs/stories/user-auth-reset-password-20250416143000-0001.md"

gh issue edit "$ISSUE_NUMBER" \
  --body-file "$STORY_FILE"

echo "[story-sync] BODY_UPDATE  #$ISSUE_NUMBER  ← $STORY_FILE"

Sync: Issue → File (labels changed)

When labels on the issue change (e.g., after PO updates priority or phase advances):

ISSUE_NUMBER=42
STORY_FILE="docs/stories/user-auth-reset-password-20250416143000-0001.md"

# Fetch current labels from issue
CURRENT_LABELS=$(gh issue view "$ISSUE_NUMBER" \
  --json labels \
  --jq '[.labels[].name] | join(",")')

# Rewrite labels block in frontmatter
python3 - <<EOF
import re
text = open('$STORY_FILE').read()
label_lines = '\n'.join(f'  - "{l}"' for l in "$CURRENT_LABELS".split(',') if l)
text = re.sub(
    r'^labels:\n(  - .*\n)+',
    f'labels:\n{label_lines}\n',
    text,
    flags=re.MULTILINE
)
open('$STORY_FILE', 'w').write(text)
EOF

echo "[story-sync] LABELS_SYNC  #$ISSUE_NUMBER  → $STORY_FILE"

Detect Drift (file vs issue)

Run before any update to check whether file and issue are in sync:

ISSUE_NUMBER=42
STORY_FILE="docs/stories/user-auth-reset-password-20250416143000-0001.md"

FILE_TITLE=$(python3 -c "
import re
m = re.search(r'^title:\s*[\"\'](.*?)[\"\']', open('$STORY_FILE').read(), re.MULTILINE)
print(m.group(1) if m else '')
")

ISSUE_TITLE=$(gh issue view "$ISSUE_NUMBER" --json title --jq '.title')

if [ "$FILE_TITLE" != "$ISSUE_TITLE" ]; then
  echo "[story-sync] DRIFT  title mismatch: file='$FILE_TITLE'  issue='$ISSUE_TITLE'"
  # File is authoritative for title — update the issue
  gh issue edit "$ISSUE_NUMBER" --title "$FILE_TITLE"
fi

Batch Sync (all stories)

find docs/stories -name "*.md" ! -name "_template.md" | while read -r f; do
  NUMBER=$(python3 -c "
import re
m = re.search(r'^issue_number:\s*(\d+)', open('$f').read(), re.MULTILINE)
print(m.group(1) if m else '')
")
  if [ -z "$NUMBER" ]; then
    echo "[story-sync] NEEDS_CREATE  $f"
  else
    echo "[story-sync] HAS_ISSUE    $f  → #$NUMBER"
  fi
done

Failure Modes

Logging

[story-sync] CREATED       #42  ← docs/stories/user-auth-reset-0001.md
[story-sync] BODY_UPDATE   #42  ← docs/stories/user-auth-reset-0001.md
[story-sync] LABELS_SYNC   #42  → docs/stories/user-auth-reset-0001.md
[story-sync] DRIFT         #42  title mismatch — issue updated
[story-sync] SKIP          #42  no changes detected

SKILL: Stripe Patterns

Local Testing Setup

# Listen for webhooks and forward to local server
stripe listen --forward-to localhost:3000/api/webhooks/stripe

# Trigger test events
stripe trigger payment_intent.succeeded
stripe trigger checkout.session.completed
stripe trigger customer.subscription.created

# Monitor logs
stripe logs tail

Webhook Handler Pattern

// ALWAYS verify webhook signatures — never skip
import Stripe from 'stripe';

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);

export async function POST(req: Request) {
  const body = await req.text();
  const sig = req.headers.get('stripe-signature')!;
  const webhookSecret = process.env.STRIPE_WEBHOOK_SECRET!;

  let event: Stripe.Event;
  try {
    event = stripe.webhooks.constructEvent(body, sig, webhookSecret);
  } catch (err) {
    return new Response(`Webhook Error: ${err.message}`, { status: 400 });
  }

  // Idempotency: check if event already processed
  // Store event.id in database, skip if duplicate

  switch (event.type) {
    case 'payment_intent.succeeded': {
      const paymentIntent = event.data.object as Stripe.PaymentIntent;
      // Handle success
      break;
    }
    case 'checkout.session.completed': {
      const session = event.data.object as Stripe.Checkout.Session;
      // Provision access
      break;
    }
    default:
      console.log(`Unhandled event type: ${event.type}`);
  }

  return new Response(JSON.stringify({ received: true }), { status: 200 });
}

Checkout Session Pattern

const session = await stripe.checkout.sessions.create({
  mode: 'subscription',
  payment_method_types: ['card'],
  line_items: [{
    price: priceId,
    quantity: 1,
  }],
  success_url: `${baseUrl}/success?session_id={CHECKOUT_SESSION_ID}`,
  cancel_url: `${baseUrl}/cancel`,
  customer_email: user.email,
  metadata: {
    userId: user.id,  // link back to your user
  },
}, {
  idempotencyKey: `checkout-${user.id}-${priceId}`,  // ALWAYS use idempotency keys
});

Rules

• ALWAYS verify webhook signatures with constructEvent().
• ALWAYS use idempotency keys on write operations.
• NEVER log raw card data or full payment method details.
• Use restricted API keys with minimum required permissions per service.
• Test every webhook handler with stripe trigger.
• Store Stripe customer IDs in your database for lookup.

SKILL: Supabase Patterns

Local Development Workflow

# Start local Supabase stack
supabase start

# Apply migrations
supabase db push

# Generate TypeScript types
supabase gen types typescript --local > src/types/supabase.ts

# Deploy Edge Functions
supabase functions deploy {function-name}

# Stop
supabase stop

Migration Pattern

-- supabase/migrations/{timestamp}_{description}.sql
-- Up migration (always additive in production)

CREATE TABLE IF NOT EXISTS public.{table_name} (
  id uuid DEFAULT gen_random_uuid() PRIMARY KEY,
  user_id uuid REFERENCES auth.users(id) ON DELETE CASCADE NOT NULL,
  created_at timestamptz DEFAULT now() NOT NULL,
  updated_at timestamptz DEFAULT now() NOT NULL
);

-- Enable RLS ALWAYS
ALTER TABLE public.{table_name} ENABLE ROW LEVEL SECURITY;

-- RLS Policies
CREATE POLICY "{table_name}_select_own"
  ON public.{table_name} FOR SELECT
  USING (auth.uid() = user_id);

CREATE POLICY "{table_name}_insert_own"
  ON public.{table_name} FOR INSERT
  WITH CHECK (auth.uid() = user_id);

CREATE POLICY "{table_name}_update_own"
  ON public.{table_name} FOR UPDATE
  USING (auth.uid() = user_id)
  WITH CHECK (auth.uid() = user_id);

CREATE POLICY "{table_name}_delete_own"
  ON public.{table_name} FOR DELETE
  USING (auth.uid() = user_id);

Edge Function Pattern

// supabase/functions/{name}/index.ts
import { serve } from 'https://deno.land/std@0.177.0/http/server.ts'
import { createClient } from 'https://esm.sh/@supabase/supabase-js@2'

serve(async (req: Request) => {
  const authHeader = req.headers.get('Authorization')
  if (!authHeader) {
    return new Response(JSON.stringify({ error: 'Unauthorized' }), {
      status: 401,
      headers: { 'Content-Type': 'application/json' }
    })
  }

  const supabase = createClient(
    Deno.env.get('SUPABASE_URL') ?? '',
    Deno.env.get('SUPABASE_ANON_KEY') ?? '',
    { global: { headers: { Authorization: authHeader } } }
  )

  // Never use service_role key in Edge Functions unless absolutely necessary
  const { data: { user }, error } = await supabase.auth.getUser()
  if (error || !user) {
    return new Response(JSON.stringify({ error: 'Unauthorized' }), { status: 401 })
  }

  // ... handler logic
})

Rules

• Enable RLS on EVERY table with user data. No exceptions.
• Never expose service_role key to client code.
• Always use supabase gen types typescript for type safety.
• Migrations are append-only (never modify existing migration files).
• Test with supabase start before deploying.

SKILL: TDD Workflow

The RED → GREEN → REFACTOR Cycle

RED Phase (QA Agent)

1. Read the acceptance criterion or task description.
2. Write a test that will fail because the implementation doesn't exist.
3. Run the test. It MUST fail with a meaningful error (not a syntax error).
4. If the test passes immediately → the test is wrong. Rewrite it.
5. Report: file path, test name, failure message.

GREEN Phase (Specialist Agent)

1. Read the failing test file at the provided path.
2. Implement the MINIMUM code to make ONLY that test pass.
3. Do not implement anything not required by the test.
4. Run the test. It must pass.
5. Run the full unit suite to verify no regressions.
6. If the test fails after 3 attempts → escalate to Orchestrator.

REFACTOR Phase (Specialist Agent)

1. Look for: duplication, poor naming, long functions, complex conditionals.
2. Clean up without changing behavior.
3. Run the test again. It must still pass.
4. Commit: git commit -m "refactor: {what was cleaned up}"

ATDD Pattern (Acceptance Test-Driven Development)

1. Write the E2E/acceptance test from the acceptance criterion (Given/When/Then).
2. Watch it fail (RED).
3. Drive out unit tests and implementation to make it pass (GREEN).
4. Acceptance test goes green last.

Integration Test Container Lifecycle

# Before integration tests
docker compose -f docker-compose.test.yml up -d --wait

# Run integration tests
make test-integration

# After tests
docker compose -f docker-compose.test.yml down -v

Rules

• Test file is created BEFORE implementation file.
• Test name format: "should {expected outcome} when {condition}".
• Never weaken an assertion to make a test pass.
• Never mock what you can test with a real dependency (use containers).
• Implementation agent receives FILE PATH, not requirement text.
• Gate: test must fail before implementation, pass after.

SKILL: Terraform Patterns

Module Structure

infra/terraform/
├── modules/
│   ├── networking/
│   ├── database/
│   └── compute/
└── environments/
    ├── dev/
    │   ├── main.tf
    │   ├── variables.tf
    │   └── terraform.tfvars
    ├── staging/
    └── prod/

Module Pattern

# modules/database/main.tf
resource "aws_db_instance" "main" {
  # finops: ~$180/mo (db.t3.medium, 100GB gp3, single AZ)
  identifier     = "${var.environment}-${var.name}-db"
  engine         = "postgres"
  engine_version = "16"
  instance_class = var.instance_class

  allocated_storage     = var.storage_gb
  storage_type          = "gp3"
  storage_encrypted     = true

  username = var.username
  password = var.password

  vpc_security_group_ids = [aws_security_group.db.id]
  db_subnet_group_name   = aws_db_subnet_group.main.name

  backup_retention_period = var.environment == "prod" ? 7 : 1
  deletion_protection     = var.environment == "prod"

  tags = merge(var.tags, {
    Environment = var.environment
    ManagedBy   = "terraform"
  })
}

Workflow

# Initialize (first time or after provider changes)
terraform init

# Format check (CI)
terraform fmt -check -recursive

# Validate syntax
terraform validate

# Plan (always before apply)
terraform plan -out=plan.tfplan -var-file=environments/dev/terraform.tfvars

# Apply (requires explicit instruction)
terraform apply plan.tfplan

# State inspection
terraform show
terraform state list

Rules

• ALWAYS run terraform validate before reporting complete.
• ALWAYS run terraform plan to show what will change.
• NEVER run terraform apply without explicit instruction.
• ALWAYS annotate resources with # finops: cost estimate.
• Use workspaces or separate state files per environment.
• Enable state locking (S3 + DynamoDB or Terraform Cloud).
• Tag all resources with environment, managed-by, and cost-center.

SKILL: Threat Modeling (STRIDE)

Output Location

docs/specs/{feature-slug}/threat-model.md

STRIDE Framework

For each component and trust boundary, evaluate all 6 threat categories:

Threat Model Template

# Threat Model: {Feature Name}

## Assets
| Asset | Sensitivity | Owner |
|-------|-------------|-------|
| User PII | High | {team} |
| Payment data | Critical | {team} |
| API keys | Critical | {team} |

## Trust Boundaries
- Internet <-> Load Balancer
- Load Balancer <-> Application
- Application <-> Database
- Application <-> Third-party APIs

## STRIDE Analysis

### {Component Name}

**S — Spoofing**
- Risk: {description}
- Likelihood: High/Medium/Low
- Impact: High/Medium/Low
- Mitigation: {control}

**T — Tampering**
...

**R — Repudiation**
...

**I — Information Disclosure**
...

**D — Denial of Service**
...

**E — Elevation of Privilege**
...

## Risk Register
| Threat | Component | Likelihood | Impact | Risk Level | Mitigation | Status |
|--------|-----------|------------|--------|------------|------------|--------|
| SQL Injection | API | High | Critical | Critical | Parameterized queries | Mitigated |

## Mitigations Required Before Launch
- [ ] {Critical mitigation 1}
- [ ] {Critical mitigation 2}

Common Mitigations

• Authentication: JWT with short expiry, refresh token rotation.
• Authorization: RBAC, RLS on database.
• Input validation: Zod/FluentValidation on all inputs.
• Rate limiting: Per-IP and per-user limits.
• Encryption: TLS 1.3 in transit, AES-256 at rest.
• Audit logging: All write operations logged with actor + timestamp.
• Secrets management: Never in code; use environment variables or vault.

SKILL: Vercel Patterns

vercel.json Configuration

{
  "framework": "nextjs",
  "buildCommand": "npm run build",
  "devCommand": "npm run dev",
  "installCommand": "npm ci",
  "regions": ["iad1"],
  "headers": [
    {
      "source": "/api/(.*)",
      "headers": [
        { "key": "X-Content-Type-Options", "value": "nosniff" },
        { "key": "X-Frame-Options", "value": "DENY" },
        { "key": "Strict-Transport-Security", "value": "max-age=31536000" }
      ]
    }
  ],
  "rewrites": [],
  "redirects": [
    {
      "source": "/old-path",
      "destination": "/new-path",
      "permanent": true
    }
  ]
}

Runtime Selection

// Edge Runtime (low-latency, streaming, middleware)
export const runtime = 'edge';

// Node.js Runtime (heavy compute, native modules, file system)
export const runtime = 'nodejs';

// ISR (static with revalidation)
export const revalidate = 3600; // seconds

Environment Variables

# Pull env vars for local development
vercel env pull .env.local

# Add env var
vercel env add SECRET_KEY production

# List env vars
vercel env ls

Deployment Workflow

# Build locally first (catch errors before deploy)
vercel build

# Deploy prebuilt (faster, recommended for CI)
vercel deploy --prebuilt

# Deploy to production
vercel deploy --prod --prebuilt

Middleware Pattern

// middleware.ts (runs at edge, before every request)
import { NextResponse } from 'next/server';
import type { NextRequest } from 'next/server';

export function middleware(request: NextRequest) {
  // Auth check, rate limiting, A/B testing, etc.
  const token = request.cookies.get('token');
  if (!token && request.nextUrl.pathname.startsWith('/dashboard')) {
    return NextResponse.redirect(new URL('/login', request.url));
  }
  return NextResponse.next();
}

export const config = {
  matcher: ['/dashboard/:path*', '/api/protected/:path*'],
};

Rules

• Run vercel build locally before deploying to catch errors.
• Use vercel env pull to sync environment variables locally.
• Prefer Edge runtime for middleware and simple API routes.
• Use Node.js runtime for heavy compute or native module requirements.
• Set security headers for all API routes.

SKILL: visual-identity

Purpose

Produce a coherent visual identity from a brief or set of brand keywords. Outputs are palette, typography pairing, spacing scale, and radius scale — all serialised to JSON files that feed the design-tokens skill. Human approval required before tokens propagate to UI.

Inputs

Outputs

Target awareness

When design.target (project.config.yaml, default web) is tui, keep the same JSON outputs but constrain choices to the terminal: colors must be expressible in ANSI-256 (record the nearest 256 index alongside each hex), every fg/bg role pair must clear WCAG 2.2 AA contrast, and typography.json describes terminal text styles (bold, dim/faint, italic, underline, reverse) rather than font families and px sizes. The palette/typography/scale templates below still apply structurally; adapt their values for the terminal.

Palette Structure

docs/design/identity/palette.json:

{
  "brand": {
    "primary":   { "value": "#2563eb", "on": "#ffffff", "contrast_aa": true },
    "secondary": { "value": "#7c3aed", "on": "#ffffff", "contrast_aa": true },
    "accent":    { "value": "#0ea5e9", "on": "#ffffff", "contrast_aa": true }
  },
  "semantic": {
    "success":  { "value": "#16a34a", "on": "#ffffff", "contrast_aa": true },
    "warning":  { "value": "#d97706", "on": "#000000", "contrast_aa": true },
    "error":    { "value": "#dc2626", "on": "#ffffff", "contrast_aa": true },
    "info":     { "value": "#0284c7", "on": "#ffffff", "contrast_aa": true }
  },
  "neutral": {
    "50":  "#f8fafc",
    "100": "#f1f5f9",
    "200": "#e2e8f0",
    "300": "#cbd5e1",
    "400": "#94a3b8",
    "500": "#64748b",
    "600": "#475569",
    "700": "#334155",
    "800": "#1e293b",
    "900": "#0f172a"
  },
  "surface": {
    "background": "#ffffff",
    "foreground": "#0f172a",
    "muted":      "#f1f5f9",
    "border":     "#e2e8f0"
  }
}

WCAG Contrast Check

All palette entries with on values must pass WCAG 2.2 AA (4.5:1 for normal text, 3:1 for large text):

def relative_luminance(hex_color):
    r, g, b = (int(hex_color[i:i+2], 16) / 255 for i in (1, 3, 5))
    def linearize(c):
        return c / 12.92 if c <= 0.04045 else ((c + 0.055) / 1.055) ** 2.4
    r, g, b = linearize(r), linearize(g), linearize(b)
    return 0.2126 * r + 0.7152 * g + 0.0722 * b

def contrast_ratio(fg, bg):
    l1 = relative_luminance(fg)
    l2 = relative_luminance(bg)
    lighter, darker = max(l1, l2), min(l1, l2)
    return (lighter + 0.05) / (darker + 0.05)

# AA normal text requires >= 4.5
# AA large text requires >= 3.0
ratio = contrast_ratio("#2563eb", "#ffffff")
assert ratio >= 4.5, f"FAIL: contrast {ratio:.2f} < 4.5 for #2563eb on #ffffff"

If any pair fails AA, adjust the shade until it passes. Never ship a palette with failing contrast.

Typography Structure

docs/design/identity/typography.json:

{
  "families": {
    "sans":  "Inter, system-ui, -apple-system, sans-serif",
    "mono":  "JetBrains Mono, 'Fira Code', monospace",
    "serif": null
  },
  "scale": {
    "xs":   { "size": "0.75rem",  "line": "1rem" },
    "sm":   { "size": "0.875rem", "line": "1.25rem" },
    "base": { "size": "1rem",     "line": "1.5rem" },
    "lg":   { "size": "1.125rem", "line": "1.75rem" },
    "xl":   { "size": "1.25rem",  "line": "1.75rem" },
    "2xl":  { "size": "1.5rem",   "line": "2rem" },
    "3xl":  { "size": "1.875rem", "line": "2.25rem" },
    "4xl":  { "size": "2.25rem",  "line": "2.5rem" }
  },
  "weights": {
    "regular": 400,
    "medium":  500,
    "semibold": 600,
    "bold":    700
  }
}

Spacing + Radius Scales

Written directly into tokens.json (see design-tokens skill for full schema):

{
  "spacing": {
    "1":  "0.25rem",
    "2":  "0.5rem",
    "3":  "0.75rem",
    "4":  "1rem",
    "6":  "1.5rem",
    "8":  "2rem",
    "12": "3rem",
    "16": "4rem"
  },
  "radius": {
    "none": "0",
    "sm":   "0.125rem",
    "md":   "0.375rem",
    "lg":   "0.5rem",
    "xl":   "0.75rem",
    "full": "9999px"
  }
}

Write palette.json

mkdir -p docs/design/identity
# Write palette.json from the template above, populated with chosen values
# Then validate all contrast ratios before writing
python3 scripts/validate-palette.py docs/design/identity/palette.json

Approval Gate

Mark docs/design/identity/palette.json approved before design-tokens runs:

Add to the top of palette.json:

{ "_meta": { "status": "draft", "approved_by": null, "approved_at": null }, ... }

Check in design-tokens skill:

STATUS=$(python3 -c "import json; print(json.load(open('docs/design/identity/palette.json'))['_meta']['status'])")
[ "$STATUS" = "approved" ] || { echo "BLOCKED: palette not approved"; exit 1; }

Failure Modes

Logging

[visual-identity] PALETTE    docs/design/identity/palette.json  contrast=all-pass
[visual-identity] TYPOGRAPHY docs/design/identity/typography.json
[visual-identity] SKIP       docs/design/identity/palette.json  (approved — locked)
[visual-identity] CONTRAST_FAIL  #2563eb on #ffffff  ratio=3.8  required=4.5

SKILL: wireframe

Purpose

Generate low-fidelity wireframes from user story files. Output is deterministic — given the same story and layout hints, the same wireframe structure is produced. Three output formats: ASCII (default), SVG, HTML. Human approval is required before the wireframe feeds downstream mockup work.

Inputs

Outputs

The required files depend on design.target in project.config.yaml (default web) — see Target awareness:

A wireframe stage that produces fewer than the files required for the active target is incomplete. Do not PAUSE or mark DONE without them.

Target awareness

design.target decides which files are required:

• web — <id>.wireframe.md (ASCII) + .html (preview) + .excalidraw.
• tui — <id>.wireframe.md (ASCII/box-drawing) + .excalidraw. No .html.

Use box-drawing primitives for tui layouts, label panes/overlays/status bar, and include the keybinding legend and focus order inline in the .md. The Excalidraw generator below applies to both targets; the HTML generator is web only.

ASCII Wireframe Primitives

Use these consistently across all wireframes:

┌─────────────────────────────────┐   ← container / card
│  [Label]  [Input Field      ]   │   ← label + text input
│  [Button: Primary Action    ]   │   ← primary button
│  [Button: Secondary]            │   ← secondary button
│  ○ Option A  ○ Option B         │   ← radio group
│  ☐ Checkbox label               │   ← checkbox
│  ▼ Dropdown / Select            │   ← select / combobox
│  ──────────────────────         │   ← divider
│  ⚠ Error message text           │   ← validation error
│  ✓ Success confirmation         │   ← success state
└─────────────────────────────────┘

[Nav: Logo | Item 1 | Item 2 | CTA]  ← navigation bar
[ Sidebar  ][     Main Content    ]  ← two-column layout
[  Col 1  ][  Col 2  ][  Col 3  ]   ← three-column grid
[         Full-width Banner         ]← hero / header band

ASCII Wireframe — Example (Password Reset)

┌──────────────────────────────────────┐
│            Reset Password            │
│                                      │
│  Email                               │
│  [                              ]    │
│                                      │
│  ⚠ No account found for this email  │  ← error state
│                                      │
│  [Button: Send Reset Link       ]    │
│                                      │
│  ← Back to Login                     │
└──────────────────────────────────────┘

Generate Wireframe Files

For each story, produce all three output files. Run these steps:

STORY_FILE="docs/stories/auth-reset-password-20250416143000-0001.md"
STORY_ID=$(python3 -c "
import re
m = re.search(r'^id:\s*[\"\'](.*?)[\"\']', open('$STORY_FILE').read(), re.MULTILINE)
print(m.group(1) if m else 'unknown')
")
mkdir -p docs/design/wireframes

Step 1 — Write ${STORY_ID}.wireframe.md (ASCII layout + approval metadata):

---
story_id: "{story_id}"
story_file: "{story_file}"
status: draft          # draft | approved | rejected
approved_by: null
approved_at: null
---

## Wireframe: {story title}

### Default state
{ASCII wireframe}

### Error state
{ASCII wireframe — validation error}

### Success state
{ASCII wireframe — confirmation}

### Interaction Notes

- Tab order: {list of focusable elements in tab sequence}
- Primary action: {describe}
- Error handling: {describe visible error states}

### Approval

- [ ] Approved by product owner
- [ ] Approved by UX lead (if applicable)

Step 2 — Write ${STORY_ID}.wireframe.html (see HTML template below)

Step 3 — Write ${STORY_ID}.wireframe.excalidraw (see Excalidraw template below)

After writing the files required for the active target, verify they exist (web: md, html, excalidraw; tui: md, excalidraw):

ls docs/design/wireframes/${STORY_ID}.wireframe.md
ls docs/design/wireframes/${STORY_ID}.wireframe.excalidraw
# web target also:
ls docs/design/wireframes/${STORY_ID}.wireframe.html 2>/dev/null || true

If any required file is missing, produce it before continuing.

HTML Wireframe (web target only)

For web targets, always generate the HTML wireframe. Skip this section entirely for tui. Use multiple <section> blocks for multi-state wireframes (default, loading, error, success, empty).

cat > "docs/design/wireframes/${STORY_ID}.wireframe.html" <<'HTMLEOF'
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>Wireframe: {story title}</title>
  <style>
    * { box-sizing: border-box; font-family: monospace; }
    body { background: #e9ecef; padding: 2rem; }
    h1 { font-size: 1rem; color: #495057; margin-bottom: 1.5rem; }
    .states { display: flex; flex-wrap: wrap; gap: 1.5rem; }
    .state { background: #f8f9fa; border: 1px solid #adb5bd; border-radius: 4px; padding: 0; min-width: 360px; }
    .state-label { background: #343a40; color: #fff; font-size: .75rem; padding: .25rem .75rem; border-radius: 4px 4px 0 0; }
    .frame { padding: 1.5rem; }
    .screen-title { font-weight: bold; font-size: 1.1rem; margin-bottom: 1rem; border-bottom: 1px solid #dee2e6; padding-bottom: .5rem; }
    label { display: block; font-size: .8rem; color: #495057; margin-bottom: .2rem; margin-top: .75rem; }
    .input { border: 1px solid #868e96; padding: .4rem .6rem; width: 100%; background: #fff; }
    .btn { border: none; padding: .5rem 1rem; cursor: default; margin-top: .75rem; width: 100%; font-weight: bold; }
    .btn-primary { background: #343a40; color: #fff; }
    .btn-secondary { background: transparent; border: 1px solid #343a40; color: #343a40; }
    .error { color: #c0392b; font-size: .8rem; margin-top: .25rem; }
    .success { color: #2d6a4f; font-size: .8rem; margin-top: .25rem; }
    .link { color: #1971c2; font-size: .85rem; margin-top: .75rem; display: block; }
    .nav { display: flex; gap: 1rem; background: #343a40; color: #fff; padding: .6rem 1rem; font-size: .85rem; margin-bottom: .75rem; }
    .badge { background: #868e96; color: #fff; font-size: .7rem; padding: .1rem .4rem; border-radius: 3px; }
    .divider { border: none; border-top: 1px solid #dee2e6; margin: .75rem 0; }
    .tab-order { font-size: .7rem; color: #868e96; margin-top: 1.5rem; border-top: 1px dashed #dee2e6; padding-top: .5rem; }
  </style>
</head>
<body>
  <h1>Wireframe: {story title} — {story_id}</h1>
  <div class="states">

    <div class="state">
      <div class="state-label">Default state</div>
      <div class="frame">
        <div class="screen-title">{Screen Title}</div>
        <!-- Add form fields, buttons, content blocks here -->
        <label>Field label</label>
        <input class="input" type="text" placeholder="placeholder" disabled />
        <div class="btn btn-primary">Primary Action</div>
        <a class="link" href="#">Secondary link</a>
        <div class="tab-order">Tab order: Field → Primary Action → Secondary link</div>
      </div>
    </div>

    <div class="state">
      <div class="state-label">Error state</div>
      <div class="frame">
        <div class="screen-title">{Screen Title}</div>
        <label>Field label</label>
        <input class="input" type="text" placeholder="placeholder" disabled style="border-color:#c0392b" />
        <div class="error">⚠ Error message describing the problem</div>
        <div class="btn btn-primary">Primary Action</div>
        <div class="tab-order">Tab order: Field → Primary Action</div>
      </div>
    </div>

    <div class="state">
      <div class="state-label">Success state</div>
      <div class="frame">
        <div class="screen-title">{Screen Title}</div>
        <div class="success">✓ Success confirmation message</div>
        <div class="btn btn-secondary">Back / Next step</div>
      </div>
    </div>

  </div>
</body>
</html>
HTMLEOF

Extend with real field names, content, and states from the story Gherkin. One <div class="state"> block per Gherkin scenario.

Excalidraw Wireframe (always required)

Always generate the Excalidraw file — every story, every run. Excalidraw is the canonical editable wireframe format reviewers annotate.

Write the file as valid JSON to docs/design/wireframes/${STORY_ID}.wireframe.excalidraw. Each UI element is one entry in the elements array. Use the element templates below, copy and adapt:

python3 - <<'PYEOF'
import json, pathlib, os

story_id = os.environ.get("STORY_ID", "unknown")
out = pathlib.Path(f"docs/design/wireframes/{story_id}.wireframe.excalidraw")
out.parent.mkdir(parents=True, exist_ok=True)

# ── Element helpers ──────────────────────────────────────────────────────────
def rect(id, x, y, w, h, label="", bg="transparent", stroke="#343a40", bold=False):
    els = [{
        "id": id, "type": "rectangle", "x": x, "y": y, "width": w, "height": h,
        "angle": 0, "strokeColor": stroke, "backgroundColor": bg,
        "fillStyle": "solid", "strokeWidth": 2, "strokeStyle": "solid",
        "roughness": 1, "opacity": 100, "groupIds": [], "roundness": {"type": 3},
        "version": 1, "versionNonce": 1, "isDeleted": False,
        "boundElements": None, "updated": 1, "link": None, "locked": False,
    }]
    if label:
        els.append(text(id + "_lbl", x + w/2, y + h/2, label, bold=bold, anchor="center"))
    return els

def text(id, x, y, content, bold=False, anchor="left", color="#343a40"):
    return {
        "id": id, "type": "text", "x": x, "y": y,
        "width": len(content) * 8, "height": 20,
        "angle": 0, "strokeColor": color, "backgroundColor": "transparent",
        "fillStyle": "solid", "strokeWidth": 1, "strokeStyle": "solid",
        "roughness": 1, "opacity": 100, "groupIds": [], "roundness": None,
        "version": 1, "versionNonce": 1, "isDeleted": False,
        "boundElements": None, "updated": 1, "link": None, "locked": False,
        "text": content, "fontSize": 16,
        "fontFamily": 3,  # monospace
        "textAlign": anchor, "verticalAlign": "middle",
        "baseline": 14, "containerId": None, "originalText": content,
        "lineHeight": 1.25,
        "fontWeight": "bold" if bold else "normal",
    }

def input_field(id, x, y, w, label_text):
    return (
        [text(id + "_lbl", x, y - 18, label_text)] +
        rect(id, x, y, w, 32, stroke="#868e96")
    )

def button_primary(id, x, y, w, label_text):
    return rect(id, x, y, w, 36, label=label_text, bg="#343a40", stroke="#343a40", bold=True)

def button_secondary(id, x, y, w, label_text):
    return rect(id, x, y, w, 36, label=label_text, bg="transparent", stroke="#343a40")

def section_label(id, x, y, content):
    return [text(id, x, y, f"[ {content} ]", color="#868e96")]

# ── Build elements ────────────────────────────────────────────────────────────
elements = []

# Outer frame
elements += rect("frame", 50, 30, 700, 600, stroke="#343a40")

# Screen title
elements.append(text("title", 70, 50, "{Screen Title}", bold=True))

# --- Default state ---
elements += section_label("s_default", 70, 90, "Default state")
elements += input_field("field1", 70, 130, 560, "Field label")
elements += button_primary("btn_primary", 70, 190, 560, "Primary Action")
elements.append(text("link1", 70, 238, "← Secondary link / back", color="#1971c2"))

# --- Error state ---
elements += section_label("s_error", 70, 280, "Error state")
elements += input_field("field1_err", 70, 320, 560, "Field label")
elements += rect("err_border", 70, 320, 560, 32, stroke="#c0392b")
elements.append(text("err_msg", 70, 360, "⚠ Error message text", color="#c0392b"))
elements += button_primary("btn_primary_err", 70, 390, 560, "Primary Action")

# --- Success state ---
elements += section_label("s_success", 70, 450, "Success state")
elements.append(text("success_msg", 70, 490, "✓ Success confirmation", color="#2d6a4f"))
elements += button_secondary("btn_back", 70, 520, 260, "Back / Next step")

doc = {
    "type": "excalidraw",
    "version": 2,
    "source": "MAPLE wireframe-architect",
    "elements": elements,
    "appState": {"viewBackgroundColor": "#f8f9fa", "gridSize": None},
    "files": {},
}
out.write_text(json.dumps(doc, indent=2) + "\n")
print(f"[wireframe] wrote {out}")
PYEOF

Adapt element positions and labels to match the actual story screens. Add more rect/text/input_field/button_primary calls per Gherkin scenario. Do not leave placeholder text ({Screen Title}) in the final file.

Approval Gate

All three files must exist and the .md must be status: approved before mockup or ui-mockup-builder proceeds:

python3 - <<'EOF'
import re, sys, pathlib
sid = open(".claude/state/maple.json").read()  # or pass STORY_ID
# Check required artifacts exist (html is web-only)
cfg = open("project.config.yaml").read() if pathlib.Path("project.config.yaml").exists() else ""
tm = re.search(r'^\s*target:\s*(\w+)', cfg, re.MULTILINE)
target = tm.group(1) if tm else "web"
exts = ["md", "excalidraw"] if target == "tui" else ["md", "html", "excalidraw"]
for ext in exts:
    p = pathlib.Path(f"docs/design/wireframes/{sid}.wireframe.{ext}")
    if not p.exists():
        print(f"BLOCKED: missing {p}")
        sys.exit(1)
# Check approval status in .md
md = pathlib.Path(f"docs/design/wireframes/{sid}.wireframe.md").read_text()
m = re.search(r'^status:\s*(\w+)', md, re.MULTILINE)
status = m.group(1) if m else 'draft'
if status != 'approved':
    print(f"BLOCKED: wireframe {sid} not approved (status={status})")
    sys.exit(1)
print("approved — all three artifacts present")
EOF

Failure Modes

Logging

[wireframe] CREATE   docs/design/wireframes/auth-reset-0001.wireframe.md
[wireframe] CREATE   docs/design/wireframes/auth-reset-0001.wireframe.html
[wireframe] CREATE   docs/design/wireframes/auth-reset-0001.wireframe.excalidraw
[wireframe] SKIP     docs/design/wireframes/auth-reset-0001.wireframe.md  (approved — locked)
[wireframe] BLOCKED  auth-reset-0001  status=draft — needs approval before mockup
[wireframe] BLOCKED  auth-reset-0001  missing .html — generating now

SKILL: a11y-audit

Purpose

Run WCAG 2.2 Level AA accessibility audits against generated UI. Uses axe-core (via @axe-core/cli) or pa11y as available. Posts findings as PR comments. Blocks merge on AA violations. Required for every story with ui: true.

Target awareness

When design.target (project.config.yaml, default web) is tui, skip the browser tooling (axe/pa11y) and the preview URL. Instead evaluate the terminal a11y checklist from docs/design/design-targets.md and write the findings to docs/design/mockups/<id>.a11y.json using the SAME object shape the web path produces — an object with violations[], where each violation has id, impact (critical|serious|moderate|minor), description, help, and nodes[] ({target:[...], failureSummary}). The gate (scripts/sdlc/a11y-gate.sh) reads only violations[].impact, so matching this shape keeps it unchanged. Map checklist failures to impacts: keyboard-reachable→critical, focus-visible→serious, color-contrast→serious, color-only-signaling→serious, no-color-support→moderate, min-width-resize→moderate. The WCAG criteria, tool-detection, axe/pa11y, and PR-comment sections below apply to web targets.

WCAG 2.2 AA — Minimum Requirements

Tool Detection

detect_tool() {
  if command -v axe &>/dev/null; then
    echo "axe"
  elif command -v pa11y &>/dev/null; then
    echo "pa11y"
  elif npx --yes @axe-core/cli --version &>/dev/null 2>&1; then
    echo "axe-npx"
  else
    echo "none"
  fi
}
TOOL=$(detect_tool)

Run with axe-core CLI

URL="${1:-http://localhost:3000}"  # preview URL or Storybook story URL
STORY_ID="${2:-unknown}"
REPORT="docs/design/mockups/${STORY_ID}.a11y.json"

mkdir -p docs/design/mockups

axe "$URL" \
  --stdout \
  --tags wcag2a,wcag2aa,wcag21aa,wcag22aa \
  > "$REPORT"

VIOLATIONS=$(python3 -c "import json,sys; d=json.load(open('$REPORT')); print(len(d.get('violations',[])))")
echo "[a11y-audit] axe  $URL  violations=$VIOLATIONS"

Run with pa11y

URL="${1:-http://localhost:3000}"
STORY_ID="${2:-unknown}"
REPORT="docs/design/mockups/${STORY_ID}.a11y.json"

pa11y "$URL" \
  --standard WCAG2AA \
  --reporter json \
  > "$REPORT" 2>&1

ISSUES=$(python3 -c "import json,sys; d=json.load(open('$REPORT')); print(len(d) if isinstance(d,list) else 0)")
echo "[a11y-audit] pa11y  $URL  issues=$ISSUES"

Parse Results and Classify

import json, sys

report_path = sys.argv[1]
data = json.load(open(report_path))

# axe format
violations = data.get("violations", [])
passes     = data.get("passes", [])

critical = [v for v in violations if v["impact"] in ("critical", "serious")]
moderate = [v for v in violations if v["impact"] == "moderate"]
minor    = [v for v in violations if v["impact"] == "minor"]

print(f"CRITICAL/SERIOUS: {len(critical)}")
print(f"MODERATE:         {len(moderate)}")
print(f"MINOR:            {len(minor)}")
print(f"PASSES:           {len(passes)}")

# Merge gate: block on critical + serious
if critical:
    print("\nMERGE BLOCKED — resolve the following before merging:")
    for v in critical:
        print(f"  [{v['impact'].upper()}] {v['id']}: {v['description']}")
        for node in v.get("nodes", [])[:2]:
            print(f"    → {node.get('target', ['?'])[0]}: {node.get('failureSummary','')[:120]}")
    sys.exit(1)

Post Findings as PR Comment

STORY_ID="auth-reset-0001"
PR_NUMBER=$(gh pr list --head "$(git branch --show-current)" --json number --jq '.[0].number')
REPORT="docs/design/mockups/${STORY_ID}.a11y.json"

# Build comment body
COMMENT=$(python3 - <<'EOF'
import json, sys

data = json.load(open(sys.argv[1]))
violations = data.get("violations", [])

if not violations:
    print("## ✅ A11y Audit Passed\n\nNo WCAG 2.2 AA violations found.")
    sys.exit(0)

lines = [f"## ⚠️ A11y Audit: {len(violations)} violation(s) found\n"]
for v in violations[:10]:
    impact = v.get("impact","").upper()
    lines.append(f"### [{impact}] {v['id']}")
    lines.append(f"_{v['description']}_\n")
    for node in v.get("nodes",[])[:2]:
        selector = ', '.join(node.get("target",[]))
        lines.append(f"- `{selector}`")
        lines.append(f"  {node.get('failureSummary','')[:200]}")
    lines.append("")

if len(violations) > 10:
    lines.append(f"_...and {len(violations)-10} more. See full report in `docs/design/mockups/`._")

print('\n'.join(lines))
EOF
"$REPORT")

gh pr comment "$PR_NUMBER" --body "$COMMENT"
echo "[a11y-audit] PR_COMMENT  #$PR_NUMBER  violations=$(echo "$COMMENT" | grep -c '\[CRITICAL\]\|\[SERIOUS\]' || echo 0)"

Merge Gate Check

Called from scripts/sdlc/a11y-gate.sh (added in Phase VII):

STORY_FILE="$1"
UI=$(python3 -c "
import re
m = re.search(r'^ui:\s*(true|false)', open('$STORY_FILE').read(), re.MULTILINE)
print(m.group(1) if m else 'false')
")

if [ "$UI" != "true" ]; then
  echo "[a11y-audit] SKIP  ui:false story — no audit required"
  exit 0
fi

STORY_ID=$(python3 -c "
import re
m = re.search(r'^id:\s*[\"\'](.*?)[\"\']', open('$STORY_FILE').read(), re.MULTILINE)
print(m.group(1) if m else 'unknown')
")
REPORT="docs/design/mockups/${STORY_ID}.a11y.json"

if [ ! -f "$REPORT" ]; then
  echo "[a11y-audit] FAIL  no audit report found for $STORY_ID — run audit before merging"
  exit 1
fi

python3 scripts/sdlc/parse-a11y-report.py "$REPORT"

Manual Audit Checklist (no tool available)

When TOOL=none, perform a structured manual check:

## Manual A11y Checklist — {story_id}

### Perceivable
- [ ] All images have meaningful `alt` text (or `alt=""` for decorative)
- [ ] Color is not the sole means of conveying information
- [ ] Normal text contrast ≥ 4.5:1 (check with browser DevTools)
- [ ] Large text contrast ≥ 3:1

### Operable
- [ ] Tab through the entire form/component with keyboard only
- [ ] All actions reachable without mouse
- [ ] No keyboard trap
- [ ] Focus indicator visible on every interactive element

### Understandable
- [ ] Form inputs have visible labels (not just placeholders)
- [ ] Errors described in text, not color alone
- [ ] Error messages are specific and actionable

### Robust
- [ ] Correct semantic elements: `<button>`, `<input>`, `<label>`
- [ ] ARIA attributes only where native HTML is insufficient
- [ ] Works with browser zoom at 200%

Failure Modes

Logging

[a11y-audit] RUN      http://localhost:6006/... story=auth-reset-0001  tool=axe
[a11y-audit] RESULT   violations=0  passes=24  WCAG2AA=PASS
[a11y-audit] RESULT   violations=3  critical=1  WCAG2AA=FAIL
[a11y-audit] PR_COMMENT  #42  violations=1
[a11y-audit] SKIP     ui:false story — audit not required
[a11y-audit] BLOCKED  merge blocked — 1 critical violation unresolved

SKILL: component-scaffold

Purpose

Generate a complete component file tree wired to design tokens. Each component gets an implementation file, Storybook story, unit test, and Gherkin spec file. Skeletons are runnable with TODO stubs — not empty files. Stack is auto-detected from project.config.yaml.

Inputs

Output Tree

For PasswordResetForm with stack react-mantine:

app/
└── components/
    └── PasswordResetForm/
        ├── index.tsx              ← component implementation
        ├── PasswordResetForm.stories.tsx  ← Storybook story
        ├── PasswordResetForm.test.tsx     ← unit tests (Vitest / Jest)
        └── PasswordResetForm.spec.ts      ← Gherkin step binding

Generate Component Index (react-mantine)

app/components/{ComponentName}/index.tsx:

// {ComponentName} — generated from story {story_id}
// Tokens: docs/design/identity/mantine.theme.ts
// TODO: implement from mockup docs/design/mockups/{story_id}.mockup.tsx

import { Stack, TextInput, Button } from '@mantine/core';
import { useState } from 'react';

export interface {ComponentName}Props {
  // TODO: define props from story acceptance criteria
  onSubmit?: (data: Record<string, unknown>) => void;
}

export function {ComponentName}({ onSubmit }: {ComponentName}Props) {
  // TODO: implement
  return (
    <Stack>
      {/* TODO: build from approved mockup */}
    </Stack>
  );
}

export default {ComponentName};

Generate Storybook Story

app/components/{ComponentName}/{ComponentName}.stories.tsx:

import type { Meta, StoryObj } from '@storybook/react';
import { {ComponentName} } from '.';

const meta: Meta<typeof {ComponentName}> = {
  title: 'Components/{ComponentName}',
  component: {ComponentName},
  parameters: {
    layout: 'centered',
  },
  tags: ['autodocs'],
};
export default meta;
type Story = StoryObj<typeof {ComponentName}>;

export const Default: Story = {
  args: {},
};

export const WithError: Story = {
  args: {
    // TODO: add error props
  },
};

Generate Unit Test

app/components/{ComponentName}/{ComponentName}.test.tsx:

import { render, screen } from '@testing-library/react';
import { describe, it, expect } from 'vitest';
import { {ComponentName} } from '.';

describe('{ComponentName}', () => {
  it('renders without crashing', () => {
    render(<{ComponentName} />);
    // TODO: assert presence of key elements from wireframe
    expect(document.body).toBeTruthy();
  });

  it('calls onSubmit when form is submitted', () => {
    // TODO: implement interaction test
  });

  it('shows validation error when input is invalid', () => {
    // TODO: implement error state test
  });
});

Generate Gherkin Step Binding

app/components/{ComponentName}/{ComponentName}.spec.ts:

// Gherkin step bindings for story {story_id}
// Feature file: tests/features/{epic}/{story_slug}.feature
import { Given, When, Then } from '@cucumber/cucumber';

// TODO: copy matching steps from cucumber-automation output
// Example:
// Given('the user is on the {string} page', async (page: string) => {
//   throw new Error('Pending');
// });

Python Stack Alternative

For stack=python (e.g., Django / HTMX):

app/
└── components/
    └── password_reset_form/
        ├── __init__.py
        ├── template.html
        ├── test_password_reset_form.py
        └── password_reset_form_steps.py

Scaffold Script

COMPONENT="PasswordResetForm"
STORY_ID="auth-reset-0001"
STACK="react-mantine"
DIR="app/components/$COMPONENT"

mkdir -p "$DIR"

# Check for existing files — never overwrite
for f in "index.tsx" "${COMPONENT}.stories.tsx" "${COMPONENT}.test.tsx" "${COMPONENT}.spec.ts"; do
  if [ -f "$DIR/$f" ]; then
    echo "[component-scaffold] SKIP  $DIR/$f  (already exists)"
  else
    echo "[component-scaffold] CREATE  $DIR/$f"
    # write the appropriate template (see above)
  fi
done

Token Wiring

After scaffold, inject token import into index.tsx:

# Verify mantine.theme.ts exists
[ -f "docs/design/identity/mantine.theme.ts" ] || \
  echo "[component-scaffold] WARN  mantine.theme.ts missing — run design-tokens skill"

Failure Modes

Logging

[component-scaffold] CREATE  app/components/PasswordResetForm/index.tsx
[component-scaffold] CREATE  app/components/PasswordResetForm/PasswordResetForm.stories.tsx
[component-scaffold] CREATE  app/components/PasswordResetForm/PasswordResetForm.test.tsx
[component-scaffold] CREATE  app/components/PasswordResetForm/PasswordResetForm.spec.ts
[component-scaffold] SKIP    app/components/PasswordResetForm/index.tsx  (already exists)
[component-scaffold] WARN    mantine.theme.ts missing

SKILL: cucumber-automation

Purpose

Extract Gherkin scenarios from story markdown files into runnable .feature files, and generate step definition stubs for the project's test stack. Keeps tests/features/ in sync with docs/stories/ as the single source of Gherkin truth.

Supported Stacks

Detect the stack from the repo root:

if [ -f "package.json" ] && grep -q "@cucumber/cucumber" package.json 2>/dev/null; then
  STACK="typescript"
elif [ -f "requirements.txt" ] && grep -q "behave" requirements.txt 2>/dev/null; then
  STACK="python"
elif [ -f "pom.xml" ] || [ -f "build.gradle" ]; then
  STACK="java"
else
  STACK="unknown"
fi

Extract Gherkin from a Story File

Story files contain Gherkin in fenced code blocks tagged with gherkin:

STORY_FILE="docs/stories/user-auth-reset-password-20250416143000-0001.md"
EPIC="user-auth"

# Extract content of ```gherkin ... ``` blocks
python3 - <<'EOF'
import re, sys

story = open(sys.argv[1]).read()
blocks = re.findall(r'```gherkin\n(.*?)```', story, re.DOTALL)
if not blocks:
    print("NO_GHERKIN", file=sys.stderr)
    sys.exit(1)
print('\n\n'.join(blocks))
EOF "$STORY_FILE"

Write the Feature File

STORY_FILE="docs/stories/user-auth-reset-password-20250416143000-0001.md"
FEATURE_DIR="tests/features"
EPIC="user-auth"

mkdir -p "$FEATURE_DIR/$EPIC"
FEATURE_FILE="$FEATURE_DIR/$EPIC/reset-password.feature"

# Extract and write (idempotent — overwrites if Gherkin changed)
python3 - <<'EOF'
import re, sys, os

story_path, feature_path = sys.argv[1], sys.argv[2]
story = open(story_path).read()
blocks = re.findall(r'```gherkin\n(.*?)```', story, re.DOTALL)
if not blocks:
    print(f"[cucumber] NO_GHERKIN in {story_path}", file=sys.stderr)
    sys.exit(1)

os.makedirs(os.path.dirname(feature_path), exist_ok=True)
with open(feature_path, 'w') as f:
    f.write('\n\n'.join(b.rstrip() for b in blocks))
    f.write('\n')

print(f"[cucumber] WRITE  {feature_path}  scenarios={len(re.findall(r'^  Scenario', ''.join(blocks), re.MULTILINE))}")
EOF "$STORY_FILE" "$FEATURE_FILE"

Generate Step Definition Stubs (TypeScript)

FEATURE_FILE="tests/features/user-auth/reset-password.feature"
STEPS_DIR="tests/step-definitions/user-auth"
mkdir -p "$STEPS_DIR"

python3 - <<'EOF'
import re, sys, os

feature_path = sys.argv[1]
steps_dir = sys.argv[2]
feature = open(feature_path).read()

# Collect unique step texts
steps = re.findall(r'^\s+(Given|When|Then|And|But) (.+)$', feature, re.MULTILINE)
seen = set()
unique = []
for keyword, text in steps:
    norm = re.sub(r'"[^"]+"', '"{string}"', text)
    norm = re.sub(r'\b\d+\b', '{int}', norm)
    if norm not in seen:
        seen.add(norm)
        unique.append((keyword if keyword not in ('And','But') else 'Given', norm, text))

# Build TypeScript file
feature_name = os.path.basename(feature_path).replace('.feature','')
out_path = os.path.join(steps_dir, f"{feature_name}.steps.ts")

if os.path.exists(out_path):
    print(f"[cucumber] SKIP  {out_path}  (already exists)")
    sys.exit(0)

lines = [
    "import { Given, When, Then } from '@cucumber/cucumber';",
    "",
]
for keyword, pattern, original in unique:
    fn = keyword.lower()
    # build parameter list from placeholders
    params = []
    if '{string}' in pattern:
        params += [f"arg{i}: string" for i in range(pattern.count('{string}'))]
    if '{int}' in pattern:
        params += [f"n{i}: number" for i in range(pattern.count('{int}'))]
    param_str = ', '.join(params)
    escaped = pattern.replace("'", "\\'")
    lines += [
        f"// {original}",
        f"{fn}('{escaped}', async ({param_str}) => {{",
        f"  // TODO: implement",
        f"  throw new Error('Pending: {escaped}');",
        f"}});",
        "",
    ]

with open(out_path, 'w') as f:
    f.write('\n'.join(lines))

print(f"[cucumber] STUBS  {out_path}  steps={len(unique)}")
EOF "$FEATURE_FILE" "$STEPS_DIR"

Generate Step Definition Stubs (Python / behave)

FEATURE_FILE="tests/features/user_auth/reset_password.feature"
STEPS_DIR="tests/features/user_auth"
mkdir -p "$STEPS_DIR"

python3 - <<'EOF'
import re, sys, os

feature_path = sys.argv[1]
steps_dir = sys.argv[2]
feature = open(feature_path).read()

steps = re.findall(r'^\s+(Given|When|Then|And|But) (.+)$', feature, re.MULTILINE)
seen = set()
unique = []
for keyword, text in steps:
    norm = re.sub(r'"[^"]+"', '"{text}"', text)
    norm = re.sub(r'\b\d+\b', '{n:d}', norm)
    if norm not in seen:
        seen.add(norm)
        unique.append((keyword if keyword not in ('And','But') else 'given', norm, text))

feature_name = os.path.basename(feature_path).replace('.feature','')
out_path = os.path.join(steps_dir, f"{feature_name}_steps.py")

if os.path.exists(out_path):
    print(f"[cucumber] SKIP  {out_path}  (already exists)")
    sys.exit(0)

lines = ["from behave import given, when, then", ""]
for keyword, pattern, original in unique:
    fn = keyword.lower()
    escaped = pattern.replace('"', '\\"')
    lines += [
        f"# {original}",
        f'@{fn}(u"{escaped}")',
        f"def step_impl(context):",
        f'    raise NotImplementedError(u"STEP: {fn} {escaped}")',
        "",
    ]

with open(out_path, 'w') as f:
    f.write('\n'.join(lines))

print(f"[cucumber] STUBS  {out_path}  steps={len(unique)}")
EOF "$FEATURE_FILE" "$STEPS_DIR"

Batch Sync (all stories → all feature files)

find docs/stories -name "*.md" ! -name "_template.md" | while read -r story; do
  EPIC=$(python3 -c "
import re
m = re.search(r'^epic:\s*[\"\'](.*?)[\"\']', open('$story').read(), re.MULTILINE)
print(m.group(1) if m else 'unknown')
")
  SLUG=$(basename "$story" | sed 's/-[0-9]\{14\}-[0-9]\{4\}\.md$//')
  FEATURE_FILE="tests/features/$EPIC/$SLUG.feature"
  # extract-and-write step (see above) ...
  echo "[cucumber] SYNC  $story → $FEATURE_FILE"
done

Playwright + behave Integration

When the stack includes Playwright (requirements.txt contains playwright or behave), step definitions must follow these patterns. Read the QA agent's BDD section for the full antipatterns list.

environment.py template

import json
import threading
from playwright.sync_api import sync_playwright

BASE_URL = "http://localhost:3000"
DEFAULT_GEO = {"latitude": 40.7128, "longitude": -74.0060}

MOCK_FORECAST = {
    "daily": {
        "time": ["2025-01-01","2025-01-02","2025-01-03",
                 "2025-01-04","2025-01-05","2025-01-06","2025-01-07"],
        "temperature_2m_max": [22.1, 18.3, 15.0, 20.5, 25.2, 19.8, 17.4],
        "temperature_2m_min": [12.0, 10.5,  9.3, 13.2, 16.1, 11.4, 10.9],
        "weathercode":        [0,    3,     61,   0,    1,    80,   71 ],
        "precipitation_probability_max": [5, 30, 85, 10, 20, 70, 60],
        "windspeed_10m_max":  [12.0, 20.5, 35.2, 8.4, 15.6, 28.9, 22.3],
        "relative_humidity_2m_max": [55, 72, 90, 48, 62, 85, 78],
    }
}

def before_all(context):
    context.playwright = sync_playwright().start()
    context.browser = context.playwright.chromium.launch()

def after_all(context):
    context.browser.close()
    context.playwright.stop()

def before_scenario(context, scenario):
    context.browser_context = context.browser.new_context(
        permissions=["geolocation"],
        geolocation=DEFAULT_GEO,
    )
    context.page = context.browser_context.new_page()
    context._forecast_event = None

def after_scenario(context, scenario):
    context.page.close()
    context.browser_context.close()

# ── Helpers ────────────────────────────────────────────────────────────────────

def setup_forecast_route(page, error=False, delay_event=None):
    """Network-level Open-Meteo intercept. NEVER overrides window.fetch."""
    def handle(route):
        if delay_event is not None:
            delay_event.wait(timeout=30)
        if error:
            route.fulfill(status=500, content_type="application/json",
                          body='{"error":"service unavailable"}')
        else:
            route.fulfill(status=200, content_type="application/json",
                          body=json.dumps(MOCK_FORECAST))
    page.route("**/api.open-meteo.com/**", handle)

def navigate_and_wait(page):
    page.goto(BASE_URL, wait_until="domcontentloaded")
    page.wait_for_selector(".forecast-card", timeout=10_000)

Browser capability scenarios

# Geolocation granted — default, handled by before_scenario

# Geolocation denied — create context without the permission
context.browser_context = context.browser.new_context()  # no geolocation permission

# Geolocation unsupported — NO Playwright native API; add_init_script is acceptable HERE ONLY
context.page.add_init_script(
    "Object.defineProperty(navigator,'geolocation',{value:undefined,configurable:true});"
)

# Geolocation timeout — NO Playwright native API; add_init_script acceptable HERE ONLY
context.page.add_init_script(
    "navigator.geolocation.getCurrentPosition = function(){};"  # never calls back
)

Loading state (route with threading.Event)

# Setup step — route stays blocked until event is set
event = threading.Event()
setup_forecast_route(context.page, delay_event=event)
context._forecast_event = event

# Assert spinner visible while blocked
spinner = context.page.locator('[role="status"]')
spinner.wait_for(state="visible", timeout=3000)

# Unblock route → cards should appear
context._forecast_event.set()
context.page.wait_for_selector(".forecast-card", timeout=5000)

API error state

setup_forecast_route(context.page, error=True)
# route returns HTTP 500 — app must handle gracefully

Antipatterns checklist (rubber duck will flag these)

Failure Modes

Logging

[cucumber] WRITE   tests/features/user-auth/reset-password.feature  scenarios=3
[cucumber] STUBS   tests/step-definitions/user-auth/reset-password.steps.ts  steps=7
[cucumber] SKIP    tests/step-definitions/user-auth/login.steps.ts  (already exists)
[cucumber] NO_GHERKIN  docs/stories/auth-spike-20250416143000-0002.md  (spike — expected)

SKILL: design-tokens

Purpose

Read and write design tokens in W3C Design Token Community Group (DTCG) format (tokens.json). Emit framework-specific outputs: CSS custom properties, Tailwind config, and Mantine theme object. The tokens.json in docs/design/identity/ is the canonical source of truth; all framework outputs are derived and regenerated — never manually edited.

Token File: docs/design/identity/tokens.json

W3C DTCG format. Each token is an object with $value and $type:

{
  "$schema": "https://design-tokens.org/schema/v1.0.0",
  "_meta": { "status": "draft", "version": "1.0.0" },

  "color": {
    "brand": {
      "primary":   { "$value": "#2563eb", "$type": "color" },
      "secondary": { "$value": "#7c3aed", "$type": "color" },
      "accent":    { "$value": "#0ea5e9", "$type": "color" }
    },
    "semantic": {
      "success": { "$value": "#16a34a", "$type": "color" },
      "warning": { "$value": "#d97706", "$type": "color" },
      "error":   { "$value": "#dc2626", "$type": "color" },
      "info":    { "$value": "#0284c7", "$type": "color" }
    },
    "neutral": {
      "50":  { "$value": "#f8fafc", "$type": "color" },
      "500": { "$value": "#64748b", "$type": "color" },
      "900": { "$value": "#0f172a", "$type": "color" }
    },
    "surface": {
      "background": { "$value": "#ffffff", "$type": "color" },
      "foreground": { "$value": "#0f172a", "$type": "color" },
      "muted":      { "$value": "#f1f5f9", "$type": "color" },
      "border":     { "$value": "#e2e8f0", "$type": "color" }
    }
  },

  "typography": {
    "fontFamily": {
      "sans": { "$value": "Inter, system-ui, sans-serif", "$type": "fontFamily" },
      "mono": { "$value": "JetBrains Mono, monospace",   "$type": "fontFamily" }
    },
    "fontSize": {
      "sm":   { "$value": "0.875rem", "$type": "dimension" },
      "base": { "$value": "1rem",     "$type": "dimension" },
      "lg":   { "$value": "1.125rem", "$type": "dimension" },
      "xl":   { "$value": "1.25rem",  "$type": "dimension" },
      "2xl":  { "$value": "1.5rem",   "$type": "dimension" },
      "4xl":  { "$value": "2.25rem",  "$type": "dimension" }
    }
  },

  "spacing": {
    "1": { "$value": "0.25rem", "$type": "dimension" },
    "2": { "$value": "0.5rem",  "$type": "dimension" },
    "4": { "$value": "1rem",    "$type": "dimension" },
    "8": { "$value": "2rem",    "$type": "dimension" }
  },

  "radius": {
    "sm":   { "$value": "0.125rem", "$type": "dimension" },
    "md":   { "$value": "0.375rem", "$type": "dimension" },
    "lg":   { "$value": "0.5rem",   "$type": "dimension" },
    "full": { "$value": "9999px",   "$type": "dimension" }
  },

  "shadow": {
    "sm": { "$value": "0 1px 2px 0 rgb(0 0 0 / 0.05)", "$type": "shadow" },
    "md": { "$value": "0 4px 6px -1px rgb(0 0 0 / 0.1)", "$type": "shadow" },
    "lg": { "$value": "0 10px 15px -3px rgb(0 0 0 / 0.1)", "$type": "shadow" }
  }
}

Emit: CSS Custom Properties

Output to docs/design/identity/tokens.css:

import json, re

def flatten(obj, prefix=""):
    result = {}
    for k, v in obj.items():
        if k.startswith("$") or k.startswith("_"):
            continue
        key = f"{prefix}-{k}" if prefix else k
        if isinstance(v, dict) and "$value" in v:
            result[key] = v["$value"]
        elif isinstance(v, dict):
            result.update(flatten(v, key))
    return result

tokens = json.load(open("docs/design/identity/tokens.json"))
flat = flatten(tokens)

lines = [":root {"]
for name, value in sorted(flat.items()):
    css_var = "--" + name.replace(".", "-")
    lines.append(f"  {css_var}: {value};")
lines.append("}")

with open("docs/design/identity/tokens.css", "w") as f:
    f.write("\n".join(lines) + "\n")

print(f"[design-tokens] CSS  docs/design/identity/tokens.css  vars={len(flat)}")

Emit: Tailwind Config

Output to docs/design/identity/tailwind.tokens.js:

import json

tokens = json.load(open("docs/design/identity/tokens.json"))

def extract_colors():
    result = {}
    for group, values in tokens.get("color", {}).items():
        result[group] = {}
        for name, token in values.items():
            if "$value" in token:
                result[group][name] = token["$value"]
    return result

colors = extract_colors()
font_family = {
    k: v["$value"]
    for k, v in tokens.get("typography", {}).get("fontFamily", {}).items()
}

config = f"""/** @type {{import('tailwindcss').Config}} */
// AUTO-GENERATED — edit docs/design/identity/tokens.json, not this file
module.exports = {{
  theme: {{
    extend: {{
      colors: {json.dumps(colors, indent(6))},
      fontFamily: {json.dumps(font_family, indent(6))},
    }},
  }},
}};
"""

with open("docs/design/identity/tailwind.tokens.js", "w") as f:
    f.write(config)

print("[design-tokens] TAILWIND  docs/design/identity/tailwind.tokens.js")

Emit: Mantine Theme

Output to docs/design/identity/mantine.theme.ts:

import json

tokens = json.load(open("docs/design/identity/tokens.json"))

primary = tokens["color"]["brand"]["primary"]["$value"]
secondary = tokens["color"]["brand"]["secondary"]["$value"]

theme = f"""// AUTO-GENERATED — edit docs/design/identity/tokens.json, not this file
import {{ createTheme }} from '@mantine/core';

export const theme = createTheme({{
  primaryColor: 'brand',
  colors: {{
    brand: [
      '{tokens["color"]["neutral"]["50"]["$value"]}',
      '{tokens["color"]["neutral"]["100"]["$value"] if "100" in tokens["color"]["neutral"] else "#f1f5f9"}',
      '{tokens["color"]["neutral"]["200"]["$value"] if "200" in tokens["color"]["neutral"] else "#e2e8f0"}',
      '{tokens["color"]["neutral"]["300"]["$value"] if "300" in tokens["color"]["neutral"] else "#cbd5e1"}',
      '{tokens["color"]["neutral"]["400"]["$value"] if "400" in tokens["color"]["neutral"] else "#94a3b8"}',
      '{tokens["color"]["neutral"]["500"]["$value"]}',
      '{primary}',
      '{tokens["color"]["neutral"]["700"]["$value"] if "700" in tokens["color"]["neutral"] else "#334155"}',
      '{tokens["color"]["neutral"]["800"]["$value"] if "800" in tokens["color"]["neutral"] else "#1e293b"}',
      '{tokens["color"]["neutral"]["900"]["$value"]}',
    ],
  }},
  fontFamily: '{tokens["typography"]["fontFamily"]["sans"]["$value"]}',
  fontFamilyMonospace: '{tokens["typography"]["fontFamily"]["mono"]["$value"]}',
}});
"""

with open("docs/design/identity/mantine.theme.ts", "w") as f:
    f.write(theme)

print("[design-tokens] MANTINE  docs/design/identity/mantine.theme.ts")

Emit: Terminal Theme (tui target)

When design.target is tui, emit docs/design/identity/terminal-theme.json from tokens.json instead of the CSS/Tailwind/Mantine outputs. Map each color role to an ANSI-256 index (and the hex) plus a lipgloss style name, and record the foreground/background pairs with their contrast ratios so the a11y auditor can flag any pair under WCAG 2.2 AA. Shape:

{
  "roles": {
    "primary":    { "fg": "#7aa2f7", "ansi256": 111, "lipgloss": "primary" },
    "muted":      { "fg": "#565f89", "ansi256": 60,  "lipgloss": "muted" },
    "accent":     { "fg": "#bb9af7", "ansi256": 141, "lipgloss": "accent" },
    "error":      { "fg": "#f7768e", "ansi256": 204, "lipgloss": "error" },
    "success":    { "fg": "#9ece6a", "ansi256": 149, "lipgloss": "success" },
    "background": { "bg": "#1a1b26", "ansi256": 234 },
    "foreground": { "fg": "#c0caf5", "ansi256": 189 }
  },
  "pairs": [
    { "role": "foreground", "on": "background", "contrast": 12.6 },
    { "role": "muted",      "on": "background", "contrast": 3.4 }
  ]
}

Run All Emitters

python3 - <<'EOF'
# Run all three emitters in sequence
# (inline the three scripts above, or import from scripts/emit-tokens.py)
EOF

Update Tokens (read-write)

To update a single token value:

import json, sys

tokens = json.load(open("docs/design/identity/tokens.json"))
# Set tokens["color"]["brand"]["primary"]["$value"] = "#1d4ed8"
# Write back, then re-run all emitters
json.dump(tokens, open("docs/design/identity/tokens.json", "w"), indent=2)

Always re-emit all framework outputs after any token change.

Failure Modes

Logging

[design-tokens] READ    docs/design/identity/tokens.json  tokens=47
[design-tokens] CSS     docs/design/identity/tokens.css   vars=47
[design-tokens] TAILWIND docs/design/identity/tailwind.tokens.js
[design-tokens] MANTINE  docs/design/identity/mantine.theme.ts
[design-tokens] MISSING_TOKEN  color.neutral.100  — using placeholder

SKILL: Docker Patterns

Multi-Stage Dockerfile Pattern

# syntax=docker/dockerfile:1
FROM node:22-alpine AS base
WORKDIR /app

FROM base AS deps
COPY package*.json ./
RUN --mount=type=cache,target=/root/.npm \
    npm ci --only=production

FROM base AS dev-deps
COPY package*.json ./
RUN --mount=type=cache,target=/root/.npm \
    npm ci

FROM base AS build
COPY --from=dev-deps /app/node_modules ./node_modules
COPY . .
RUN npm run build

FROM gcr.io/distroless/nodejs22-debian12 AS production
WORKDIR /app
USER 1001
COPY --from=deps /app/node_modules ./node_modules
COPY --from=build /app/dist ./dist
EXPOSE 3000
CMD ["dist/main.js"]

docker-compose Health Check Pattern

services:
  app:
    build:
      context: .
      target: production
    ports:
      - "3000:3000"
    environment:
      DATABASE_URL: postgres://postgres:pass@db:5432/app
    depends_on:
      db:
        condition: service_healthy
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
      interval: 5s
      timeout: 5s
      retries: 5
      start_period: 10s

  db:
    image: postgres:16-alpine
    environment:
      POSTGRES_PASSWORD: pass
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 2s
      timeout: 5s
      retries: 10

.dockerignore

node_modules
.git
.github
dist
build
coverage
.next
*.log
.env*
!.env.example
README.md
docs
tests

Key Rules

• ALWAYS use multi-stage builds for production images.
• ALWAYS run as non-root user (USER 1001 or named user).
• ALWAYS add health checks to all services.
• NEVER copy .env files into images.
• Use --mount=type=cache for package manager caches.
• Use distroless or alpine base images.
• Use docker compose up -d --wait to wait for health checks.

Verification

# Build test
docker build --target production -t test-image .

# Security scan
docker run --rm -v /var/run/docker.sock:/var/run/docker.sock \
  aquasec/trivy:latest image test-image

# Start and verify health
docker compose up -d --wait
docker compose ps

SKILL: FinOps Review

Purpose

Identify and annotate the cloud cost implications of architectural decisions.

Cost Driver Categories

Compute

• Lambda/Functions: invocation count x duration x memory
• EC2/VMs: instance type x hours + data transfer
• Containers: CPU/memory reservation x hours
• Edge functions: request count x execution time

Storage

• Object storage (S3/GCS/Blob): GB stored + requests + egress
• Database: instance size + storage + IOPS + backups
• Cache: node size x hours

Networking

• Egress: GB transferred out (most expensive)
• CDN: requests + GB served
• Load balancer: hours + LCU

Third-party APIs

• Stripe: 2.9% + $0.30 per transaction
• Supabase: row reads/writes, storage, Edge Function invocations
• Vercel: bandwidth, function invocations, seats

Annotation Format (Terraform)

resource "aws_db_instance" "main" {
  # finops: ~$180/mo (db.t3.medium, 100GB gp3, 1 AZ)
  # finops: scale-trigger: >70% CPU or >80% storage
  instance_class = "db.t3.medium"
  ...
}

Architecture Review Questions

1. What scales with user count? What scales with data volume?
2. Are there N+1 API calls that will cost $$ at scale?
3. Is egress minimized? (Cache aggressively, colocate services)
4. Are reserved instances/savings plans applicable?
5. What is the cost at 10x current load?

Monthly Estimate Template

## Cost Estimate: {Feature}

| Service | Config | Est. Monthly |
|---------|--------|-------------|
| RDS PostgreSQL | db.t3.medium, 100GB | $180 |
| ElastiCache Redis | cache.t3.micro | $25 |
| ECS Fargate | 2 tasks, 0.5 vCPU, 1GB | $30 |
| ALB | 1 ALB, ~1M requests | $20 |
| **Total** | | **~$255/mo** |

Scales linearly with: [traffic volume / data volume]

SKILL: gh-issues

Purpose

Create, read, update, and link GitHub Issues as first-class story artifacts. Agents use this skill to manage issue lifecycle — from PO story creation through QA closure — without human intervention.

Inputs

Outputs

Create an Issue

# Capture issue number and URL
RESULT=$(gh issue create \
  --title "{title}" \
  --body-file "{body_file}" \
  --label "{labels}" \
  --milestone "{milestone}" \
  --json number,url,id)

ISSUE_NUMBER=$(echo "$RESULT" | python3 -c "import sys,json; d=json.load(sys.stdin); print(d['number'])")
ISSUE_URL=$(echo "$RESULT"    | python3 -c "import sys,json; d=json.load(sys.stdin); print(d['url'])")
ISSUE_NODE=$(echo "$RESULT"   | python3 -c "import sys,json; d=json.load(sys.stdin); print(d['id'])")

View an Issue

gh issue view {issue_number} --json number,title,state,labels,body

Edit Labels and Assignee

# Add label, remove old phase label
gh issue edit {issue_number} \
  --add-label "phase:architect" \
  --remove-label "phase:discover"

# Assign to current actor
gh issue edit {issue_number} --add-assignee "@me"

Add a Comment

gh issue comment {issue_number} \
  --body "{message}"

Comment conventions by role:

Close an Issue

# Close with final validation summary
gh issue close {issue_number} \
  --comment "All acceptance criteria passing. Validation: {summary}"

List Issues

# All open issues for current phase
gh issue list --label "phase:implement" --state open --json number,title,labels

# Blocked issues
gh issue list --label "blocked" --state open

Link Issues (parent / blocks)

GitHub Issues has no native parent field — use body references and labels:

# In the child issue body, add:
# "Closes #{parent_number}" → auto-closes parent when child closes
# "Part of #{epic_issue_number}"

# For blocking relationships, comment on the blocked issue:
gh issue comment {blocked_number} \
  --body "Blocked by #{blocker_number} — {reason}"
gh issue edit {blocked_number} --add-label "blocked"

Failure Modes

Logging

Always log after every gh issue mutation:

[gh-issues] CREATE  #42  "User can reset password"  labels=[type:feature,priority:high]
[gh-issues] COMMENT #42  phase:implement start
[gh-issues] CLOSE   #42  all criteria passing

Format: [gh-issues] {ACTION} #{number} {description}

SKILL: gh-labels-milestones

Purpose

Bootstrap and sync GitHub labels and milestones idempotently. Labels and milestones are created if absent; existing ones are updated if color or description differs. Never delete — only add or update.

Label Bootstrap

Use this at project start (maple labels) and in CI to guarantee label state.

# Idempotent label create-or-update
upsert_label() {
  local name="$1" color="$2" description="$3"
  if gh label list --json name --jq '.[].name' | grep -qx "$name"; then
    gh label edit "$name" --color "$color" --description "$description"
  else
    gh label create "$name" --color "$color" --description "$description"
  fi
}

Label Groups

Phase Labels (pipeline position)

upsert_label "phase:discover"   "0075ca" "Phase 1: Discovery"
upsert_label "phase:architect"  "0075ca" "Phase 2: Architecture"
upsert_label "phase:plan"       "0075ca" "Phase 3: Planning"
upsert_label "phase:infra"      "0075ca" "Phase 4: Infrastructure"
upsert_label "phase:implement"  "0075ca" "Phase 5: Implementation"
upsert_label "phase:validate"   "0075ca" "Phase 6: Validation"
upsert_label "phase:document"   "0075ca" "Phase 7: Documentation"
upsert_label "phase:done"       "0075ca" "Phase 8: Complete"

Type Labels (work classification)

upsert_label "type:feature"     "0052cc" "New capability"
upsert_label "type:bug"         "d73a4a" "Defect"
upsert_label "type:spike"       "e4e669" "Research / time-boxed exploration"
upsert_label "type:chore"       "ededed" "Non-functional maintenance"
upsert_label "type:refactor"    "ededed" "Code restructuring, no behavior change"
upsert_label "type:docs"        "0075ca" "Documentation only"

Priority Labels (MoSCoW)

upsert_label "priority:critical" "b60205" "Must ship — blocks launch"
upsert_label "priority:high"     "e11d48" "Must have"
upsert_label "priority:medium"   "f97316" "Should have"
upsert_label "priority:low"      "84cc16" "Could have"
upsert_label "priority:wontfix"  "ffffff" "Won't have this cycle"

Spec / Story Kit Labels

upsert_label "spec:problem"     "7057ff" "Problem statement written"
upsert_label "spec:approved"    "7057ff" "Spec approved by PO"
upsert_label "spec:in-review"   "7057ff" "Spec under review"

Design Labels

upsert_label "design:pending"      "fbca04" "Awaiting design"
upsert_label "design:in-progress"  "fbca04" "Design work active"
upsert_label "design:approved"     "fbca04" "Design approved"
upsert_label "design:a11y-passed"  "fbca04" "Accessibility review passed"

ADR Labels

upsert_label "adr:required"    "5319e7" "ADR must be written before implementation"
upsert_label "adr:in-progress" "5319e7" "ADR being authored"
upsert_label "adr:complete"    "5319e7" "ADR accepted"
upsert_label "adr:rejected"    "5319e7" "ADR rejected — see comments"

UI / Accessibility Labels

upsert_label "ui:required"     "fef2c0" "Has UI surface — design review required"
upsert_label "ui:in-progress"  "fef2c0" "UI implementation active"
upsert_label "ui:complete"     "fef2c0" "UI complete and reviewed"

Status Labels

upsert_label "in-progress" "0052cc" "Work started"
upsert_label "blocked"     "b60205" "Blocked — needs human"
upsert_label "validated"   "0e8a16" "All tests pass"
upsert_label "tdd:red"     "d73a4a" "Failing test written"
upsert_label "tdd:green"   "0e8a16" "Tests passing"

Milestone Bootstrap

# Idempotent milestone create
upsert_milestone() {
  local title="$1" due="$2" description="$3"
  EXISTING=$(gh api "repos/{owner}/{repo}/milestones" \
    --jq ".[] | select(.title == \"$title\") | .number" 2>/dev/null)
  if [ -n "$EXISTING" ]; then
    gh api "repos/{owner}/{repo}/milestones/$EXISTING" \
      -X PATCH \
      -f title="$title" \
      -f due_on="${due}T00:00:00Z" \
      -f description="$description"
  else
    gh api "repos/{owner}/{repo}/milestones" \
      -X POST \
      -f title="$title" \
      -f due_on="${due}T00:00:00Z" \
      -f description="$description"
  fi
}

# Example usage
upsert_milestone "v1.0" "2025-12-31" "Initial release"

Assign Labels to an Issue

# Add labels (idempotent — gh ignores if already present)
gh issue edit {issue_number} \
  --add-label "type:feature,priority:high,phase:discover"

# Remove a specific label
gh issue edit {issue_number} --remove-label "phase:discover"

Failure Modes

Logging

[gh-labels] UPSERT  label="type:feature"    color=0052cc
[gh-labels] SKIP    label="priority:high"   (unchanged)
[gh-milestones] CREATE  "v1.0"  due=2025-12-31
[gh-milestones] SKIP    "v1.0"  already exists

SKILL: gh-projects

Purpose

Manage GitHub Projects v2 board operations: add issues as cards, update field values (status, type, ADR required), and query board state. Uses gh project CLI where available; falls back to gh api graphql for operations the CLI does not expose.

Inputs

Read project config

PROJECT_NUMBER=$(python3 -c "
import sys
for line in open('project.config.yaml'):
    if 'project_number:' in line:
        print(line.split(':')[1].strip())
        break
")

PROJECT_NODE=$(python3 -c "
import sys
for line in open('project.config.yaml'):
    if 'project_node_id:' in line:
        print(line.split(':', 1)[1].strip())
        break
")

Add an Issue to the Project Board

# CLI (preferred)
gh project item-add "$PROJECT_NUMBER" \
  --owner "{owner}" \
  --url "https://github.com/{owner}/{repo}/issues/{issue_number}"

# GraphQL fallback (when CLI unavailable or for automation)
gh api graphql -f query='
  mutation($project: ID!, $content: ID!) {
    addProjectV2ItemById(input: {projectId: $project, contentId: $content}) {
      item { id }
    }
  }' \
  -f project="$PROJECT_NODE" \
  -f content="{issue_node_id}" \
  --jq '.data.addProjectV2ItemById.item.id'

Save the returned item_id — required for field updates.

Get Field and Option IDs

Field updates require the field's node ID and the option's node ID (for single-select fields).

FIELDS=$(gh api graphql -f query='
  query($project: ID!) {
    node(id: $project) {
      ... on ProjectV2 {
        fields(first: 20) {
          nodes {
            ... on ProjectV2Field { id name }
            ... on ProjectV2SingleSelectField {
              id name
              options { id name }
            }
          }
        }
      }
    }
  }' \
  -f project="$PROJECT_NODE")

# Extract field ID by name
FIELD_ID=$(echo "$FIELDS" | python3 -c "
import sys, json
d = json.load(sys.stdin)
for f in d['data']['node']['fields']['nodes']:
    if f.get('name') == '{field_name}':
        print(f['id'])
        break
")

# Extract option ID by value (single-select fields)
OPTION_ID=$(echo "$FIELDS" | python3 -c "
import sys, json
d = json.load(sys.stdin)
for f in d['data']['node']['fields']['nodes']:
    if f.get('name') == '{field_name}':
        for opt in f.get('options', []):
            if opt['name'] == '{field_value}':
                print(opt['id'])
                break
")

Update a Single-Select Field (Status, Type, ADR Required)

gh api graphql -f query='
  mutation($project: ID!, $item: ID!, $field: ID!, $option: String!) {
    updateProjectV2ItemFieldValue(input: {
      projectId: $project
      itemId: $item
      fieldId: $field
      value: { singleSelectOptionId: $option }
    }) {
      projectV2Item { id }
    }
  }' \
  -f project="$PROJECT_NODE" \
  -f item="{item_id}" \
  -f field="$FIELD_ID" \
  -f option="$OPTION_ID"

Update a Text Field (Epic, Specialist)

gh api graphql -f query='
  mutation($project: ID!, $item: ID!, $field: ID!, $value: String!) {
    updateProjectV2ItemFieldValue(input: {
      projectId: $project
      itemId: $item
      fieldId: $field
      value: { text: $value }
    }) {
      projectV2Item { id }
    }
  }' \
  -f project="$PROJECT_NODE" \
  -f item="{item_id}" \
  -f field="$FIELD_ID" \
  -f value="{text_value}"

Standard Field Updates by Pipeline Phase

Query Board State

# List all items with status
gh project item-list "$PROJECT_NUMBER" \
  --owner "{owner}" \
  --format json \
  --jq '.items[] | {id, title: .content.title, status: .fieldValues[] | select(.field.name=="Status") | .name}'

Failure Modes

Logging

[gh-projects] ADD    #42  → project #{project_number}  item_id={id}
[gh-projects] UPDATE #42  field=Status  value="In progress"
[gh-projects] SKIP   #42  already on board

SKILL: gherkin-authoring

Purpose

Produce valid, consistently named Gherkin story files. Handles ID allocation, timestamp generation, filename construction, tag formatting, and scenario validation. Used by the product-owner agent whenever a new story is written or updated.

Story File Naming Convention

<epic-slug>-<story-slug>-<timestamp>-<NNNN>.md

Full example: user-auth-reset-password-20250416143000-0003.md

Allocate the Next Story ID

# Count existing stories for an epic to get next sequential ID
EPIC="user-auth"
NEXT_ID=$(ls docs/stories/${EPIC}-* 2>/dev/null \
  | grep -oE '\-[0-9]{4}\.md$' \
  | grep -oE '[0-9]{4}' \
  | sort -n | tail -1 \
  | python3 -c "import sys; n=sys.stdin.read().strip(); print(f'{int(n)+1:04d}' if n else '0001')")
[ -z "$NEXT_ID" ] && NEXT_ID="0001"
echo "$NEXT_ID"

Generate Filename

EPIC="user-auth"
STORY="reset-password"
TS=$(date -u +"%Y%m%d%H%M%S")
ID="$NEXT_ID"   # from allocation step above
FILENAME="${EPIC}-${STORY}-${TS}-${ID}.md"
echo "$FILENAME"   # user-auth-reset-password-20250416143000-0001.md

Story File Template

Every story file must contain:

---
id: "{EPIC}-{NNNN}"
title: "{Human-readable story title}"
epic: "{epic-slug}"
priority: "high|medium|low|critical"
ui: false
adr_required: false
milestone: "{milestone name}"
labels:
  - "type:feature"
  - "priority:high"
  - "phase:discover"
issue_number: null
issue_url: null
---

## Story

**As a** {actor},
**I want** {capability},
**so that** {business outcome}.

## Acceptance Criteria

```gherkin
@story:{EPIC}-{NNNN} @epic:{epic-slug} @priority:{level}
Feature: {Feature title}

  Scenario: {scenario title}
    Given {precondition}
    When {action}
    Then {expected outcome}

Definition of Done

• All Gherkin scenarios have passing step implementations
• Unit tests written and passing
• Integration tests written and passing (if applicable)
• Code reviewed and approved
• No regressions in related features
• Documentation updated (if applicable)

ADR Links

## Gherkin Validation Rules

Before writing a scenario, verify:

1. **Single responsibility**: each `Scenario` tests exactly one behavior.
2. **Given-When-Then order**: never skip or reorder.
3. **No implementation detail in steps**: steps describe intent, not code.
4. **Declarative steps**: `Given the user is logged in` ✓ — `Given I call POST /auth/login` ✗
5. **Tags present**: `@story:`, `@epic:`, `@priority:` required on every Feature block.
6. **No `And` as first step**: `And` is only valid after a `Given`, `When`, or `Then`.

## Background Block (shared preconditions)

```gherkin
Feature: Password Reset

  Background:
    Given the user has a verified account
    And the account is not locked

  Scenario: Successful reset request
    When the user submits their email address
    Then a reset link is sent to that address

Use Background when 2+ scenarios share the same preconditions.

Scenario Outline (data-driven)

  Scenario Outline: Reject invalid email formats
    When the user submits "<email>"
    Then they see a validation error "<message>"

    Examples:
      | email        | message                  |
      | notanemail   | Invalid email format     |
      | @nodomain    | Invalid email format     |
      | a@b          | Domain must have TLD     |

Tags Reference

Failure Modes

Logging

[gherkin] ALLOCATE  epic=user-auth  next_id=0003
[gherkin] CREATE    docs/stories/user-auth-reset-password-20250416143000-0003.md
[gherkin] VALIDATE  scenarios=3  tags=ok  structure=ok

SKILL: GitHub CLI

Repo Context (always run first)

# Who am I, what repo am I in
gh auth status
gh repo view --json name,owner,defaultBranchRef,url,isPrivate

# Open issues + PRs at a glance
gh issue list --state open --limit 20 --json number,title,labels,assignees
gh pr list --state open --json number,title,headRefName,statusCheckRollup

Issues as Tasks

Create

# Feature story
gh issue create \
  --title "feat: {title}" \
  --body-file docs/stories/{slug}/Story.md \
  --label "type:feature,priority:high,phase:discover" \
  --milestone "v1.0" \
  --assignee "@me"

# Bug
gh issue create \
  --title "fix: {title}" \
  --body "## Steps to reproduce\n{steps}\n\n## Expected\n{expected}\n\n## Actual\n{actual}" \
  --label "type:bug,priority:high"

# Task (sub-work, no story file)
gh issue create \
  --title "task: {title}" \
  --body "{description}" \
  --label "type:task" \
  --assignee "@me"

Read

gh issue view {number}
gh issue view {number} --json number,title,state,body,labels,assignees,comments,milestone

# Search
gh issue list --search "label:blocked" --state open
gh issue list --search "assignee:@me is:open"
gh issue list --search "phase:implement" --label "tdd:red"
gh issue list --state open --label "type:feature" --milestone "v1.0"

Update

# Phase transition
gh issue edit {number} \
  --add-label "phase:architect" \
  --remove-label "phase:discover"

# Assign / unassign
gh issue edit {number} --add-assignee "@me"
gh issue edit {number} --remove-assignee "{login}"

# Change milestone
gh issue edit {number} --milestone "v2.0"

# Block / unblock
gh issue edit {number} --add-label "blocked"
gh issue edit {number} --remove-label "blocked"

Comment

gh issue comment {number} --body "{message}"

# Phase lifecycle comments (standard format)
gh issue comment {number} --body "Phase {N} {NAME}: starting. Target artifacts: {paths}"
gh issue comment {number} --body "Phase {N} {NAME}: complete. Artifacts: {paths}"
gh issue comment {number} --body "RED: Failing test at {path} — {message}"
gh issue comment {number} --body "GREEN: {count} tests passing."
gh issue comment {number} --body "BLOCKED: {agent} failed 3x on {task}. Human required."

Close

gh issue close {number} --comment "Acceptance criteria passing. Validation: {summary}"
gh issue close {number} --reason "not planned"

Pull Requests

# Create PR (always draft first)
gh pr create \
  --title "feat: {description}" \
  --body "## Summary\n{summary}\n\nCloses #{issue_number}" \
  --base main \
  --draft

# Mark ready when all gates pass
gh pr ready {number}

# View PR + CI status
gh pr view {number} --json number,title,state,reviews,statusCheckRollup,files

# Request review
gh pr edit {number} --add-reviewer "{login}"

# Check CI on PR
gh pr checks {number}

# Merge (squash — preferred)
gh pr merge {number} --squash --subject "feat: {description} (#{issue_number})" --delete-branch

# Review
gh pr review {number} --approve --body "LGTM"
gh pr review {number} --request-changes --body "{feedback}"

Branches

# List branches
gh api repos/{owner}/{repo}/branches --jq '.[].name'

# Create via API (when not in git context)
gh api repos/{owner}/{repo}/git/refs \
  -f ref="refs/heads/feat/{slug}" \
  -f sha="$(gh api repos/{owner}/{repo}/git/ref/heads/main --jq '.object.sha')"

# Delete remote branch
gh api -X DELETE repos/{owner}/{repo}/git/refs/heads/feat/{slug}

# Branch protection status
gh api repos/{owner}/{repo}/branches/main/protection

Actions / CI

# List recent runs
gh run list --limit 10
gh run list --workflow ci.yml --branch main --limit 5

# Watch a run live
gh run watch {run-id}

# View failed run details
gh run view {run-id} --log-failed

# Trigger workflow manually
gh workflow run {workflow-file} --ref main

# Re-run failed jobs only
gh run rerun {run-id} --failed

# Download artifact
gh run download {run-id} --name {artifact-name} --dir ./artifacts

Repo Inspection

# Full repo metadata
gh repo view --json name,owner,description,topics,visibility,defaultBranchRef,\
licenseInfo,stargazerCount,forkCount,createdAt,updatedAt

# Collaborators
gh api repos/{owner}/{repo}/collaborators --jq '.[].login'

# Repo settings
gh api repos/{owner}/{repo} --jq '{private:.private,hasIssues:.has_issues,hasWiki:.has_wiki}'

# Topics
gh repo edit --add-topic "{topic}"

# Clone URL
gh repo view --json sshUrl,url

# Releases
gh release list --limit 5
gh release view {tag}

Labels & Milestones

# Bootstrap MAPLE labels (idempotent)
bash scripts/bootstrap-labels.sh

# List labels
gh label list

# Create label
gh label create "type:task" --color "0075ca" --description "Work item"

# Create milestone
gh api repos/{owner}/{repo}/milestones \
  -f title="v1.0" \
  -f description="First release" \
  -f due_on="2026-06-01T00:00:00Z"

# List milestones
gh api repos/{owner}/{repo}/milestones --jq '.[] | {number:.number,title:.title,open:.open_issues}'

Search

# Search code in repo
gh search code "{query}" --repo {owner}/{repo} --json path,url

# Search issues across GitHub
gh search issues "{query}" --repo {owner}/{repo} --json number,title,state

# Search PRs
gh search prs "{query}" --repo {owner}/{repo} --state open

Issue Lifecycle (MAPLE Standard)

Failure Modes

humanizer skill

Polish text by removing detectable AI-generated writing patterns. Ideal for finalizing documentation, commit messages, comments, and any prose before merging.

When to use

• After @docs generates feature documentation
• Before committing code (check commit messages and comments)
• Polishing README updates, CHANGELOG entries, or runbooks
• Making AI-assisted prose sound more natural
• Manual voice calibration for brand consistency

How to invoke

/humanizer

[paste your text here]

Or ask directly in chat:

Please humanize this text: [your text]

Voice calibration (optional)

Provide a sample of your own writing for the skill to match your style:

/humanizer

Here's a sample of my writing for voice matching:
[paste 2-3 paragraphs of your own writing]

Now humanize this text:
[paste AI text to humanize]

What it detects

The skill checks for 29 AI-writing patterns, including:

• Significance inflation — "marking a pivotal moment in the evolution of..." → "was established in 1989"
• Notability name-dropping — Lists of citations → specific examples with context
• Superficial -ing phrases — "symbolizing, reflecting, showcasing" → active explanations
• Promotional language — Corporate jargon → straightforward description
• Overuse of 'indeed' — Filler words → tighter prose
• Transition abuse — Excessive "Furthermore, In conclusion..." → natural flow
• Hedging redundancy — "arguably, in some sense, it could be argued..." → clarity
• Rare word stacking — Thesaurus abuse → common vocabulary
• False expert mode — Generic expertise → grounded examples
• Generalist fluff — "many fields, various domains..." → specific scope

Integration with MAPLE

• Auto-call after Phase 7 (DOCUMENT) if humanize: true in feature story frontmatter
• Manual: invoke at any phase before merge
• Works across all harnesses (Claude Code, OpenCode, Cursor, Copilot CLI)

Output

Returns a humanized version of your text with:

1. First pass: Remove identified AI patterns
2. Final audit: "Obviously AI generated?" check
3. Second rewrite: Catch lingering AI-isms

Further reading

• Wikipedia: Signs of AI writing
• Humanizer repo

SKILL: Jupyter Notebook Patterns

Notebook Structure

Cells should follow this order:

1. Setup — imports, configuration, constants
2. Data Loading — load raw data with validation
3. EDA — exploratory data analysis, distributions, correlations
4. Preprocessing — cleaning, feature engineering
5. Modeling — model training and evaluation
6. Visualization — charts and figures
7. Conclusions — findings summary, next steps

Parameterized Execution with Papermill

# In notebook cell tagged with "parameters":
# Click: View -> Cell Toolbar -> Tags -> add "parameters" tag

dataset = "data/train.csv"  # papermill will override this
output_dir = "outputs"
n_estimators = 100
random_state = 42

# Execute with papermill
papermill input.ipynb output.ipynb \
  -p dataset "data/test.csv" \
  -p n_estimators 200 \
  -p random_state 0

Programmatic Notebook Creation

import nbformat as nbf

nb = nbf.v4.new_notebook()
nb.cells = [
    nbf.v4.new_markdown_cell("# Analysis: {Title}"),
    nbf.v4.new_code_cell("import pandas as pd\nimport numpy as np"),
    nbf.v4.new_code_cell("df = pd.read_csv('data.csv')\ndf.head()"),
]

with open('analysis.ipynb', 'w') as f:
    nbf.write(nb, f)

Export

# To HTML (with outputs)
jupyter nbconvert --to html --execute notebook.ipynb

# To PDF
jupyter nbconvert --to pdf --execute notebook.ipynb

# Execute in place
jupyter nbconvert --to notebook --execute --inplace notebook.ipynb

Git Hygiene

# Clear outputs before commit
jupyter nbconvert --to notebook --ClearOutputPreprocessor.enabled=True \
  --inplace notebook.ipynb

# Or use nbstripout (installs as git filter)
pip install nbstripout
nbstripout --install

Rules

• Restart kernel and run all cells before committing.
• Clear all outputs before git commit.
• Tag parameter cells for papermill.
• Each notebook should be self-contained and reproducible.
• Include random_state parameter for reproducibility.
• Use relative paths for data files.

karpathy-audit skill

Audit PRs and code changes against Andrej Karpathy's 4 principles for reducing LLM coding mistakes.

When to use

• Auto-invoked after Phase 5 (IMPLEMENT) before advancing to Phase 6 (VALIDATE)
• Manual invocation: /karpathy-audit or @karpathy-audit in chat
• At any phase when you want to assess code quality against the principles

The 4 Principles

1. Think Before Coding

Don't assume. Don't hide confusion. Surface tradeoffs.

• State assumptions explicitly. If uncertain, ask.
• Present multiple interpretations—don't pick silently.
• If a simpler approach exists, say so. Push back when warranted.
• Stop when confused. Name what's unclear and ask.

2. Simplicity First

Minimum code that solves the problem. Nothing speculative.

• No features beyond what was asked.
• No abstractions for single-use code.
• No "flexibility" or "configurability" that wasn't requested.
• No error handling for impossible scenarios.
• If 200 lines could be 50, rewrite it.

3. Surgical Changes

Touch only what you must. Clean up only your own mess.

• Don't "improve" adjacent code, comments, or formatting.
• Don't refactor things that aren't broken.
• Match existing style, even if you'd do it differently.
• Only remove imports/variables/functions that YOUR changes made unused.

4. Goal-Driven Execution

Define success criteria. Loop until verified.

• Transform tasks into verifiable goals: tests before code.
• State a brief plan with explicit success criteria.
• Loop independently until verified.

How to invoke

Auto-call (Phase 5 → Phase 6 gate): Orchestrator automatically calls this skill after IMPLEMENT phase to audit the diff.

Manual call:

/karpathy-audit

or

@karpathy-audit

Audit output

The skill produces a compliance report written to .claude/state/karpathy-report.json:

{
  "phase": "IMPLEMENT",
  "timestamp": "2026-05-18T21:25:00Z",
  "spec_file": "docs/stories/user-auth/Story.md",
  "audit": {
    "think_before_coding": {
      "score": 85,
      "violations": ["Assumed DB schema without asking"],
      "evidence": ["Line 42: const User = model('User')"]
    },
    "simplicity_first": {
      "score": 92,
      "violations": [],
      "evidence": ["Reduced 180→120 lines in refactor"]
    },
    "surgical_changes": {
      "score": 78,
      "violations": ["Modified logging in unrelated file"],
      "scope_creep_files": ["src/logging/index.ts"],
      "out_of_spec": true
    },
    "goal_driven": {
      "score": 100,
      "violations": [],
      "evidence": ["All tests passing. RED→GREEN→REFACTOR complete."]
    },
    "overall": 89,
    "gate_decision": "PASS_WITH_APPROVAL",
    "recommendation": "Score 89: Pass scope and simplicity checks. Recommend human approval before advancing to Phase 6."
  }
}

Scoring & Gate Decisions

Scope creep detection

Compares two sources:

1. Original spec — From docs/stories/{story}/Story.md (required scope)
2. PR diff — Files and line changes in the current PR

Violations flagged:

• Files modified outside the spec boundary
• Feature branches added beyond the story requirement
• Unrelated cleanup/refactoring

Phase 5 → Phase 6 Gate

Orchestrator behavior:

Phase 5 (IMPLEMENT) complete
  ↓
Auto-call: /karpathy-audit
  ↓
Analyze spec + PR diff + 4 principles
  ↓
Write `.claude/state/karpathy-report.json`
  ↓
Score ≥90?      → Auto-advance to Phase 6
Score 70-89?    → Pause. Display report. Require [a]pprove or [c]cancel
Score <70?      → HALT. Show violations. Require /karpathy-audit re-run after fixes

Dashboard integration

The TUI displays:

• Phase 5 detail view — Shows karpathy-report.json if present
• [P] overlay (Pipeline pane) — Per-principle scores + violations
• Red blocking indicator — If score <70, blocks manual phase advance
• Approval gate — If 70-89, shows "awaiting approval" state

Remediation workflow

If audit fails or scores <70:

1. Orchestrator shows violation details
2. Specialist agent re-assesses work against the principle
3. Fix or remove out-of-scope code
4. Manually re-run: /karpathy-audit
5. If all 4 principles ≥70 now, approve advancement

Example invocation

User: /feature "add password reset via email"
Orchestrator: [Phase 1-5 complete]
Orchestrator: Auditing against Karpathy principles...
karpathy-audit: Running audit...
[Analyze spec vs PR diff]
[Score each principle]
karpathy-audit: 📋 Report written to .claude/state/karpathy-report.json
karpathy-audit: 🟡 Score 82/100 — PASS_WITH_APPROVAL
karpathy-audit: ⚠️ Scope creep: modified src/logging (out of spec)

Dashboard: [Shows approval gate, awaiting [a] key]
User: a  [approve]
Dashboard: [Phase 6 VALIDATE begins]

Further reading

• Karpathy's observations on LLM coding mistakes
• MAPLE 8-Phase Pipeline

SKILL: Kubernetes Patterns

Kustomize Structure

infra/k8s/
├── base/
│   ├── deployment.yaml
│   ├── service.yaml
│   ├── configmap.yaml
│   └── kustomization.yaml
└── overlays/
    ├── dev/
    │   ├── kustomization.yaml
    │   └── patches/
    ├── staging/
    │   ├── kustomization.yaml
    │   └── patches/
    └── prod/
        ├── kustomization.yaml
        └── patches/

Deployment with Required Fields

apiVersion: apps/v1
kind: Deployment
metadata:
  name: {app-name}
  labels:
    app: {app-name}
spec:
  replicas: 2
  selector:
    matchLabels:
      app: {app-name}
  template:
    metadata:
      labels:
        app: {app-name}
    spec:
      securityContext:
        runAsNonRoot: true
        runAsUser: 1001
      containers:
        - name: {app-name}
          image: {image}:{tag}
          resources:
            requests:
              memory: "128Mi"
              cpu: "100m"
            limits:
              memory: "256Mi"
              cpu: "500m"
          readinessProbe:
            httpGet:
              path: /health
              port: 3000
            initialDelaySeconds: 5
            periodSeconds: 10
          livenessProbe:
            httpGet:
              path: /health
              port: 3000
            initialDelaySeconds: 15
            periodSeconds: 20
          startupProbe:
            httpGet:
              path: /health
              port: 3000
            failureThreshold: 30
            periodSeconds: 10

PodDisruptionBudget

apiVersion: policy/v1
kind: PodDisruptionBudget
metadata:
  name: {app-name}-pdb
spec:
  minAvailable: 1
  selector:
    matchLabels:
      app: {app-name}

HPA

apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: {app-name}-hpa
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: {app-name}
  minReplicas: 2
  maxReplicas: 10
  metrics:
    - type: Resource
      resource:
        name: cpu
        target:
          type: Utilization
          averageUtilization: 70

Validation Workflow

# Always validate before applying
kubectl apply --dry-run=client -f {manifest}
kustomize build overlays/dev | kubectl apply --dry-run=client -f -
helm template {release} {chart} | kubectl apply --dry-run=client -f -

SKILL: Mermaid Diagrams

Required Diagrams Per Feature

1. Component diagram (graph TB)
2. Sequence diagram (sequenceDiagram)
3. ER diagram (erDiagram)
4. Deployment diagram (graph TB with deployment focus)
5. State machine (stateDiagram-v2) — where applicable

Rules

• Maximum 30 nodes per diagram.
• All diagrams must be syntactically valid.
• Test diagrams in the Mermaid Live Editor before committing.
• Use descriptive node labels.

Component Diagram

graph TB
    subgraph "Frontend"
        UI["React App"]
    end
    subgraph "Backend"
        API["REST API"]
        DB[("PostgreSQL")]
        Cache[("Redis")]
    end
    UI -->|"HTTPS"| API
    API --> DB
    API --> Cache

Sequence Diagram

sequenceDiagram
    actor U as User
    participant F as Frontend
    participant A as API
    participant D as Database

    U->>F: Action
    F->>A: POST /api/resource
    A->>D: INSERT
    D-->>A: 201 Created
    A-->>F: {id, data}
    F-->>U: Success

ER Diagram

erDiagram
    USER {
        uuid id PK
        string email UK
        timestamp created_at
    }
    ORDER {
        uuid id PK
        uuid user_id FK
        decimal total
        timestamp created_at
    }
    USER ||--o{ ORDER : "places"

State Machine

stateDiagram-v2
    [*] --> Pending
    Pending --> Processing: payment received
    Processing --> Completed: fulfilled
    Processing --> Failed: error
    Failed --> Pending: retry
    Completed --> [*]

Deployment Diagram

graph TB
    subgraph "Vercel Edge"
        FE["Next.js App"]
        EF["Edge Functions"]
    end
    subgraph "AWS"
        LB["Load Balancer"]
        APP["App Servers"]
        RDS[("RDS PostgreSQL")]
        EC["ElastiCache Redis"]
    end
    FE --> EF
    EF --> LB
    LB --> APP
    APP --> RDS
    APP --> EC

SKILL: mockup

Purpose

Scaffold high-fidelity UI component mockups using the project's declared UI stack (Mantine, Tailwind/shadcn, or plain HTML). Mockups consume approved wireframes and design tokens. Output is runnable code — not a design file. Human approval required before the mockup is treated as the implementation target.

Inputs

Supported Stacks (web target)

Outputs

Target awareness

design.target (project.config.yaml, default web):

• web — generate the code mockup (.tsx/.html) for the configured ui_library, plus .mockup.md.
• tui — generate ONLY <id>.mockup.md: a fenced monospace terminal render at the target width covering default/selected/empty/error/loading states, followed by a "Styles" section mapping each region to lipgloss Foreground/Background/Border/Padding taken from docs/design/identity/terminal-theme.json. Skip the stack detector and the React templates below.

Pre-flight Checks

Before generating:

WIREFRAME="docs/design/wireframes/${STORY_ID}.wireframe.md"
TOKENS="docs/design/identity/tokens.json"

# 1. Wireframe must be approved
STATUS=$(python3 -c "
import re
m = re.search(r'^status:\s*(\w+)', open('$WIREFRAME').read(), re.MULTILINE)
print(m.group(1) if m else 'draft')
")
[ "$STATUS" = "approved" ] || { echo "BLOCKED: wireframe not approved"; exit 1; }

# 2. Tokens must exist
[ -f "$TOKENS" ] || { echo "BLOCKED: tokens.json missing — run visual-identity skill first"; exit 1; }

Mockup Template: react-mantine

// AUTO-GENERATED MOCKUP — docs/design/mockups/{story-id}.mockup.tsx
// Story: {story title}
// Wireframe: {wireframe file}
// Tokens: mantine.theme.ts
// Status: draft — awaiting approval

import { MantineProvider, Stack, TextInput, Button, Text, Alert } from '@mantine/core';
import { theme } from '../../docs/design/identity/mantine.theme';
import { IconAlertCircle } from '@tabler/icons-react';

interface Props {
  error?: string;
  onSubmit: (email: string) => void;
}

export function {ComponentName}({ error, onSubmit }: Props) {
  const [email, setEmail] = useState('');

  return (
    <MantineProvider theme={theme}>
      <Stack gap="md" maw={400} mx="auto" mt="xl">
        <Text fw={700} size="xl">{Screen Title}</Text>

        <TextInput
          label="Email"
          placeholder="you@example.com"
          value={email}
          onChange={(e) => setEmail(e.target.value)}
          error={error}
        />

        {error && (
          <Alert icon={<IconAlertCircle />} color="red" variant="light">
            {error}
          </Alert>
        )}

        <Button fullWidth onClick={() => onSubmit(email)}>
          Send Reset Link
        </Button>
      </Stack>
    </MantineProvider>
  );
}

Mockup Template: react-tailwind

// AUTO-GENERATED MOCKUP — docs/design/mockups/{story-id}.mockup.tsx
import { useState } from 'react';

interface Props {
  error?: string;
  onSubmit: (email: string) => void;
}

export function {ComponentName}({ error, onSubmit }: Props) {
  const [email, setEmail] = useState('');

  return (
    <div className="max-w-sm mx-auto mt-16 space-y-4">
      <h1 className="text-2xl font-bold text-foreground">{Screen Title}</h1>

      <div>
        <label className="block text-sm font-medium mb-1">Email</label>
        <input
          type="email"
          className={`w-full border rounded-md px-3 py-2 text-sm ${error ? 'border-error' : 'border-border'}`}
          placeholder="you@example.com"
          value={email}
          onChange={(e) => setEmail(e.target.value)}
        />
        {error && <p className="text-error text-sm mt-1">{error}</p>}
      </div>

      <button
        className="w-full bg-brand-primary text-white rounded-md py-2 font-medium hover:opacity-90"
        onClick={() => onSubmit(email)}
      >
        Send Reset Link
      </button>
    </div>
  );
}

Mockup Metadata File

Always write a .mockup.md alongside the code file:

---
story_id: "{story_id}"
wireframe: "docs/design/wireframes/{story_id}.wireframe.md"
stack: "{stack}"
status: draft        # draft | approved | rejected
approved_by: null
approved_at: null
---

## Mockup: {story title}

### States

- Default
- Error: {describe}
- Success: {describe}
- Loading: {describe if applicable}

### Token Usage

- Primary action: `color.brand.primary`
- Error text: `color.semantic.error`
- Border: `color.surface.border`

### Approval

- [ ] Matches approved wireframe
- [ ] Design tokens applied correctly
- [ ] All interaction states present
- [ ] Approved by product owner / UX lead

Failure Modes

Logging

[mockup] CREATE   docs/design/mockups/auth-reset-0001.mockup.tsx  stack=react-mantine
[mockup] CREATE   docs/design/mockups/auth-reset-0001.mockup.md   status=draft
[mockup] BLOCKED  auth-reset-0001  wireframe not approved
[mockup] SKIP     auth-reset-0001  mockup approved — locked

SKILL: pipeline-runner

What It Does

Dispatches any named workflow, skill, or agent from a single entry point. Resolution order:

1. Taffy workflow — look for .claude/taffy/<name>.yaml; if found, execute each stage in order
2. Skill (local) — look for .claude/skills/<name>/; if found, invoke the skill
3. Agent — look for .claude/agents/<name>.md; if found, delegate to @<name>
4. Skill (registry) — if not found locally, try to install from skills.sh, then retry step 2

Pipeline state is written to .claude/state/maple.json at every transition.

Usage

/pipeline-runner <name>

Examples:

/pipeline-runner new-ui-feature
/pipeline-runner api-endpoint
/pipeline-runner implement-stories
/pipeline-runner tdd-workflow
/pipeline-runner orchestrator

List available taffy workflows:

ls .claude/taffy/*.yaml | grep -v schema

List available skills:

ls .claude/skills/

Dispatch Protocol

Step 1: Resolve the target

# Check taffy first
[ -f ".claude/taffy/<name>.yaml" ] && dispatch=taffy
# Then local skill
[ -d ".claude/skills/<name>" ] && dispatch=skill
# Then agent
[ -f ".claude/agents/<name>.md" ] && dispatch=agent
# Fallback: fetch from skills.sh registry, then retry
if [ -z "$dispatch" ] && command -v npx &>/dev/null; then
  echo "pipeline-runner: '<name>' not found locally — checking skills.sh…"
  npx --yes skills add kinncj/maple@<name> -a claude-code -y 2>/dev/null \
    || npx --yes skills add <name> -a claude-code -y 2>/dev/null \
    || true
  [ -d ".claude/skills/<name>" ] && dispatch=skill
fi

If nothing matches after the registry fallback, report: pipeline-runner: no taffy workflow, skill, or agent named '<name>' (also checked skills.sh registry)

Step 2: Initialise state

Write to .claude/state/maple.json (merge — do not overwrite unowned fields):

{
  "taffy": "<name>",
  "stage": "<first-stage or skill-name>",
  "status": "RUNNING",
  "awaiting_approval": null,
  "started_at": "<iso8601>",
  "updated_at": "<iso8601>"
}

Step 2b: Runtime policy enforcement (mandatory)

Before any stage execution, read and enforce:

• Harness-specific root markdown:
  • Claude harness → CLAUDE.md
  • OpenCode harness → OPENCODE.md
  • Cursor harness → CURSOR.md
  • Copilot harness → COPILOT.md
• AGENTS.md
• .github/copilot-instructions.md
• .github/instructions/stories.instructions.md (when touching story files)

When the launch prompt contains a <maple-gherkin-handoff> block:

1. Treat it as hard scope: implement only listed story paths / IDs.
2. Do not run Spec-Kit or regenerate stories.
3. Preserve the repository's current Cucumber stack:
   • If generated stories include cucumber/*_steps.py, use Python behave-style steps.
   • Do not introduce TypeScript @cucumber/cucumber unless the repository already uses it as the active standard.
4. Keep BusinessRepo structure and phase gates exactly as defined by instruction files.
5. Treat test layout as mandatory:
   • Gherkin feature files must live under /tests/features/.
   • Step definitions must use the repository's active Cucumber stack and live under /tests.
   • Do not place acceptance tests under /app or story directories.
6. Enforce module boundaries independent of language:
   • Runtime/source files must not import from docs/, .github/, or .claude/.
   • Copying/adapting approved artifact content into app/test source is allowed.
   • Design/spec artifacts are references, not runtime code dependencies.

Step 3a: Taffy workflow execution

Load .claude/taffy/<name>.yaml, parse stages:, resolve depends_on order.

If the workflow defines an orchestrator-kickoff stage, execute it first before all other stages. This stage must publish the initial plan and heartbeat cadence.

For each stage:

when: guard:

• when: ui:true — skip if story has ui: false, unless .claude/state/maple.json has force_ui: true with launch_source: maple-x (MAPLE [x] quick-launch override).
• when: ui:false — skip if story has ui: true
• when: always — always run
• UI-related scope includes web, mobile, desktop, and TUI stories. Any such run must include design-review human-approval stages before implementation phases.

depends_on: all listed stages must be DONE before this one starts.

Dispatch:

• agent: <name> → delegate to @<name> with current story context
• skill: <name> → invoke the skill
• pipeline: standard → run the full 8-phase orchestrator pipeline

After each stage: update maple.json with current stage + RUNNING.

Progress heartbeats (mandatory):

• Send an immediate kickoff status before the first long-running tool/agent call.
• While a taffy run is active, send a concise progress update at least every 60-120 seconds.
• On each heartbeat, refresh maple.json updated_at and current stage.
• Every heartbeat must include concrete progress evidence:
  • changed files/artifacts since last update (explicit paths), or
  • a specific blocker that prevented changes.
• Use this status format:
  • Progress: <stage / phase>
  • Done since last update: <brief>
  • Current action: <brief>
  • Blockers: <none or blocker>
  • Next update: <ETA>
• Do not send heartbeat-only timestamp churn with no artifact/blocker details.
• If a stage requires writing artifacts and write access/tools are unavailable, set maple.json to FAILED with an explicit error and stop.
• If blocked/waiting, report what is pending and continue heartbeats until unblocked.

Completion artifact gate (mandatory):

• Before marking DONE, verify the run produced concrete story-linked artifacts under the BusinessRepo layout.
• Required for implementation runs:
  • application changes in /app (or existing domain folders),
  • tests in /tests (unit/integration/e2e as applicable),
  • Gherkin assets in /tests/features plus matching step implementations.
• Boundary check:
  • fail the run if generated runtime code imports paths under docs/, .github/, or .claude/.
• If required test/gherkin artifacts are missing, set maple.json to FAILED and report missing paths explicitly.

Step 3b: Skill invocation

Invoke the skill directly. Update maple.json on start and completion.

Step 3c: Agent delegation

Delegate to @<name>. Update maple.json on start and completion.

Step 4: Human-approval gates (taffy only)

When a stage has gate: human-approval:

1. Complete stage work (produce artifact).
   • For design review stages (wireframe, visual-identity, design-tokens, ui-mockup-builder, design-refresh), artifact production is mandatory:
     • create at least one previewable artifact (.excalidraw, .html, .svg, .png, .jpg, .jpeg, .webp, or .md) under docs/design (or approved artifact dirs), and
     • the required formats depend on design.target (project.config.yaml, default web): web = .md + .html + .excalidraw; tui = .md + .excalidraw (no .html). A run that produces fewer than the required formats is incomplete, and
     • update .claude/state/design-artifacts.json with current stage artifact paths so the review portal can update live.
   • Path + completeness gate for wireframe stage (mandatory before PAUSING):

     # Verify wireframes are in the canonical location and the required formats exist.
     # Required formats depend on design.target (web: md+html+excalidraw; tui: md+excalidraw).
     TARGET=$(sed -n 's/^[[:space:]]*target:[[:space:]]*\([a-z]*\).*/\1/p' project.config.yaml 2>/dev/null | head -1)
     [ -z "$TARGET" ] && TARGET=web
     CANONICAL=$(find docs/design/wireframes -name "*.wireframe.*" 2>/dev/null | wc -l | tr -d ' ')
     MISPLACED=$(find docs -name "*.wireframe.*" -not -path "*/docs/design/wireframes/*" 2>/dev/null)
     MISSING_HTML=""
     if [ "$TARGET" != "tui" ]; then
       MISSING_HTML=$(find docs/design/wireframes -name "*.wireframe.md" 2>/dev/null | while read md; do
         base="${md%.wireframe.md}"
         [ ! -f "${base}.wireframe.html" ] && echo "${base}.wireframe.html"
       done)
     fi
     MISSING_EXCALIDRAW=$(find docs/design/wireframes -name "*.wireframe.md" 2>/dev/null | while read md; do
       base="${md%.wireframe.md}"
       [ ! -f "${base}.wireframe.excalidraw" ] && echo "${base}.wireframe.excalidraw"
     done)
     if [ "$CANONICAL" -eq 0 ]; then
       if [ -n "$MISPLACED" ]; then
         echo "PIPELINE GATE FAILED: wireframes found at wrong path(s): $MISPLACED"
         echo "Canonical path is docs/design/wireframes/ — move files there before this stage can complete."
       else
         echo "PIPELINE GATE FAILED: no wireframe artifacts in docs/design/wireframes/"
       fi
       # set maple.json FAILED and stop
     fi
     if [ -n "$MISSING_HTML" ]; then
       echo "PIPELINE GATE FAILED: missing .wireframe.html for: $MISSING_HTML — generate it now."
       # set maple.json FAILED and stop
     fi
     if [ -n "$MISSING_EXCALIDRAW" ]; then
       echo "PIPELINE GATE FAILED: missing .wireframe.excalidraw for: $MISSING_EXCALIDRAW — generate it now."
       # set maple.json FAILED and stop
     fi
     

     If the gate fails, produce the missing files before re-running the gate check.
   • If no reviewable artifact exists for a design gate, set maple.json to FAILED and stop.
2. Write PAUSED state:

{ "stage": "<name>", "status": "PAUSED", "awaiting_approval": "<name>", "updated_at": "<iso8601>" }

3. Write stage name to .claude/state/approval-pending.txt.
4. Output:

TAFFY PAUSED — awaiting human approval
Stage:    <stage-name>
Artifact: <artifact path or description>

Approve via the maple TUI ([P] pipeline → [a] approve) or reply "approved" / "continue".
I will not advance to the next stage until approval is confirmed.

5. Poll: timeout 540 bash -c 'until [ ! -f .claude/state/approval-pending.txt ]; do sleep 2; done'
   • On timeout (exit 124), re-run the same poll. The Bash tool caps at 10 min per call; re-polling across calls lets approval delays exceed that bound.
   • Also accept an explicit "approved" / "continue" reply in chat.
   • When the user approves via the maple TUI ([P] → [a]), the TUI deletes the pending file and sends a "continue" keystroke to the agent's pane via the active multiplexer (outer tmux/zellij, or a detached tmux new-session wrapper). Either signal is sufficient to resume.
6. On resume: update to RUNNING, advance to next stage.
7. While paused, monitor .claude/state/design-feedback.json:
   • status: requested_changes or status: rejected means apply the requested updates before advancing.
   • Treat attachments as required review inputs (uploaded files such as .excalidraw, images, HTML, text), typically under docs/design/review-input/.
   • Summarize how each feedback item and attachment was addressed before continuing.

Step 5: Completion

{ "taffy": "<name>", "stage": "DONE", "status": "DONE", "awaiting_approval": null, "updated_at": "<iso8601>" }

Output:

TAFFY COMPLETE — <name>
Stages run: N
Duration:   <elapsed>

Failure Handling

After 3 consecutive failures on any stage:

{ "stage": "<name>", "status": "FAILED", "error": "<summary>", "updated_at": "<iso8601>" }

Stop. Report failed stage and error to human. Do not proceed.

Session Context

On startup, read .claude/state/sessions.json if it exists:

{ "claude": "<uuid>", "opencode": "<id>", "copilot": "<id>" }

Use the matching session ID when resuming work within an existing agent session.

State File Reference

All state in .claude/state/. TUI and skill share these files.

.claude/state/maple.json

Merge-not-overwrite: read existing file, update only owned fields, re-write.

.claude/state/approval-pending.txt

Skill writes stage name. TUI deletes when user presses [a].

.claude/state/sessions.json

TUI writes harness→session-ID map. Skill reads for session resume.

Skip Conditions

• spike/* and chore/* branches: skip Spec-Kit stages, run implementation stages.
• Stage when: ui:true on a ui: false story: skip silently, log [pipeline-runner] SKIP stage=<name> reason=ui:false unless quick-launch override is active (force_ui=true, launch_source=maple-x).

SKILL: Playwright CLI

When to Use

Use Playwright CLI (playwright-cli) for interactive browser exploration and snapshot-based interaction. Use npx playwright test for running actual test suites.

Installation

npm install -g @playwright/cli
npx playwright install  # installs browsers

Core CLI Commands

Browser Exploration

# Open browser to URL
playwright-cli open http://localhost:3000

# Take accessibility snapshot (YAML with element references)
playwright-cli snapshot
# Output: saves to disk as snapshot.yml — review before acting

# Interact by element reference (e.g., e21 from snapshot)
playwright-cli click e21
playwright-cli fill e35 "test@example.com"
playwright-cli press e35 Enter
playwright-cli screenshot  # saves to disk

Session Management

# Named sessions for auth state
playwright-cli --session=auth open http://localhost:3000/login
playwright-cli --session=auth fill e10 "admin@example.com"
playwright-cli --session=auth fill e11 "password"
playwright-cli --session=auth click e20  # submit button
playwright-cli session-list

Snapshot-to-Test Workflow

1. playwright-cli open http://localhost:3000
2. playwright-cli snapshot → review element refs in snapshot.yml
3. Interact: playwright-cli click e21, playwright-cli fill e35 "value"
4. Observe results
5. Convert to test file:

// tests/e2e/feature.spec.ts
import { test, expect } from '@playwright/test';

test('should {outcome} when {action}', async ({ page }) => {
  await page.goto('/');
  await page.getByRole('button', { name: 'Sign In' }).click();
  await page.getByLabel('Email').fill('test@example.com');
  await page.getByLabel('Password').fill('password123');
  await page.getByRole('button', { name: 'Login' }).click();
  await expect(page).toHaveURL('/dashboard');
  await expect(page.getByRole('heading', { name: 'Dashboard' })).toBeVisible();
});

Test Execution

# Run all E2E tests
npx playwright test tests/e2e/

# Run specific test file
npx playwright test tests/e2e/auth.spec.ts

# Visual debugger
npx playwright test --ui

# Headed mode (visible browser)
npx playwright test --headed

# Generate tests by recording
npx playwright codegen http://localhost:3000

# View HTML report
npx playwright show-report

API Testing (Playwright request fixture)

test('POST /api/users returns 201', async ({ request }) => {
  const response = await request.post('/api/users', {
    data: {
      email: 'test@example.com',
      name: 'Test User'
    }
  });
  expect(response.status()).toBe(201);
  const body = await response.json();
  expect(body).toHaveProperty('id');
});

Token Efficiency Note

Use playwright-cli snapshot (saves to disk) instead of screenshots in context. The compact YAML element refs (~1,350 tokens) vs accessibility tree injection (~5,700 tokens).

SKILL: PostgreSQL Patterns

Migration Naming

migrations/
  V001__create_users.sql          # Flyway
  0001_create_users.sql           # Generic
  20240115_create_users.sql       # Timestamp-based

Table Pattern with RLS

-- Create table
CREATE TABLE IF NOT EXISTS users (
  id          uuid DEFAULT gen_random_uuid() PRIMARY KEY,
  email       text UNIQUE NOT NULL,
  name        text NOT NULL,
  role        text NOT NULL DEFAULT 'user' CHECK (role IN ('user', 'admin')),
  created_at  timestamptz DEFAULT now() NOT NULL,
  updated_at  timestamptz DEFAULT now() NOT NULL
);

-- Indexes
CREATE INDEX CONCURRENTLY idx_users_email ON users(email);
CREATE INDEX CONCURRENTLY idx_users_role ON users(role) WHERE role != 'user';

-- Updated_at trigger
CREATE OR REPLACE FUNCTION update_updated_at()
RETURNS TRIGGER AS $$
BEGIN
  NEW.updated_at = now();
  RETURN NEW;
END;
$$ LANGUAGE plpgsql;

CREATE TRIGGER users_updated_at
  BEFORE UPDATE ON users
  FOR EACH ROW EXECUTE FUNCTION update_updated_at();

-- RLS
ALTER TABLE users ENABLE ROW LEVEL SECURITY;

CREATE POLICY users_select_own ON users
  FOR SELECT USING (id = current_user_id());

CREATE POLICY users_admin_all ON users
  FOR ALL USING (current_user_role() = 'admin');

Query Optimization

-- Always EXPLAIN ANALYZE in development
EXPLAIN (ANALYZE, BUFFERS, FORMAT TEXT)
SELECT u.*, COUNT(o.id) as order_count
FROM users u
LEFT JOIN orders o ON o.user_id = u.id
WHERE u.created_at > now() - interval '30 days'
GROUP BY u.id;

-- Partial index for common filter
CREATE INDEX idx_orders_pending
  ON orders(created_at)
  WHERE status = 'pending';

-- GIN index for full-text search
CREATE INDEX idx_products_search
  ON products USING gin(to_tsvector('english', name || ' ' || description));

Connection Pooling (PgBouncer)

# pgbouncer.ini
[databases]
app = host=127.0.0.1 port=5432 dbname=app

[pgbouncer]
pool_mode = transaction  # transaction pooling for most apps
max_client_conn = 100
default_pool_size = 20

Rules

• NEVER modify existing migration files.
• Always create new migration for schema changes.
• Index all foreign keys.
• Use CONCURRENTLY for index creation on large tables.
• EXPLAIN ANALYZE all queries > 100ms.
• Enable RLS on tables with user data.

SKILL: Redis Patterns

Key Design Convention

{app}:{domain}:{entity}:{id}
# Examples:
myapp:user:session:usr_123
myapp:product:cache:prod_456
myapp:rate:api:ip_1.2.3.4
myapp:queue:emails:pending

Cache-Aside Pattern

async function getUser(id: string): Promise<User> {
  const key = `myapp:user:data:${id}`;
  const ttl = 3600; // 1 hour

  // Try cache first
  const cached = await redis.get(key);
  if (cached) {
    return JSON.parse(cached) as User;
  }

  // Cache miss — fetch from DB
  const user = await db.users.findById(id);
  if (!user) throw new Error('User not found');

  // Store in cache with TTL
  await redis.setex(key, ttl, JSON.stringify(user));
  return user;
}

// Invalidate on update
async function updateUser(id: string, data: Partial<User>): Promise<User> {
  const user = await db.users.update(id, data);
  await redis.del(`myapp:user:data:${id}`);
  return user;
}

Rate Limiting with Sorted Set

async function rateLimit(ip: string, limit: number, windowSeconds: number): Promise<boolean> {
  const key = `myapp:rate:api:${ip}`;
  const now = Date.now();
  const windowStart = now - (windowSeconds * 1000);

  const pipeline = redis.pipeline();
  pipeline.zremrangebyscore(key, 0, windowStart);
  pipeline.zadd(key, now, `${now}`);
  pipeline.zcard(key);
  pipeline.expire(key, windowSeconds);

  const results = await pipeline.exec();
  const count = results?.[2]?.[1] as number;
  return count <= limit;
}

Session Store

// Using ioredis with connect-redis
import session from 'express-session';
import RedisStore from 'connect-redis';

app.use(session({
  store: new RedisStore({ client: redis }),
  secret: process.env.SESSION_SECRET!,
  resave: false,
  saveUninitialized: false,
  cookie: {
    secure: process.env.NODE_ENV === 'production',
    httpOnly: true,
    maxAge: 1000 * 60 * 60 * 24, // 24 hours
  }
}));

Rules

• ALWAYS set TTLs on cache keys — never store indefinitely.
• Use SCAN not KEYS in production (non-blocking).
• Use pipelining for multiple operations.
• Key convention: {app}:{domain}:{entity}:{id}.
• Monitor with: redis-cli info memory and redis-cli monitor (dev only).
• Set maxmemory-policy allkeys-lru for cache-only Redis instances.

SKILL: RFC / Architecture Decision Records

ADR Format

Every significant architectural decision gets an ADR. Store in: docs/specs/{feature}/adr.md

# ADR-{N}: {Short Title}

## Status
Proposed | Accepted | Deprecated | Superseded by ADR-{N}

## Context
What is the problem or situation that requires a decision?
What constraints exist?

## Goals
- {Specific, measurable goal}

## Non-goals
- {What this ADR does NOT address}

## Proposal
{Detailed technical proposal. Include code snippets if helpful.}

## Alternatives Considered

### Option A: {Name}
**Description:** {What it is}
**Pros:** {list}
**Cons:** {list}

### Option B: {Name}
**Description:** {What it is}
**Pros:** {list}
**Cons:** {list}

## Trade-offs and Risks
{Analysis of trade-offs. What could go wrong?}

## Impact

### Cost (FinOps)
{Estimated cloud cost impact. Monthly estimate if possible.}

### Operations (SRE)
{New runbook requirements. Alert thresholds. On-call implications.}

### Security
{Changes to attack surface. New threat vectors. Compliance implications.}

### Team
{Skill requirements. Training needed. Hiring implications.}

## Decision
{Final decision and rationale. Who made it and when.}

## Next Steps
- [ ] {Action item with owner}
- [ ] {Action item with owner}

When to Write an ADR

• Choosing between two or more non-trivial technical approaches.
• Adopting a new technology or framework.
• Changing a significant existing pattern.
• Making a trade-off with known long-term implications.

When NOT to Write an ADR

• Obvious choices with no real alternatives.
• Implementation details within an agreed-upon approach.
• Temporary decisions expected to change soon.

rubber-duck skill

Invoke @rubber-duck to get an independent second opinion on a plan, implementation, or test suite. This is the same pattern as GitHub Copilot CLI's built-in Rubber Duck feature — a different perspective to catch what the primary agent missed.

When to invoke

How to call it

@rubber-duck Mode: PLAN REVIEW

Plan: <paste plan.md content or path>
Story: <paste story frontmatter + scenarios>

@rubber-duck Mode: CODE REVIEW

Files changed:
- src/scheduler.ts
- src/jobs/notify.ts
- src/queue/index.ts

<paste diff or file content>

@rubber-duck Mode: TEST REVIEW

Test files:
- tests/unit/scheduler.test.ts
- tests/e2e/notify.spec.ts
- features/scheduler.feature

<paste test content>

Verdict handling

CRITICAL findings always block. WARN findings are surfaced to the human for a decision. INFO findings are logged but do not block.

Tips

• You do not need to prepare anything special — just pass the relevant content.
• The rubber duck will not rewrite your code. It only surfaces findings. Acting on them is your job.
• For Copilot CLI users: the built-in /experimental Rubber Duck activates automatically at the same checkpoints. This skill adds equivalent coverage when using Claude Code or OpenCode.

SKILL: Ship-Safe Audit

What It Does

Runs ship-safe — a pre-ship security and quality scanner that checks for secrets, vulnerabilities, and risky patterns before code reaches production.

Usage

npx ship-safe audit .

Run from the project root. No install required (npx fetches it on demand).

Opt-In

Ship-safe is disabled by default. To enable it:

• CI/CD: set the repository variable ENABLE_SHIP_SAFE=true in GitHub → Settings → Variables
• Agents / local: set env var ENABLE_SHIP_SAFE=true before invoking /ship-safe

When to Use

Only run if ENABLE_SHIP_SAFE=true is set. When enabled, appropriate moments are:

• Before opening a PR
• After adding new dependencies
• Before merging any feature branch to main
• After touching auth, secrets handling, or infra config

Output Interpretation

Agent Instructions

1. Run npx ship-safe audit . from the repo root.
2. Parse stdout for CRITICAL/HIGH findings — these are blockers.
3. For each blocker: report the file, line, and finding description.
4. For MEDIUM/LOW: report as advisory, do not block.
5. If all checks pass: confirm "ship-safe: clean" and proceed.
6. If blockers found: halt the task, report findings to Orchestrator.

Example Integration (architect / pre-ship checklist)

/ship-safe

The skill runs the audit, colors findings by severity, and surfaces blockers before any merge action.

SKILL: spec-kit

Purpose

Produce a complete Gherkin story file in docs/stories/ before any implementation begins. One invocation = one story file. The story file is the minimum spec — no additional artifacts required.

State Machine

feature description → story draft → human approval → DISCOVER

No step may begin until the previous one completes. Approval = human sets status: approved in the story frontmatter, or confirms verbally.

Story File Location

docs/stories/{epic-slug}-{feature-slug}.md   # with epic context
docs/stories/{feature-slug}.md               # standalone feature

Story File Template

---
id: "{feature-slug}"
title: "{Feature Title}"
epic: "{epic-slug or null}"
priority: "high|medium|low"
ui: false
adr_required: false
phase: discover
labels:
  - "type:feature"
  - "priority:{priority}"
status: draft
---

## Story

**As a** {user role},
**I want** {what they want},
**so that** {business outcome}.

## Acceptance Criteria

```gherkin
@story:{feature-slug} @priority:{priority}
Feature: {Feature Title}

  Scenario: {happy path title}
    Given {precondition}
    When {action}
    Then {outcome}

  Scenario: {failure or edge case title}
    Given {precondition}
    When {action}
    Then {outcome}

Definition of Done

• All Gherkin scenarios have passing step implementations
• Unit tests written and passing
• Code reviewed and approved
• Documentation updated if user-facing

## Validate a Story File

```bash
validate_story() {
  local file="$1"

  if [ ! -f "$file" ]; then
    echo "[spec-kit] MISSING  $file"
    return 1
  fi

  if ! grep -qE "^\s*(Scenario|Scenario Outline):" "$file"; then
    echo "[spec-kit] FAIL  $file — no Gherkin scenarios found"
    return 1
  fi

  STATUS=$(grep -m1 "^status:" "$file" | awk '{print $2}' | tr -d '"')
  if [ "$STATUS" != "approved" ]; then
    echo "[spec-kit] BLOCKED  $file  status=$STATUS  required=approved"
    return 1
  fi

  echo "[spec-kit] OK  $file  status=approved"
}

# Example
validate_story "docs/stories/user-auth-reset-password.md" || exit 1

Check All Stories Are Approved

FAIL=0
STORIES=$(find docs/stories -name "*.md" ! -name "_template.md" 2>/dev/null || true)

if [ -z "$STORIES" ]; then
  echo "[spec-kit] SKIP  no story files found"
  exit 0
fi

for story in $STORIES; do
  validate_story "$story" || FAIL=1
done

exit $FAIL

Scenario Count Guidelines

Do not invent scenarios not implied by the feature description. Mark unknown cases as TODO and flag for human review.

Skip Conditions

BRANCH=$(git branch --show-current)
if echo "$BRANCH" | grep -qE '^(spike|chore)/'; then
  echo "[spec-kit] SKIP  branch=$BRANCH — spike/chore exempt"
  exit 0
fi

Failure Modes

Logging

[spec-kit] WRITE   docs/stories/user-auth-reset-password.md
[spec-kit] HALT    awaiting human approval
[spec-kit] OK      docs/stories/user-auth-reset-password.md  status=approved
[spec-kit] SKIP    spike/* branch — spec-kit not required

SKILL: SRE Review

Purpose

Evaluate operational readiness of new features before launch.

Failure Mode Analysis

For each new component, document:

1. What can fail? (service down, latency spike, data corruption, cascade)
2. Blast radius? (who is affected? how many users?)
3. Detection time? (how quickly will alerts fire?)
4. Recovery time? (how long to restore service?)
5. Can it be rolled back? (feature flag? migration rollback?)

Observability Requirements

Metrics (Prometheus/CloudWatch/Datadog)

{feature}_requests_total{status="success|error"} counter
{feature}_request_duration_seconds histogram
{feature}_active_connections gauge
{feature}_errors_total{type="validation|timeout|upstream"} counter

Logs (Structured JSON)

{
  "timestamp": "ISO8601",
  "level": "info|warn|error",
  "service": "{service-name}",
  "trace_id": "{distributed-trace-id}",
  "user_id": "{anonymized}",
  "action": "{what happened}",
  "duration_ms": 42,
  "result": "success|error",
  "error": "{message if error}"
}

Traces

• Instrument all cross-service calls with OpenTelemetry.
• Trace IDs propagated via W3C Trace Context headers.

Alerts

Runbook Template

docs/runbooks/{feature}-runbook.md

# Runbook: {Feature Name}

## Symptoms
- {Alert name}: {what the user sees}

## Diagnosis
1. Check logs: `kubectl logs -l app={service} --tail=100`
2. Check metrics: {dashboard URL}
3. Check dependencies: {health check commands}

## Mitigation
### Option A: Restart service
```bash
kubectl rollout restart deployment/{service}
kubectl rollout status deployment/{service}

Option B: Feature flag off

# Disable via environment variable
kubectl set env deployment/{service} FEATURE_{NAME}_ENABLED=false

Escalation

• On-call: {PagerDuty rotation}
• Escalation: {eng manager}
• War room: {Slack channel}

SKILL: story-issue-sync

Purpose

Maintain bidirectional consistency between story files (docs/stories/*.md) and GitHub Issues. The file is authoritative for narrative and Gherkin. The issue is authoritative for labels, status, project board position, and DoD checklist state.

Ownership Model

Inputs / Outputs

Create: File → Issue

When a new story file exists with issue_number: null:

STORY_FILE="docs/stories/user-auth-reset-password-20250416143000-0001.md"

# Extract frontmatter fields
TITLE=$(python3 -c "
import sys, re
text = open('$STORY_FILE').read()
m = re.search(r'^title:\s*[\"\'](.*?)[\"\']', text, re.MULTILINE)
print(m.group(1) if m else '')
")

LABELS=$(python3 -c "
import sys, re
text = open('$STORY_FILE').read()
m = re.findall(r'^\s+- [\"\'](.*?)[\"\']\s*$', text, re.MULTILINE)
print(','.join(m))
")

MILESTONE=$(python3 -c "
import sys, re
text = open('$STORY_FILE').read()
m = re.search(r'^milestone:\s*[\"\'](.*?)[\"\']', text, re.MULTILINE)
print(m.group(1) if m else '')
")

# Create the issue
RESULT=$(gh issue create \
  --title "$TITLE" \
  --body-file "$STORY_FILE" \
  --label "$LABELS" \
  --milestone "$MILESTONE" \
  --json number,url,id)

ISSUE_NUMBER=$(echo "$RESULT" | python3 -c "import sys,json; print(json.load(sys.stdin)['number'])")
ISSUE_URL=$(echo "$RESULT"    | python3 -c "import sys,json; print(json.load(sys.stdin)['url'])")

# Write back to story frontmatter
python3 - <<EOF
import re
text = open('$STORY_FILE').read()
text = re.sub(r'^issue_number: null', f'issue_number: $ISSUE_NUMBER', text, flags=re.MULTILINE)
text = re.sub(r'^issue_url: null', f'issue_url: "$ISSUE_URL"', text, flags=re.MULTILINE)
open('$STORY_FILE', 'w').write(text)
EOF

echo "[story-sync] CREATED  #$ISSUE_NUMBER  ← $STORY_FILE"

Update: File → Issue (body changed)

When story Gherkin or acceptance criteria are edited:

ISSUE_NUMBER=42
STORY_FILE="docs/stories/user-auth-reset-password-20250416143000-0001.md"

gh issue edit "$ISSUE_NUMBER" \
  --body-file "$STORY_FILE"

echo "[story-sync] BODY_UPDATE  #$ISSUE_NUMBER  ← $STORY_FILE"

Sync: Issue → File (labels changed)

When labels on the issue change (e.g., after PO updates priority or phase advances):

ISSUE_NUMBER=42
STORY_FILE="docs/stories/user-auth-reset-password-20250416143000-0001.md"

# Fetch current labels from issue
CURRENT_LABELS=$(gh issue view "$ISSUE_NUMBER" \
  --json labels \
  --jq '[.labels[].name] | join(",")')

# Rewrite labels block in frontmatter
python3 - <<EOF
import re
text = open('$STORY_FILE').read()
label_lines = '\n'.join(f'  - "{l}"' for l in "$CURRENT_LABELS".split(',') if l)
text = re.sub(
    r'^labels:\n(  - .*\n)+',
    f'labels:\n{label_lines}\n',
    text,
    flags=re.MULTILINE
)
open('$STORY_FILE', 'w').write(text)
EOF

echo "[story-sync] LABELS_SYNC  #$ISSUE_NUMBER  → $STORY_FILE"

Detect Drift (file vs issue)

Run before any update to check whether file and issue are in sync:

ISSUE_NUMBER=42
STORY_FILE="docs/stories/user-auth-reset-password-20250416143000-0001.md"

FILE_TITLE=$(python3 -c "
import re
m = re.search(r'^title:\s*[\"\'](.*?)[\"\']', open('$STORY_FILE').read(), re.MULTILINE)
print(m.group(1) if m else '')
")

ISSUE_TITLE=$(gh issue view "$ISSUE_NUMBER" --json title --jq '.title')

if [ "$FILE_TITLE" != "$ISSUE_TITLE" ]; then
  echo "[story-sync] DRIFT  title mismatch: file='$FILE_TITLE'  issue='$ISSUE_TITLE'"
  # File is authoritative for title — update the issue
  gh issue edit "$ISSUE_NUMBER" --title "$FILE_TITLE"
fi

Batch Sync (all stories)

find docs/stories -name "*.md" ! -name "_template.md" | while read -r f; do
  NUMBER=$(python3 -c "
import re
m = re.search(r'^issue_number:\s*(\d+)', open('$f').read(), re.MULTILINE)
print(m.group(1) if m else '')
")
  if [ -z "$NUMBER" ]; then
    echo "[story-sync] NEEDS_CREATE  $f"
  else
    echo "[story-sync] HAS_ISSUE    $f  → #$NUMBER"
  fi
done

Failure Modes

Logging

[story-sync] CREATED       #42  ← docs/stories/user-auth-reset-0001.md
[story-sync] BODY_UPDATE   #42  ← docs/stories/user-auth-reset-0001.md
[story-sync] LABELS_SYNC   #42  → docs/stories/user-auth-reset-0001.md
[story-sync] DRIFT         #42  title mismatch — issue updated
[story-sync] SKIP          #42  no changes detected

SKILL: Stripe Patterns

Local Testing Setup

# Listen for webhooks and forward to local server
stripe listen --forward-to localhost:3000/api/webhooks/stripe

# Trigger test events
stripe trigger payment_intent.succeeded
stripe trigger checkout.session.completed
stripe trigger customer.subscription.created

# Monitor logs
stripe logs tail

Webhook Handler Pattern

// ALWAYS verify webhook signatures — never skip
import Stripe from 'stripe';

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);

export async function POST(req: Request) {
  const body = await req.text();
  const sig = req.headers.get('stripe-signature')!;
  const webhookSecret = process.env.STRIPE_WEBHOOK_SECRET!;

  let event: Stripe.Event;
  try {
    event = stripe.webhooks.constructEvent(body, sig, webhookSecret);
  } catch (err) {
    return new Response(`Webhook Error: ${err.message}`, { status: 400 });
  }

  // Idempotency: check if event already processed
  // Store event.id in database, skip if duplicate

  switch (event.type) {
    case 'payment_intent.succeeded': {
      const paymentIntent = event.data.object as Stripe.PaymentIntent;
      // Handle success
      break;
    }
    case 'checkout.session.completed': {
      const session = event.data.object as Stripe.Checkout.Session;
      // Provision access
      break;
    }
    default:
      console.log(`Unhandled event type: ${event.type}`);
  }

  return new Response(JSON.stringify({ received: true }), { status: 200 });
}

Checkout Session Pattern

const session = await stripe.checkout.sessions.create({
  mode: 'subscription',
  payment_method_types: ['card'],
  line_items: [{
    price: priceId,
    quantity: 1,
  }],
  success_url: `${baseUrl}/success?session_id={CHECKOUT_SESSION_ID}`,
  cancel_url: `${baseUrl}/cancel`,
  customer_email: user.email,
  metadata: {
    userId: user.id,  // link back to your user
  },
}, {
  idempotencyKey: `checkout-${user.id}-${priceId}`,  // ALWAYS use idempotency keys
});

Rules

• ALWAYS verify webhook signatures with constructEvent().
• ALWAYS use idempotency keys on write operations.
• NEVER log raw card data or full payment method details.
• Use restricted API keys with minimum required permissions per service.
• Test every webhook handler with stripe trigger.
• Store Stripe customer IDs in your database for lookup.

SKILL: Supabase Patterns

Local Development Workflow

# Start local Supabase stack
supabase start

# Apply migrations
supabase db push

# Generate TypeScript types
supabase gen types typescript --local > src/types/supabase.ts

# Deploy Edge Functions
supabase functions deploy {function-name}

# Stop
supabase stop

Migration Pattern

-- supabase/migrations/{timestamp}_{description}.sql
-- Up migration (always additive in production)

CREATE TABLE IF NOT EXISTS public.{table_name} (
  id uuid DEFAULT gen_random_uuid() PRIMARY KEY,
  user_id uuid REFERENCES auth.users(id) ON DELETE CASCADE NOT NULL,
  created_at timestamptz DEFAULT now() NOT NULL,
  updated_at timestamptz DEFAULT now() NOT NULL
);

-- Enable RLS ALWAYS
ALTER TABLE public.{table_name} ENABLE ROW LEVEL SECURITY;

-- RLS Policies
CREATE POLICY "{table_name}_select_own"
  ON public.{table_name} FOR SELECT
  USING (auth.uid() = user_id);

CREATE POLICY "{table_name}_insert_own"
  ON public.{table_name} FOR INSERT
  WITH CHECK (auth.uid() = user_id);

CREATE POLICY "{table_name}_update_own"
  ON public.{table_name} FOR UPDATE
  USING (auth.uid() = user_id)
  WITH CHECK (auth.uid() = user_id);

CREATE POLICY "{table_name}_delete_own"
  ON public.{table_name} FOR DELETE
  USING (auth.uid() = user_id);

Edge Function Pattern

// supabase/functions/{name}/index.ts
import { serve } from 'https://deno.land/std@0.177.0/http/server.ts'
import { createClient } from 'https://esm.sh/@supabase/supabase-js@2'

serve(async (req: Request) => {
  const authHeader = req.headers.get('Authorization')
  if (!authHeader) {
    return new Response(JSON.stringify({ error: 'Unauthorized' }), {
      status: 401,
      headers: { 'Content-Type': 'application/json' }
    })
  }

  const supabase = createClient(
    Deno.env.get('SUPABASE_URL') ?? '',
    Deno.env.get('SUPABASE_ANON_KEY') ?? '',
    { global: { headers: { Authorization: authHeader } } }
  )

  // Never use service_role key in Edge Functions unless absolutely necessary
  const { data: { user }, error } = await supabase.auth.getUser()
  if (error || !user) {
    return new Response(JSON.stringify({ error: 'Unauthorized' }), { status: 401 })
  }

  // ... handler logic
})

Rules

• Enable RLS on EVERY table with user data. No exceptions.
• Never expose service_role key to client code.
• Always use supabase gen types typescript for type safety.
• Migrations are append-only (never modify existing migration files).
• Test with supabase start before deploying.

SKILL: TDD Workflow

The RED → GREEN → REFACTOR Cycle

RED Phase (QA Agent)

1. Read the acceptance criterion or task description.
2. Write a test that will fail because the implementation doesn't exist.
3. Run the test. It MUST fail with a meaningful error (not a syntax error).
4. If the test passes immediately → the test is wrong. Rewrite it.
5. Report: file path, test name, failure message.

GREEN Phase (Specialist Agent)

1. Read the failing test file at the provided path.
2. Implement the MINIMUM code to make ONLY that test pass.
3. Do not implement anything not required by the test.
4. Run the test. It must pass.
5. Run the full unit suite to verify no regressions.
6. If the test fails after 3 attempts → escalate to Orchestrator.

REFACTOR Phase (Specialist Agent)

1. Look for: duplication, poor naming, long functions, complex conditionals.
2. Clean up without changing behavior.
3. Run the test again. It must still pass.
4. Commit: git commit -m "refactor: {what was cleaned up}"

ATDD Pattern (Acceptance Test-Driven Development)

1. Write the E2E/acceptance test from the acceptance criterion (Given/When/Then).
2. Watch it fail (RED).
3. Drive out unit tests and implementation to make it pass (GREEN).
4. Acceptance test goes green last.

Integration Test Container Lifecycle

# Before integration tests
docker compose -f docker-compose.test.yml up -d --wait

# Run integration tests
make test-integration

# After tests
docker compose -f docker-compose.test.yml down -v

Rules

• Test file is created BEFORE implementation file.
• Test name format: "should {expected outcome} when {condition}".
• Never weaken an assertion to make a test pass.
• Never mock what you can test with a real dependency (use containers).
• Implementation agent receives FILE PATH, not requirement text.
• Gate: test must fail before implementation, pass after.

SKILL: Terraform Patterns

Module Structure

infra/terraform/
├── modules/
│   ├── networking/
│   ├── database/
│   └── compute/
└── environments/
    ├── dev/
    │   ├── main.tf
    │   ├── variables.tf
    │   └── terraform.tfvars
    ├── staging/
    └── prod/

Module Pattern

# modules/database/main.tf
resource "aws_db_instance" "main" {
  # finops: ~$180/mo (db.t3.medium, 100GB gp3, single AZ)
  identifier     = "${var.environment}-${var.name}-db"
  engine         = "postgres"
  engine_version = "16"
  instance_class = var.instance_class

  allocated_storage     = var.storage_gb
  storage_type          = "gp3"
  storage_encrypted     = true

  username = var.username
  password = var.password

  vpc_security_group_ids = [aws_security_group.db.id]
  db_subnet_group_name   = aws_db_subnet_group.main.name

  backup_retention_period = var.environment == "prod" ? 7 : 1
  deletion_protection     = var.environment == "prod"

  tags = merge(var.tags, {
    Environment = var.environment
    ManagedBy   = "terraform"
  })
}

Workflow

# Initialize (first time or after provider changes)
terraform init

# Format check (CI)
terraform fmt -check -recursive

# Validate syntax
terraform validate

# Plan (always before apply)
terraform plan -out=plan.tfplan -var-file=environments/dev/terraform.tfvars

# Apply (requires explicit instruction)
terraform apply plan.tfplan

# State inspection
terraform show
terraform state list

Rules

• ALWAYS run terraform validate before reporting complete.
• ALWAYS run terraform plan to show what will change.
• NEVER run terraform apply without explicit instruction.
• ALWAYS annotate resources with # finops: cost estimate.
• Use workspaces or separate state files per environment.
• Enable state locking (S3 + DynamoDB or Terraform Cloud).
• Tag all resources with environment, managed-by, and cost-center.

SKILL: Threat Modeling (STRIDE)

Output Location

docs/specs/{feature-slug}/threat-model.md

STRIDE Framework

For each component and trust boundary, evaluate all 6 threat categories:

Threat Model Template

# Threat Model: {Feature Name}

## Assets
| Asset | Sensitivity | Owner |
|-------|-------------|-------|
| User PII | High | {team} |
| Payment data | Critical | {team} |
| API keys | Critical | {team} |

## Trust Boundaries
- Internet <-> Load Balancer
- Load Balancer <-> Application
- Application <-> Database
- Application <-> Third-party APIs

## STRIDE Analysis

### {Component Name}

**S — Spoofing**
- Risk: {description}
- Likelihood: High/Medium/Low
- Impact: High/Medium/Low
- Mitigation: {control}

**T — Tampering**
...

**R — Repudiation**
...

**I — Information Disclosure**
...

**D — Denial of Service**
...

**E — Elevation of Privilege**
...

## Risk Register
| Threat | Component | Likelihood | Impact | Risk Level | Mitigation | Status |
|--------|-----------|------------|--------|------------|------------|--------|
| SQL Injection | API | High | Critical | Critical | Parameterized queries | Mitigated |

## Mitigations Required Before Launch
- [ ] {Critical mitigation 1}
- [ ] {Critical mitigation 2}

Common Mitigations

• Authentication: JWT with short expiry, refresh token rotation.
• Authorization: RBAC, RLS on database.
• Input validation: Zod/FluentValidation on all inputs.
• Rate limiting: Per-IP and per-user limits.
• Encryption: TLS 1.3 in transit, AES-256 at rest.
• Audit logging: All write operations logged with actor + timestamp.
• Secrets management: Never in code; use environment variables or vault.

SKILL: Vercel Patterns

vercel.json Configuration

{
  "framework": "nextjs",
  "buildCommand": "npm run build",
  "devCommand": "npm run dev",
  "installCommand": "npm ci",
  "regions": ["iad1"],
  "headers": [
    {
      "source": "/api/(.*)",
      "headers": [
        { "key": "X-Content-Type-Options", "value": "nosniff" },
        { "key": "X-Frame-Options", "value": "DENY" },
        { "key": "Strict-Transport-Security", "value": "max-age=31536000" }
      ]
    }
  ],
  "rewrites": [],
  "redirects": [
    {
      "source": "/old-path",
      "destination": "/new-path",
      "permanent": true
    }
  ]
}

Runtime Selection

// Edge Runtime (low-latency, streaming, middleware)
export const runtime = 'edge';

// Node.js Runtime (heavy compute, native modules, file system)
export const runtime = 'nodejs';

// ISR (static with revalidation)
export const revalidate = 3600; // seconds

Environment Variables

# Pull env vars for local development
vercel env pull .env.local

# Add env var
vercel env add SECRET_KEY production

# List env vars
vercel env ls

Deployment Workflow

# Build locally first (catch errors before deploy)
vercel build

# Deploy prebuilt (faster, recommended for CI)
vercel deploy --prebuilt

# Deploy to production
vercel deploy --prod --prebuilt

Middleware Pattern

// middleware.ts (runs at edge, before every request)
import { NextResponse } from 'next/server';
import type { NextRequest } from 'next/server';

export function middleware(request: NextRequest) {
  // Auth check, rate limiting, A/B testing, etc.
  const token = request.cookies.get('token');
  if (!token && request.nextUrl.pathname.startsWith('/dashboard')) {
    return NextResponse.redirect(new URL('/login', request.url));
  }
  return NextResponse.next();
}

export const config = {
  matcher: ['/dashboard/:path*', '/api/protected/:path*'],
};

Rules

• Run vercel build locally before deploying to catch errors.
• Use vercel env pull to sync environment variables locally.
• Prefer Edge runtime for middleware and simple API routes.
• Use Node.js runtime for heavy compute or native module requirements.
• Set security headers for all API routes.

SKILL: visual-identity

Purpose

Produce a coherent visual identity from a brief or set of brand keywords. Outputs are palette, typography pairing, spacing scale, and radius scale — all serialised to JSON files that feed the design-tokens skill. Human approval required before tokens propagate to UI.

Inputs

Outputs

Target awareness

When design.target (project.config.yaml, default web) is tui, keep the same JSON outputs but constrain choices to the terminal: colors must be expressible in ANSI-256 (record the nearest 256 index alongside each hex), every fg/bg role pair must clear WCAG 2.2 AA contrast, and typography.json describes terminal text styles (bold, dim/faint, italic, underline, reverse) rather than font families and px sizes. The palette/typography/scale templates below still apply structurally; adapt their values for the terminal.

Palette Structure

docs/design/identity/palette.json:

{
  "brand": {
    "primary":   { "value": "#2563eb", "on": "#ffffff", "contrast_aa": true },
    "secondary": { "value": "#7c3aed", "on": "#ffffff", "contrast_aa": true },
    "accent":    { "value": "#0ea5e9", "on": "#ffffff", "contrast_aa": true }
  },
  "semantic": {
    "success":  { "value": "#16a34a", "on": "#ffffff", "contrast_aa": true },
    "warning":  { "value": "#d97706", "on": "#000000", "contrast_aa": true },
    "error":    { "value": "#dc2626", "on": "#ffffff", "contrast_aa": true },
    "info":     { "value": "#0284c7", "on": "#ffffff", "contrast_aa": true }
  },
  "neutral": {
    "50":  "#f8fafc",
    "100": "#f1f5f9",
    "200": "#e2e8f0",
    "300": "#cbd5e1",
    "400": "#94a3b8",
    "500": "#64748b",
    "600": "#475569",
    "700": "#334155",
    "800": "#1e293b",
    "900": "#0f172a"
  },
  "surface": {
    "background": "#ffffff",
    "foreground": "#0f172a",
    "muted":      "#f1f5f9",
    "border":     "#e2e8f0"
  }
}

WCAG Contrast Check

All palette entries with on values must pass WCAG 2.2 AA (4.5:1 for normal text, 3:1 for large text):

def relative_luminance(hex_color):
    r, g, b = (int(hex_color[i:i+2], 16) / 255 for i in (1, 3, 5))
    def linearize(c):
        return c / 12.92 if c <= 0.04045 else ((c + 0.055) / 1.055) ** 2.4
    r, g, b = linearize(r), linearize(g), linearize(b)
    return 0.2126 * r + 0.7152 * g + 0.0722 * b

def contrast_ratio(fg, bg):
    l1 = relative_luminance(fg)
    l2 = relative_luminance(bg)
    lighter, darker = max(l1, l2), min(l1, l2)
    return (lighter + 0.05) / (darker + 0.05)

# AA normal text requires >= 4.5
# AA large text requires >= 3.0
ratio = contrast_ratio("#2563eb", "#ffffff")
assert ratio >= 4.5, f"FAIL: contrast {ratio:.2f} < 4.5 for #2563eb on #ffffff"

If any pair fails AA, adjust the shade until it passes. Never ship a palette with failing contrast.

Typography Structure

docs/design/identity/typography.json:

{
  "families": {
    "sans":  "Inter, system-ui, -apple-system, sans-serif",
    "mono":  "JetBrains Mono, 'Fira Code', monospace",
    "serif": null
  },
  "scale": {
    "xs":   { "size": "0.75rem",  "line": "1rem" },
    "sm":   { "size": "0.875rem", "line": "1.25rem" },
    "base": { "size": "1rem",     "line": "1.5rem" },
    "lg":   { "size": "1.125rem", "line": "1.75rem" },
    "xl":   { "size": "1.25rem",  "line": "1.75rem" },
    "2xl":  { "size": "1.5rem",   "line": "2rem" },
    "3xl":  { "size": "1.875rem", "line": "2.25rem" },
    "4xl":  { "size": "2.25rem",  "line": "2.5rem" }
  },
  "weights": {
    "regular": 400,
    "medium":  500,
    "semibold": 600,
    "bold":    700
  }
}

Spacing + Radius Scales

Written directly into tokens.json (see design-tokens skill for full schema):

{
  "spacing": {
    "1":  "0.25rem",
    "2":  "0.5rem",
    "3":  "0.75rem",
    "4":  "1rem",
    "6":  "1.5rem",
    "8":  "2rem",
    "12": "3rem",
    "16": "4rem"
  },
  "radius": {
    "none": "0",
    "sm":   "0.125rem",
    "md":   "0.375rem",
    "lg":   "0.5rem",
    "xl":   "0.75rem",
    "full": "9999px"
  }
}

Write palette.json

mkdir -p docs/design/identity
# Write palette.json from the template above, populated with chosen values
# Then validate all contrast ratios before writing
python3 scripts/validate-palette.py docs/design/identity/palette.json

Approval Gate

Mark docs/design/identity/palette.json approved before design-tokens runs:

Add to the top of palette.json:

{ "_meta": { "status": "draft", "approved_by": null, "approved_at": null }, ... }

Check in design-tokens skill:

STATUS=$(python3 -c "import json; print(json.load(open('docs/design/identity/palette.json'))['_meta']['status'])")
[ "$STATUS" = "approved" ] || { echo "BLOCKED: palette not approved"; exit 1; }

Failure Modes

Logging

[visual-identity] PALETTE    docs/design/identity/palette.json  contrast=all-pass
[visual-identity] TYPOGRAPHY docs/design/identity/typography.json
[visual-identity] SKIP       docs/design/identity/palette.json  (approved — locked)
[visual-identity] CONTRAST_FAIL  #2563eb on #ffffff  ratio=3.8  required=4.5

SKILL: wireframe

Purpose

Generate low-fidelity wireframes from user story files. Output is deterministic — given the same story and layout hints, the same wireframe structure is produced. Three output formats: ASCII (default), SVG, HTML. Human approval is required before the wireframe feeds downstream mockup work.

Inputs

Outputs

The required files depend on design.target in project.config.yaml (default web) — see Target awareness:

A wireframe stage that produces fewer than the files required for the active target is incomplete. Do not PAUSE or mark DONE without them.

Target awareness

design.target decides which files are required:

• web — <id>.wireframe.md (ASCII) + .html (preview) + .excalidraw.
• tui — <id>.wireframe.md (ASCII/box-drawing) + .excalidraw. No .html.

Use box-drawing primitives for tui layouts, label panes/overlays/status bar, and include the keybinding legend and focus order inline in the .md. The Excalidraw generator below applies to both targets; the HTML generator is web only.

ASCII Wireframe Primitives

Use these consistently across all wireframes:

┌─────────────────────────────────┐   ← container / card
│  [Label]  [Input Field      ]   │   ← label + text input
│  [Button: Primary Action    ]   │   ← primary button
│  [Button: Secondary]            │   ← secondary button
│  ○ Option A  ○ Option B         │   ← radio group
│  ☐ Checkbox label               │   ← checkbox
│  ▼ Dropdown / Select            │   ← select / combobox
│  ──────────────────────         │   ← divider
│  ⚠ Error message text           │   ← validation error
│  ✓ Success confirmation         │   ← success state
└─────────────────────────────────┘

[Nav: Logo | Item 1 | Item 2 | CTA]  ← navigation bar
[ Sidebar  ][     Main Content    ]  ← two-column layout
[  Col 1  ][  Col 2  ][  Col 3  ]   ← three-column grid
[         Full-width Banner         ]← hero / header band

ASCII Wireframe — Example (Password Reset)

┌──────────────────────────────────────┐
│            Reset Password            │
│                                      │
│  Email                               │
│  [                              ]    │
│                                      │
│  ⚠ No account found for this email  │  ← error state
│                                      │
│  [Button: Send Reset Link       ]    │
│                                      │
│  ← Back to Login                     │
└──────────────────────────────────────┘

Generate Wireframe Files

For each story, produce all three output files. Run these steps:

STORY_FILE="docs/stories/auth-reset-password-20250416143000-0001.md"
STORY_ID=$(python3 -c "
import re
m = re.search(r'^id:\s*[\"\'](.*?)[\"\']', open('$STORY_FILE').read(), re.MULTILINE)
print(m.group(1) if m else 'unknown')
")
mkdir -p docs/design/wireframes

Step 1 — Write ${STORY_ID}.wireframe.md (ASCII layout + approval metadata):

---
story_id: "{story_id}"
story_file: "{story_file}"
status: draft          # draft | approved | rejected
approved_by: null
approved_at: null
---

## Wireframe: {story title}

### Default state
{ASCII wireframe}

### Error state
{ASCII wireframe — validation error}

### Success state
{ASCII wireframe — confirmation}

### Interaction Notes

- Tab order: {list of focusable elements in tab sequence}
- Primary action: {describe}
- Error handling: {describe visible error states}

### Approval

- [ ] Approved by product owner
- [ ] Approved by UX lead (if applicable)

Step 2 — Write ${STORY_ID}.wireframe.html (see HTML template below)

Step 3 — Write ${STORY_ID}.wireframe.excalidraw (see Excalidraw template below)

After writing the files required for the active target, verify they exist (web: md, html, excalidraw; tui: md, excalidraw):

ls docs/design/wireframes/${STORY_ID}.wireframe.md
ls docs/design/wireframes/${STORY_ID}.wireframe.excalidraw
# web target also:
ls docs/design/wireframes/${STORY_ID}.wireframe.html 2>/dev/null || true

If any required file is missing, produce it before continuing.

HTML Wireframe (web target only)

For web targets, always generate the HTML wireframe. Skip this section entirely for tui. Use multiple <section> blocks for multi-state wireframes (default, loading, error, success, empty).

cat > "docs/design/wireframes/${STORY_ID}.wireframe.html" <<'HTMLEOF'
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>Wireframe: {story title}</title>
  <style>
    * { box-sizing: border-box; font-family: monospace; }
    body { background: #e9ecef; padding: 2rem; }
    h1 { font-size: 1rem; color: #495057; margin-bottom: 1.5rem; }
    .states { display: flex; flex-wrap: wrap; gap: 1.5rem; }
    .state { background: #f8f9fa; border: 1px solid #adb5bd; border-radius: 4px; padding: 0; min-width: 360px; }
    .state-label { background: #343a40; color: #fff; font-size: .75rem; padding: .25rem .75rem; border-radius: 4px 4px 0 0; }
    .frame { padding: 1.5rem; }
    .screen-title { font-weight: bold; font-size: 1.1rem; margin-bottom: 1rem; border-bottom: 1px solid #dee2e6; padding-bottom: .5rem; }
    label { display: block; font-size: .8rem; color: #495057; margin-bottom: .2rem; margin-top: .75rem; }
    .input { border: 1px solid #868e96; padding: .4rem .6rem; width: 100%; background: #fff; }
    .btn { border: none; padding: .5rem 1rem; cursor: default; margin-top: .75rem; width: 100%; font-weight: bold; }
    .btn-primary { background: #343a40; color: #fff; }
    .btn-secondary { background: transparent; border: 1px solid #343a40; color: #343a40; }
    .error { color: #c0392b; font-size: .8rem; margin-top: .25rem; }
    .success { color: #2d6a4f; font-size: .8rem; margin-top: .25rem; }
    .link { color: #1971c2; font-size: .85rem; margin-top: .75rem; display: block; }
    .nav { display: flex; gap: 1rem; background: #343a40; color: #fff; padding: .6rem 1rem; font-size: .85rem; margin-bottom: .75rem; }
    .badge { background: #868e96; color: #fff; font-size: .7rem; padding: .1rem .4rem; border-radius: 3px; }
    .divider { border: none; border-top: 1px solid #dee2e6; margin: .75rem 0; }
    .tab-order { font-size: .7rem; color: #868e96; margin-top: 1.5rem; border-top: 1px dashed #dee2e6; padding-top: .5rem; }
  </style>
</head>
<body>
  <h1>Wireframe: {story title} — {story_id}</h1>
  <div class="states">

    <div class="state">
      <div class="state-label">Default state</div>
      <div class="frame">
        <div class="screen-title">{Screen Title}</div>
        <!-- Add form fields, buttons, content blocks here -->
        <label>Field label</label>
        <input class="input" type="text" placeholder="placeholder" disabled />
        <div class="btn btn-primary">Primary Action</div>
        <a class="link" href="#">Secondary link</a>
        <div class="tab-order">Tab order: Field → Primary Action → Secondary link</div>
      </div>
    </div>

    <div class="state">
      <div class="state-label">Error state</div>
      <div class="frame">
        <div class="screen-title">{Screen Title}</div>
        <label>Field label</label>
        <input class="input" type="text" placeholder="placeholder" disabled style="border-color:#c0392b" />
        <div class="error">⚠ Error message describing the problem</div>
        <div class="btn btn-primary">Primary Action</div>
        <div class="tab-order">Tab order: Field → Primary Action</div>
      </div>
    </div>

    <div class="state">
      <div class="state-label">Success state</div>
      <div class="frame">
        <div class="screen-title">{Screen Title}</div>
        <div class="success">✓ Success confirmation message</div>
        <div class="btn btn-secondary">Back / Next step</div>
      </div>
    </div>

  </div>
</body>
</html>
HTMLEOF

Extend with real field names, content, and states from the story Gherkin. One <div class="state"> block per Gherkin scenario.

Excalidraw Wireframe (always required)

Always generate the Excalidraw file — every story, every run. Excalidraw is the canonical editable wireframe format reviewers annotate.

Write the file as valid JSON to docs/design/wireframes/${STORY_ID}.wireframe.excalidraw. Each UI element is one entry in the elements array. Use the element templates below, copy and adapt:

python3 - <<'PYEOF'
import json, pathlib, os

story_id = os.environ.get("STORY_ID", "unknown")
out = pathlib.Path(f"docs/design/wireframes/{story_id}.wireframe.excalidraw")
out.parent.mkdir(parents=True, exist_ok=True)

# ── Element helpers ──────────────────────────────────────────────────────────
def rect(id, x, y, w, h, label="", bg="transparent", stroke="#343a40", bold=False):
    els = [{
        "id": id, "type": "rectangle", "x": x, "y": y, "width": w, "height": h,
        "angle": 0, "strokeColor": stroke, "backgroundColor": bg,
        "fillStyle": "solid", "strokeWidth": 2, "strokeStyle": "solid",
        "roughness": 1, "opacity": 100, "groupIds": [], "roundness": {"type": 3},
        "version": 1, "versionNonce": 1, "isDeleted": False,
        "boundElements": None, "updated": 1, "link": None, "locked": False,
    }]
    if label:
        els.append(text(id + "_lbl", x + w/2, y + h/2, label, bold=bold, anchor="center"))
    return els

def text(id, x, y, content, bold=False, anchor="left", color="#343a40"):
    return {
        "id": id, "type": "text", "x": x, "y": y,
        "width": len(content) * 8, "height": 20,
        "angle": 0, "strokeColor": color, "backgroundColor": "transparent",
        "fillStyle": "solid", "strokeWidth": 1, "strokeStyle": "solid",
        "roughness": 1, "opacity": 100, "groupIds": [], "roundness": None,
        "version": 1, "versionNonce": 1, "isDeleted": False,
        "boundElements": None, "updated": 1, "link": None, "locked": False,
        "text": content, "fontSize": 16,
        "fontFamily": 3,  # monospace
        "textAlign": anchor, "verticalAlign": "middle",
        "baseline": 14, "containerId": None, "originalText": content,
        "lineHeight": 1.25,
        "fontWeight": "bold" if bold else "normal",
    }

def input_field(id, x, y, w, label_text):
    return (
        [text(id + "_lbl", x, y - 18, label_text)] +
        rect(id, x, y, w, 32, stroke="#868e96")
    )

def button_primary(id, x, y, w, label_text):
    return rect(id, x, y, w, 36, label=label_text, bg="#343a40", stroke="#343a40", bold=True)

def button_secondary(id, x, y, w, label_text):
    return rect(id, x, y, w, 36, label=label_text, bg="transparent", stroke="#343a40")

def section_label(id, x, y, content):
    return [text(id, x, y, f"[ {content} ]", color="#868e96")]

# ── Build elements ────────────────────────────────────────────────────────────
elements = []

# Outer frame
elements += rect("frame", 50, 30, 700, 600, stroke="#343a40")

# Screen title
elements.append(text("title", 70, 50, "{Screen Title}", bold=True))

# --- Default state ---
elements += section_label("s_default", 70, 90, "Default state")
elements += input_field("field1", 70, 130, 560, "Field label")
elements += button_primary("btn_primary", 70, 190, 560, "Primary Action")
elements.append(text("link1", 70, 238, "← Secondary link / back", color="#1971c2"))

# --- Error state ---
elements += section_label("s_error", 70, 280, "Error state")
elements += input_field("field1_err", 70, 320, 560, "Field label")
elements += rect("err_border", 70, 320, 560, 32, stroke="#c0392b")
elements.append(text("err_msg", 70, 360, "⚠ Error message text", color="#c0392b"))
elements += button_primary("btn_primary_err", 70, 390, 560, "Primary Action")

# --- Success state ---
elements += section_label("s_success", 70, 450, "Success state")
elements.append(text("success_msg", 70, 490, "✓ Success confirmation", color="#2d6a4f"))
elements += button_secondary("btn_back", 70, 520, 260, "Back / Next step")

doc = {
    "type": "excalidraw",
    "version": 2,
    "source": "MAPLE wireframe-architect",
    "elements": elements,
    "appState": {"viewBackgroundColor": "#f8f9fa", "gridSize": None},
    "files": {},
}
out.write_text(json.dumps(doc, indent=2) + "\n")
print(f"[wireframe] wrote {out}")
PYEOF

Adapt element positions and labels to match the actual story screens. Add more rect/text/input_field/button_primary calls per Gherkin scenario. Do not leave placeholder text ({Screen Title}) in the final file.

Approval Gate

All three files must exist and the .md must be status: approved before mockup or ui-mockup-builder proceeds:

python3 - <<'EOF'
import re, sys, pathlib
sid = open(".claude/state/maple.json").read()  # or pass STORY_ID
# Check required artifacts exist (html is web-only)
cfg = open("project.config.yaml").read() if pathlib.Path("project.config.yaml").exists() else ""
tm = re.search(r'^\s*target:\s*(\w+)', cfg, re.MULTILINE)
target = tm.group(1) if tm else "web"
exts = ["md", "excalidraw"] if target == "tui" else ["md", "html", "excalidraw"]
for ext in exts:
    p = pathlib.Path(f"docs/design/wireframes/{sid}.wireframe.{ext}")
    if not p.exists():
        print(f"BLOCKED: missing {p}")
        sys.exit(1)
# Check approval status in .md
md = pathlib.Path(f"docs/design/wireframes/{sid}.wireframe.md").read_text()
m = re.search(r'^status:\s*(\w+)', md, re.MULTILINE)
status = m.group(1) if m else 'draft'
if status != 'approved':
    print(f"BLOCKED: wireframe {sid} not approved (status={status})")
    sys.exit(1)
print("approved — all three artifacts present")
EOF

Failure Modes

Logging

[wireframe] CREATE   docs/design/wireframes/auth-reset-0001.wireframe.md
[wireframe] CREATE   docs/design/wireframes/auth-reset-0001.wireframe.html
[wireframe] CREATE   docs/design/wireframes/auth-reset-0001.wireframe.excalidraw
[wireframe] SKIP     docs/design/wireframes/auth-reset-0001.wireframe.md  (approved — locked)
[wireframe] BLOCKED  auth-reset-0001  status=draft — needs approval before mockup
[wireframe] BLOCKED  auth-reset-0001  missing .html — generating now

SKILL: a11y-audit

Purpose

Run WCAG 2.2 Level AA accessibility audits against generated UI. Uses axe-core (via @axe-core/cli) or pa11y as available. Posts findings as PR comments. Blocks merge on AA violations. Required for every story with ui: true.

Target awareness

When design.target (project.config.yaml, default web) is tui, skip the browser tooling (axe/pa11y) and the preview URL. Instead evaluate the terminal a11y checklist from docs/design/design-targets.md and write the findings to docs/design/mockups/<id>.a11y.json using the SAME object shape the web path produces — an object with violations[], where each violation has id, impact (critical|serious|moderate|minor), description, help, and nodes[] ({target:[...], failureSummary}). The gate (scripts/sdlc/a11y-gate.sh) reads only violations[].impact, so matching this shape keeps it unchanged. Map checklist failures to impacts: keyboard-reachable→critical, focus-visible→serious, color-contrast→serious, color-only-signaling→serious, no-color-support→moderate, min-width-resize→moderate. The WCAG criteria, tool-detection, axe/pa11y, and PR-comment sections below apply to web targets.

WCAG 2.2 AA — Minimum Requirements

Tool Detection

detect_tool() {
  if command -v axe &>/dev/null; then
    echo "axe"
  elif command -v pa11y &>/dev/null; then
    echo "pa11y"
  elif npx --yes @axe-core/cli --version &>/dev/null 2>&1; then
    echo "axe-npx"
  else
    echo "none"
  fi
}
TOOL=$(detect_tool)

Run with axe-core CLI

URL="${1:-http://localhost:3000}"  # preview URL or Storybook story URL
STORY_ID="${2:-unknown}"
REPORT="docs/design/mockups/${STORY_ID}.a11y.json"

mkdir -p docs/design/mockups

axe "$URL" \
  --stdout \
  --tags wcag2a,wcag2aa,wcag21aa,wcag22aa \
  > "$REPORT"

VIOLATIONS=$(python3 -c "import json,sys; d=json.load(open('$REPORT')); print(len(d.get('violations',[])))")
echo "[a11y-audit] axe  $URL  violations=$VIOLATIONS"

Run with pa11y

URL="${1:-http://localhost:3000}"
STORY_ID="${2:-unknown}"
REPORT="docs/design/mockups/${STORY_ID}.a11y.json"

pa11y "$URL" \
  --standard WCAG2AA \
  --reporter json \
  > "$REPORT" 2>&1

ISSUES=$(python3 -c "import json,sys; d=json.load(open('$REPORT')); print(len(d) if isinstance(d,list) else 0)")
echo "[a11y-audit] pa11y  $URL  issues=$ISSUES"

Parse Results and Classify

import json, sys

report_path = sys.argv[1]
data = json.load(open(report_path))

# axe format
violations = data.get("violations", [])
passes     = data.get("passes", [])

critical = [v for v in violations if v["impact"] in ("critical", "serious")]
moderate = [v for v in violations if v["impact"] == "moderate"]
minor    = [v for v in violations if v["impact"] == "minor"]

print(f"CRITICAL/SERIOUS: {len(critical)}")
print(f"MODERATE:         {len(moderate)}")
print(f"MINOR:            {len(minor)}")
print(f"PASSES:           {len(passes)}")

# Merge gate: block on critical + serious
if critical:
    print("\nMERGE BLOCKED — resolve the following before merging:")
    for v in critical:
        print(f"  [{v['impact'].upper()}] {v['id']}: {v['description']}")
        for node in v.get("nodes", [])[:2]:
            print(f"    → {node.get('target', ['?'])[0]}: {node.get('failureSummary','')[:120]}")
    sys.exit(1)

Post Findings as PR Comment

STORY_ID="auth-reset-0001"
PR_NUMBER=$(gh pr list --head "$(git branch --show-current)" --json number --jq '.[0].number')
REPORT="docs/design/mockups/${STORY_ID}.a11y.json"

# Build comment body
COMMENT=$(python3 - <<'EOF'
import json, sys

data = json.load(open(sys.argv[1]))
violations = data.get("violations", [])

if not violations:
    print("## ✅ A11y Audit Passed\n\nNo WCAG 2.2 AA violations found.")
    sys.exit(0)

lines = [f"## ⚠️ A11y Audit: {len(violations)} violation(s) found\n"]
for v in violations[:10]:
    impact = v.get("impact","").upper()
    lines.append(f"### [{impact}] {v['id']}")
    lines.append(f"_{v['description']}_\n")
    for node in v.get("nodes",[])[:2]:
        selector = ', '.join(node.get("target",[]))
        lines.append(f"- `{selector}`")
        lines.append(f"  {node.get('failureSummary','')[:200]}")
    lines.append("")

if len(violations) > 10:
    lines.append(f"_...and {len(violations)-10} more. See full report in `docs/design/mockups/`._")

print('\n'.join(lines))
EOF
"$REPORT")

gh pr comment "$PR_NUMBER" --body "$COMMENT"
echo "[a11y-audit] PR_COMMENT  #$PR_NUMBER  violations=$(echo "$COMMENT" | grep -c '\[CRITICAL\]\|\[SERIOUS\]' || echo 0)"

Merge Gate Check

Called from scripts/sdlc/a11y-gate.sh (added in Phase VII):

STORY_FILE="$1"
UI=$(python3 -c "
import re
m = re.search(r'^ui:\s*(true|false)', open('$STORY_FILE').read(), re.MULTILINE)
print(m.group(1) if m else 'false')
")

if [ "$UI" != "true" ]; then
  echo "[a11y-audit] SKIP  ui:false story — no audit required"
  exit 0
fi

STORY_ID=$(python3 -c "
import re
m = re.search(r'^id:\s*[\"\'](.*?)[\"\']', open('$STORY_FILE').read(), re.MULTILINE)
print(m.group(1) if m else 'unknown')
")
REPORT="docs/design/mockups/${STORY_ID}.a11y.json"

if [ ! -f "$REPORT" ]; then
  echo "[a11y-audit] FAIL  no audit report found for $STORY_ID — run audit before merging"
  exit 1
fi

python3 scripts/sdlc/parse-a11y-report.py "$REPORT"