codebyplan 1.5.1 → 1.9.0

package/templates/skills/cbp-frontend-ui/reference/variant-defaults.md

@@ -0,0 +1,149 @@
+# Variant Defaults & Button Patterns
+
+3-layer variant architecture using `createResolver` with SIZE, COLOR, and CUSTOM variants, lightweight variant maps for simpler components, plus button-specific patterns.
+
+Apply when working with `variants.ts` files, components in `src/components/buttons/`, or components using size/color variant props with BEM modifier classes. Ensures correct variant resolution order and prevents duplicate defaults.
+
+## 1. 3-Layer Architecture
+
+```
+Props -> createResolver -> CSS Classes
+         Resolution Order:
+         1. Custom variant (presets)
+         2. Size variant (typography/spacing)
+         3. Color variant (colors/interactions)
+         4. Direct prop overrides (highest priority)
+```
+
+## 2. Never Duplicate Defaults
+
+Values in SIZE/COLOR/CUSTOM_VARIANTS MUST NOT repeat defaults:
+
+```typescript
+// WRONG
+const defaults = { fontWeight: 'medium', typoPx: 's1' };
+const SIZE_VARIANTS = {
+  md: { fontSize: 'body-md', fontWeight: 'medium' }, // duplicates default
+};
+
+// CORRECT
+const SIZE_VARIANTS = {
+  md: { fontSize: 'body-md' },  // only what differs
+};
+```
+
+## 3. Layer Definitions
+
+**SIZE_VARIANTS** (typography/spacing):
+```typescript
+const SIZE_VARIANTS = {
+  sm: { fontSize: 'body-sm' },
+  md: { fontSize: 'body-md' },
+  lg: { fontSize: 'body-lg', typoPx: 's15', typoPy: 's1' },
+} as const satisfies Record<string, SizeConfig>;
+```
+
+**COLOR_VARIANTS** (colors/interactions):
+```typescript
+const COLOR_VARIANTS = {
+  primary: { bg: 'primary', text: 'inverse' },
+  highlight: { bg: 'highlight', text: 'primary' },
+  transparent: { bg: 'transparent', text: 'primary' },
+} as const satisfies Record<string, ColorConfig>;
+```
+
+**CUSTOM_VARIANTS** (presets combining size + color + overrides):
+```typescript
+const CUSTOM_VARIANTS = {
+  cta: {
+    colorVariant: 'highlight',
+    fontFamily: 'accent',
+    glow: 'sm',
+  },
+} as const satisfies Record<string, CustomConfig>;
+```
+
+## 4. Type Annotations Required
+
+All variant maps MUST use `as const satisfies Record<string, *Config>`.
+
+## 5. createResolver Setup
+
+```typescript
+import { createResolver, SizeConfig, ColorConfig, CustomConfig } from '@/utils/variants';
+
+export const getVariant = createResolver({
+  sizes: SIZE_VARIANTS,
+  colors: COLOR_VARIANTS,
+  custom: CUSTOM_VARIANTS,
+  defaults,
+});
+```
+
+## 6. Button Types
+
+```
+src/components/buttons/
+├── Button/       # Form submit, modal triggers, state changes
+├── LinkButton/   # Navigation (links)
+└── IconButton/   # Icon-only actions
+```
+
+All buttons use `createResolver`. Each has 5 files: `index.ts`, `Component.tsx`, `Component.module.scss`, `types.ts`, `variants.ts`.
+
+## 7. Button Defaults
+
+| Button | Default Size | Default Color |
+|--------|--------------|---------------|
+| Button | md | primary |
+| LinkButton | md | transparent |
+| IconButton | md | transparent |
+
+## 8. SCSS Modifier Includes
+
+All buttons include the standard modifier mixins:
+
+```scss
+.button {
+  @include typography.font-family;
+  @include typography.font-weight;
+  @include typography.font-size;
+  @include typography.tracking;
+  @include typography.leading;
+  @include typography.transform;
+  @include typography.typo-px;
+  @include typography.typo-py;
+  @include typography.typo-gap;
+  @include borders.border-radius;
+  @include borders.border-width;
+  @include borders.border-color;
+  @include interactive.color-interactive;
+  @include shadows.glow;
+  @include a11y.focus-visible;
+}
+```
+
+## 9. Lightweight Variant Maps (Alternative to createResolver)
+
+For components that only need prop-to-BEM-suffix resolution without the full variant pipeline, use simple `Record<TypeUnion, string>` maps or direct prop interpolation.
+
+**When to use**: Component has 1-2 variant dimensions (size, color) with no defaults merging, no custom presets, and no resolution priority logic. Common in icon components and simple wrappers.
+
+**Pattern A — Direct prop interpolation** (no variants.ts needed):
+```typescript
+// Prop value IS the BEM suffix — no map needed
+styles[`spinner--${size}`]
+styles[`checkmark--text-${color}`]
+```
+
+**Pattern B — Explicit variant map** (in variants.ts):
+```typescript
+export const SIZE_VARIANTS: Record<ContainerSize, string> = {
+  sm: 'sm',
+  md: 'md',
+  lg: 'lg',
+}
+// Usage: styles[`container--${SIZE_VARIANTS[size]}`]
+```
+
+**Decision rule**: If prop values map 1:1 to BEM suffixes, use Pattern A. If mapping differs from prop names or you want a centralized variants.ts, use Pattern B. If you need defaults merging, resolution priority, or custom presets, use `createResolver` (sections 1-5).

