codebyplan 1.5.1 → 1.8.0

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`

package/templates/skills/cbp-git-commit/SKILL.md

@@ -0,0 +1,278 @@
+---
+scope: org-shared
+name: cbp-git-commit
+description: Create scoped commit with conventional format
+argument-hint: "[--task|--all] [type]: [description]"
+effort: low
+---
+
+# Git Commit Command
+
+Create a commit using conventional commits format, then push to origin.
+
+## When to Use
+
+- Called by `/cbp-session-end` after files are staged
+- Direct use when user provides explicit commit message
+
+## Arguments
+
+`$ARGUMENTS`: [options] [type]: [description]
+
+**Scope Flags (one optional):**
+- `--task` - Commit all staged files (semantic: task context)
+- `--all` - Commit all staged files (explicit, same as no scope flag)
+- `--scope-task` - Commit ONLY files in the active task's `files_changed[]` (intersected with currently-staged files); leaves foreign-staged files alone
+
+**Other Options:**
+- `--files [file1] [file2] ...` - **Manual override**: commit ONLY these specific files
+- `--no-push` - Skip push to remote
+
+**Scope Flag Behavior:**
+
+| Flag | File Source | Use Case |
+|------|-------------|----------|
+| `--task` | All staged files | `/cbp-task-complete` |
+| `--all` | All staged files | Explicit full commit |
+| `--scope-task` | Intersection of `task.files_changed[].path` and `git diff --cached --name-only` | Foreign-staged files exist alongside task work; user wants to commit only the task's files in this commit |
+| (none) | All staged files | Default behavior |
+
+When a scope flag is used:
+- All staged files are committed (except `--scope-task`, which intersects with task files)
+- Semantic distinction only (for context in calling commands)
+
+**`--scope-task` Behavior:**
+
+When `--scope-task` is used:
+1. Read `task.files_changed[].path` via MCP `get_current_task`
+2. Read currently-staged files via `git diff --cached --name-only`
+3. Compute intersection — only those paths are committed
+4. Foreign-staged files (in staged set but NOT in task) remain staged after the commit; user handles them in a separate commit
+5. If intersection is empty → error "No staged files belong to TASK-N. Either use --all to commit foreign-staged files, or stage task files first."
+
+This is the right scope flag when `git status` shows foreign-staged batches alongside task work (e.g., a parallel `.claude/` sync staged simultaneously with TASK-N's work) and the commit narrative belongs to the task only.
+
+**Manual Override: --files**
+
+When `--files` is used (overrides scope flags):
+- Only the specified files are committed
+- Other staged files remain staged (not committed)
+- Specified files MUST be staged, otherwise error
+- This enables manual control when scoped flags don't fit
+
+**Message formats:**
+- `[type]: [description]`
+- `[type](scope): [description]`
+
+**Examples:**
+- `feat: add user authentication` - Commit all staged, auto-push
+- `--task feat(CHK-022): complete TASK-1` - Commit all staged in task context
+- `--all fix(api): resolve timeout` - Explicit all-staged commit
+- `--files path/to/file.md feat: add feature` - Manual specific file
+- `--no-push chore: update deps` - Commit without pushing
+
+If no message provided, analyze staged changes and generate message automatically.
+
+## Instructions
+
+### Step 1: Determine Repo Path
+
+**CRITICAL**: The shell working directory may not match the session's repo.
+
+Determine repo path from session context:
+
+The repo path is the current working directory root:
+
+```bash
+REPO_PATH="$(git rev-parse --show-toplevel)"
+```
+
+### Step 2: Parse Scope and Options
+
+**Parse `$ARGUMENTS` for flags:**
+
+1. **Check for scope flag** (mutually exclusive):
+   - `--task` -> scope = "task" (commits all staged)
+   - `--all` -> scope = "all"
+   - `--scope-task` -> scope = "scope-task" (intersection of task.files_changed[] and staged)
+   - (none) -> scope = "all" (default)
+
+2. **Check for --files** (overrides scope):
+   - If `--files` present -> use manual file list, ignore scope
+
+3. **Check for --no-push**
+
+4. **Extract commit message** (remaining arguments after flags)
+
+### Step 2a: Collect Files (if --files or --scope-task used)
+
+**If `--files` provided:** Use the manual file list.
+
+**If `--scope-task`:** Resolve via MCP + intersection.
+
+```bash
+# 1. Read task.files_changed[]
+task_paths=$(mcp get_current_task | jq -r '.files_changed[].path')
+# 2. Read staged paths
+staged_paths=$(git diff --cached --name-only)
+# 3. Compute intersection
+intersect=$(comm -12 <(echo "$task_paths" | sort) <(echo "$staged_paths" | sort))
+```
+
+If `intersect` is empty: emit error and STOP.
+
+```
+## Error: No Task Files Staged
+
+Scope: --scope-task
+TASK-N has [M] files in files_changed[]; none are currently staged.
+
+Options:
+- Stage task files: git add [path1] [path2] ...
+- Or use --all to commit the foreign-staged files instead.
+```
+
+If non-empty: use `intersect` as the file list for Step 5.
+
+**If `--task`, `--all`, or no scope:** No filtering — all staged files committed.
+
+### Step 3: Check Staged Changes
+
+```bash
+cd "$REPO_PATH" && git diff --cached --name-only
+```
+
+**If nothing staged:**
+- Show "No changes to commit."
+- Stop here.
+
+### Step 4: Analyze Changes (if no message)
+
+If no commit message provided:
+1. Read staged file diffs
+2. Determine commit type:
+   - New files with features -> `feat`
+   - Bug fixes -> `fix`
+   - Config/deps changes -> `chore`
+   - Documentation -> `docs`
+   - Refactoring -> `refactor`
+3. Generate message automatically
+
+### Step 4a: Verify Manual Files Are Staged
+
+**If `--files`:** Verify each specified file is staged.
+
+```bash
+cd "$REPO_PATH" && git diff --cached --name-only
+```
+
+**If any specified files not staged:** Show error with missing files list and STOP.
+
+**If `--task`, `--all`, or no scope:** Skip verification, use all staged.
+
+### Step 5: Create Commit
+
+**For `--scope-task`:** commit only the intersection list from Step 2a:
+
+```bash
+cd "$REPO_PATH" && git commit [intersect-file1] [intersect-file2] ... -m "$(cat <<'EOF'
+[type]: [description]
+EOF
+)"
+```
+
+Foreign-staged files remain in the index (not committed). The commit attribution covers only TASK-N's files.
+
+**Determine commit mode:**
+
+| Scope | Commit Command |
+|-------|----------------|
+| `--files [list]` | `git commit [file1] [file2] ...` |
+| `--task` | `git commit` (all staged) |
+| `--all` or (none) | `git commit` (all staged) |
+
+**If --files (manual file list):**
+
+Commit ONLY the specified files:
+
+```bash
+cd "$REPO_PATH" && git commit [file1] [file2] ... -m "$(cat <<'EOF'
+[type]: [description]
+EOF
+)"
+```
+
+**If --task, --all, or no scope (commit all staged):**
+
+```bash
+cd "$REPO_PATH" && git commit -m "$(cat <<'EOF'
+[type]: [description]
+EOF
+)"
+```
+
+### Step 6: Push to Remote
+
+**If `--no-push` option provided:**
+- Skip this step
+- Show "Push skipped (--no-push)"
+
+**Otherwise:** push the current branch to origin.
+
+```bash
+cd "$REPO_PATH" && BRANCH=$(git rev-parse --abbrev-ref HEAD) && git push origin "$BRANCH"
+```
+
+**If push fails with "no upstream":** retry with `-u`.
+
+```bash
+cd "$REPO_PATH" && git push -u origin "$BRANCH"
+```
+
+**If push fails because remote is ahead:** report to user and stop — do not auto-pull. User resolves by running `git pull --rebase origin "$BRANCH"` and retrying.
+
+### Step 7: Show Result
+
+Display output per Output Format section below.
+
+## Output Format
+
+**Standard commit (all staged):**
+```
+**Committed**: [short-hash]
+**Message**: [type]: [description]
+**Scope**: [--task / --all / --files]
+**Files**: N files changed
+**Pushed**: origin/[branch-name]
+```
+
+**If no changes to commit:**
+```
+No changes to commit.
+```
+
+**If manual files not staged:**
+```
+## Error: Files Not Staged
+
+Scope: --files
+Missing: [N] files not staged
+
+Stage the missing files or use --all.
+```
+
+## Integration
+
+- **Called by**: `/cbp-session-end`, `/cbp-task-complete`, `/cbp-checkpoint-complete`, manual
+- **Scope usage by commands**:
+  - `/cbp-task-complete` -> `--no-push` (commit all staged)
+  - `/cbp-checkpoint-complete` -> no scope needed
+  - `/cbp-session-end` -> `--all` or no scope (commit all staged)
+- **Rules**: `/.claude/rules/git-workflow.md`
+
+## Key Points
+
+1. **Simplified scopes** - `--task` and `--all` both commit all staged files
+2. **Manual override** - `--files` takes precedence over scope flags
+3. **Verification** - Only `--files` needs staged verification
+4. **Default is --all** - No scope flag = commit all staged (backward compatible)