package/templates/skills/cbp-frontend-ux/SKILL.md

@@ -0,0 +1,181 @@
+---
+scope: org-shared
+name: cbp-frontend-ux
+description: Interaction-quality self-review pass loaded by round-executor AFTER UI code is written. Catches navigation flow issues, missing feedback states, cognitive-load problems, form usability gaps, and accessibility violations. Auto-applies in-scope mechanical UX fixes within the round's files_changed. Replaces the post-implementation ux-agent spawn with an inline skill invocation.
+effort: xhigh
+---
+
+# Frontend UX (Post-Implementation Interaction Self-Review)
+
+Loaded by `round-executor` Step 3.8 AFTER UI code is written. Inline counterpart of `frontend-design` (pre-implementation aesthetic) and sibling of `frontend-ui` (post-implementation visual review). This skill evaluates interaction quality and auto-applies mechanical UX fixes that fall inside the round's `files_changed`.
+
+## When this skill fires
+
+Round-executor invokes when the round's `files_changed` contains ANY of:
+
+- `*.tsx`, `*.jsx` (React, RN, RN-Web components)
+- New page / screen / route / layout files
+- Form / modal / interactive control files
+- Plan deliverables explicitly mentioning interaction, navigation, form, feedback, error, loading
+
+If none match, skip — proceed to Step 4 (Quality Checks).
+
+## Input Contract
+
+```yaml
+input:
+  task_number: number
+  round_number: number
+  files_changed: [{path, action}]
+  context:
+    checkpoint_goal: string
+    round_requirements: string
+```
+
+## Output Contract
+
+```yaml
+output:
+  status: 'completed'
+  findings:
+    - category: 'navigation' | 'interaction' | 'feedback' | 'cognitive_load' | 'form_usability' | 'error_handling'
+      severity: 'critical' | 'warning' | 'suggestion'
+      file: string
+      issue: string
+      suggestion: string
+  files_changed:
+    - path: string
+      action: 'modified'
+      fix_for: string           # Which finding this fix addresses
+  summary:
+    total_issues: number
+    critical: number
+    warnings: number
+    suggestions: number
+    auto_fixed: number
+    out_of_scope_fixes: number  # Findings whose fix would have edited a file not in files_changed
+```
+
+The executor writes the output to `round.context.frontend_ux_review` and merges `files_changed` into the round's `files_changed` list.
+
+## Workflow
+
+### Phase 1: Read Changed Files
+
+Read all `.tsx` and page/layout files from `files_changed`. Identify components, pages, and interaction handlers.
+
+### Phase 2: Navigation Flow
+
+- Check page transitions and routing logic
+- Verify breadcrumbs, back navigation, and deep links
+- Check that navigation state is preserved across page changes
+- Verify loading states during navigation
+
+### Phase 2.5: Mobile Density Check
+
+For settings/configuration screens with multiple sections:
+
+1. **Scroll height vs viewport**: Estimate total content height. Flag if >3x viewport height
+2. **Compact layouts**: Verify list-type sections use chip rows, toggle rows, or horizontal selectors — not vertical block layouts
+3. **Conceptual clarity**: Check whether section groupings match user mental model (e.g., "schedule type" is clearer than separate "preferred days" + "time windows")
+4. **Touch targets**: Verify compact elements still meet minimum touch target (except when user explicitly requests smaller)
+
+Report findings under `cognitive_load` category with `warning` severity.
+
+### Phase 3: Interaction Patterns
+
+- Check click/touch target sizes (minimum 44x44px)
+- Verify drag-and-drop has proper visual feedback
+- Check hover states provide clear affordance
+- Verify interactive elements have cursor changes
+- Check that disabled states are visually distinct
+
+### Phase 4: User Feedback
+
+- Verify loading states exist for async operations
+- Check success/error messages after form submissions
+- Verify progress indicators for multi-step processes
+- Check that empty states have helpful messaging
+- Verify optimistic updates where appropriate
+
+### Phase 5: Cognitive Load
+
+- Check information density (not too much on screen)
+- Verify visual hierarchy guides the eye
+- Check that related items are grouped logically
+- Verify progressive disclosure for complex interfaces
+- Check that actions are clearly labeled
+
+### Phase 6: Form Usability
+
+- Check input labels and placeholders
+- Verify validation messages are clear and positioned near inputs
+- Check tab order is logical
+- Verify autofocus on primary input
+- Check that required fields are marked
+
+### Phase 7: Error Handling UX
+
+- Verify error messages are user-friendly (not technical)
+- Check recovery paths from error states
+- Verify network error handling (offline, timeout)
+- Check that errors do not lose user input
+
+### Phase 8: Aggregate Findings
+
+Categorize by severity:
+- **Critical**: Missing feedback states, broken navigation, lost user input
+- **Warning**: Suboptimal interaction patterns, unclear labels
+- **Suggestion**: Enhanced micro-interactions, better copy
+
+### Phase 9: Auto-Fix In-Scope Findings
+
+For every finding (critical, warning, and suggestion), apply the fix directly — but only when the file is in scope. The skill has Edit/Write capability via the executor's invocation; that capability requires a scope guard so the skill does not silently mutate files outside the round's contract (per `rules/workflow-discipline.md` "Agent Scope Boundary").
+
+#### Pre-Edit Scope Gate (MANDATORY)
+
+Before any Write/Edit:
+
+1. Build `allowed = new Set(input.files_changed.map(f => f.path))`.
+2. If the target path is in `allowed`, proceed to apply the fix.
+3. If the target path is NOT in `allowed`, do NOT edit. Instead:
+   - Emit the proposed fix as a `findings[]` entry with `severity: 'warning'` and a `suggestion` describing the change verbatim.
+   - Set `auto_fixed = false` for that finding.
+   - Increment `summary.out_of_scope_fixes`.
+
+This rule applies to every file. The skill's auto-fix surface exists because in-scope mechanical fixes are part of its value, not because it should rewrite anything it sees worth improving.
+
+**Specifically forbidden** (always out of scope, never edited regardless of `files_changed`):
+
+- `.claude/**` — managed infrastructure under user-level governance
+- Project test infrastructure (e.g., `playwright.config.*`, `e2e/**`) — governed by `test-e2e-agent`
+- DB migrations (e.g., `supabase/migrations/**`) — governed by `database-agent`
+- Vendor mirrors and read-only reference trees
+
+If a UX-relevant change is needed in a forbidden path, raise it as a finding only.
+
+#### In-Scope Auto-Fix Procedure
+
+For findings whose target file IS in `allowed`:
+
+1. Read the file at the reported location
+2. Apply the fix (e.g., add missing loading state, add error feedback, fix tab order, improve labels, add empty states, enhance interaction patterns)
+3. Track in `files_changed` with `fix_for` referencing the finding
+4. Set `auto_fixed = true` on the finding
+
+Go beyond fixing violations — actively improve user experience. If a form could have better validation feedback, add it. If a loading state is missing, add it. If labels are unclear, rewrite them. Deliver a comfortable, intuitive experience, not just a functional one.
+
+**Do not change** business logic or data flow — only UX patterns (feedback, states, labels, interactions). The scope gate enforces *where* you may edit; this rule enforces *what kind* of edit is allowed.
+
+## Completion Criteria
+
+- All changed page/component files reviewed
+- Navigation, interaction, feedback patterns checked
+- Critical/warning issues auto-fixed where possible (in-scope only)
+- Findings categorized by severity
+
+## Integration
+
+- **Loaded by**: `round-executor` Step 3.8 (mandatory when files_changed contains UI / interaction files)
+- **Output written to**: `round.context.frontend_ux_review`
+- **Paired with**: `frontend-design` (pre-implementation aesthetic), `frontend-ui` (visual self-review, also Step 3.8)

package/templates/skills/cbp-git-branch-feat-create/SKILL.md

@@ -0,0 +1,115 @@
+---
+scope: org-shared
+name: cbp-git-branch-feat-create
+description: Create feature branch from the production branch (main, config-driven)
+argument-hint: "[name] e.g. add-user-auth"
+effort: low
+---
+
+# Git Branch Feat Create
+
+Create a feature branch from the configured production branch (`main`).
+
+## Arguments
+
+`$ARGUMENTS`: [name] - branch name without type prefix
+
+Examples:
+- `add-user-auth` → creates `feat/add-user-auth`
+- `fix-login-bug` → creates `fix/fix-login-bug` (use fix prefix when fixing)
+
+## When to Use
+
+- Starting work on new feature
+- Triggered by `/cbp-checkpoint-create`
+- Manual use for ad-hoc features
+
+## Prerequisites
+
+- Repo must have the configured production branch (default `main`)
+- Working tree must be clean
+
+## Instructions
+
+### Step 1: Read Branch Config
+
+Read `.codebyplan/git.json` and extract `branch_config.production`:
+
+```
+BASE = branch_config.production (default: "main")
+```
+
+If `branch_config` is absent, fall back to `"main"`.
+
+### Step 2: Determine Repo Path
+
+The repo path is the current working directory root:
+
+```bash
+REPO_PATH="$(git rev-parse --show-toplevel)"
+```
+
+### Step 3: Verify Base Branch Exists
+
+Check the base branch is present (exact match — local or remote):
+
+```bash
+git rev-parse --verify "$BASE" >/dev/null 2>&1 || git ls-remote --exit-code --heads origin "$BASE" >/dev/null 2>&1
+```
+
+**If the base branch is missing:**
+```
+Base branch '$BASE' not found. Cannot create a feature branch.
+```
+Stop here.
+
+### Step 4: Verify Clean State
+
+```bash
+cd "$REPO_PATH" && git status --porcelain
+```
+
+**If uncommitted changes:**
+```
+Uncommitted changes exist. Commit your changes first.
+```
+Stop here.
+
+### Step 5: Create Branch
+
+```bash
+cd "$REPO_PATH" && git checkout "$BASE" && git checkout -b feat/$ARGUMENTS && git push -u origin feat/$ARGUMENTS
+```
+
+### Step 6: Show Result
+
+```
+## Branch Created
+
+**Branch**: feat/[name]
+**From**: [BASE]
+**Pushed**: origin/feat/[name]
+
+---
+
+Work on this branch. When done:
+- Commit with `/cbp-git-commit`
+- Ship via `/cbp-checkpoint-end` (feat → main, PR preview reviewed before merge)
+```
+
+## Branch Naming
+
+*Branch type conventions follow GitFlow:*
+
+| Type | When |
+|------|------|
+| `feat/` | New features (default) |
+| `fix/` | Bug fixes |
+| `chore/` | Maintenance |
+| `refactor/` | Restructuring |
+
+## Integration
+
+- **Triggered by**: `/cbp-checkpoint-create`
+- **Followed by**: `/cbp-checkpoint-end` (ships feat → main via PR preview)
+- **Config**: `branch_config.production` from `.codebyplan/git.json`