claude-code-workflow 7.2.27 → 7.2.28

package/.claude/skills/ship/phases/05-pr-creation.md

@@ -0,0 +1,163 @@
+# Phase 5: PR Creation
+
+Create a pull request via GitHub CLI with a structured body, linked issues, and release metadata.
+
+## Objective
+
+- Create a PR using `gh pr create` with structured body
+- Auto-link related issues from commit messages
+- Include release summary (version, changes, test plan)
+- Output the PR URL
+
+## Gate Condition
+
+PR created successfully and URL returned.
+
+## Execution Steps
+
+### Step 1: Extract Issue References from Commits
+
+```bash
+last_tag=$(git describe --tags --abbrev=0 2>/dev/null || echo "")
+
+if [ -n "$last_tag" ]; then
+  commits=$(git log "$last_tag"..HEAD --pretty=format:"%s" --no-merges)
+else
+  commits=$(git log --pretty=format:"%s" --no-merges -50)
+fi
+
+# Extract issue references: fixes #N, closes #N, resolves #N, refs #N
+issues=$(echo "$commits" | grep -oiE '(fix(es)?|close[sd]?|resolve[sd]?|refs?)\s*#[0-9]+' | grep -oE '#[0-9]+' | sort -u || true)
+
+echo "Referenced issues: $issues"
+```
+
+### Step 2: Determine Target Branch
+
+```bash
+# Default target: main (fallback: master)
+target_branch="main"
+if ! git rev-parse --verify "origin/$target_branch" &>/dev/null; then
+  target_branch="master"
+fi
+
+current_branch=$(git branch --show-current)
+echo "PR: $current_branch -> $target_branch"
+```
+
+### Step 3: Build PR Title
+
+Format: `release: vX.Y.Z`
+
+```bash
+pr_title="release: v${new_version}"
+```
+
+If the version context is not available, fall back to a descriptive title from the branch name.
+
+### Step 4: Build PR Body
+
+Construct the PR body using a HEREDOC for correct formatting:
+
+```bash
+# Gather change summary
+change_summary=$(git log "$merge_base"..HEAD --pretty=format:"- %s (%h)" --no-merges)
+
+# Build linked issues section
+if [ -n "$issues" ]; then
+  issues_section="## Linked Issues
+$(echo "$issues" | while read -r issue; do echo "- $issue"; done)"
+else
+  issues_section=""
+fi
+```
+
+### Step 5: Create PR via gh CLI
+
+```bash
+gh pr create --title "$pr_title" --base "$target_branch" --body "$(cat <<'EOF'
+## Summary
+Release vX.Y.Z
+
+### Changes
+- list of changes from changelog
+
+## Linked Issues
+- #N (fixes)
+- #M (closes)
+
+## Version
+- Previous: X.Y.Z-1
+- New: X.Y.Z
+- Bump type: patch|minor|major
+
+## Test Plan
+- [ ] Pre-flight checks passed (git clean, branch, tests, build)
+- [ ] AI code review completed with no critical issues
+- [ ] Version bump verified in version file
+- [ ] Changelog updated with all changes since last release
+- [ ] Release commit pushed successfully
+
+Generated with [Claude Code](https://claude.com/claude-code)
+EOF
+)"
+```
+
+**PR body sections**:
+
+| Section | Content |
+|---------|---------|
+| **Summary** | Version being released, one-line description |
+| **Changes** | Grouped changelog entries (from Phase 4) |
+| **Linked Issues** | Auto-extracted `fixes #N`, `closes #N` references |
+| **Version** | Previous version, new version, bump type |
+| **Test Plan** | Checklist confirming all phases passed |
+
+### Step 6: Capture and Report PR URL
+
+```bash
+# gh pr create outputs the PR URL on success
+pr_url=$(gh pr create ... 2>&1 | tail -1)
+echo "PR created: $pr_url"
+```
+
+## Output
+
+- **Format**: PR creation record
+- **Structure**:
+
+```json
+{
+  "phase": "pr-creation",
+  "pr_url": "https://github.com/owner/repo/pull/N",
+  "pr_title": "release: vX.Y.Z",
+  "target_branch": "main",
+  "source_branch": "feature-branch",
+  "linked_issues": ["#1", "#2"],
+  "overall": "pass|fail"
+}
+```
+
+## Completion
+
+After PR creation, output the final Completion Status:
+
+```
+## STATUS: DONE
+
+**Summary**: Released vX.Y.Z — PR created at {pr_url}
+
+### Details
+- Phases completed: 5/5
+- Version: {previous} -> {new} ({bump_type})
+- PR: {pr_url}
+- Key outputs: CHANGELOG.md updated, release commit pushed, PR created
+
+### Outputs
+- CHANGELOG.md (updated)
+- {version_file} (version bumped)
+- Release commit: {sha}
+- PR: {pr_url}
+```
+
+If there were review warnings, use `DONE_WITH_CONCERNS` and list the warnings in the Details section.

package/.claude/skills/skill-generator/templates/sequential-phase.md

@@ -80,6 +80,11 @@ Generate Phase files for Sequential execution mode, defining fixed-order executi
 
 {{quality_checklist}}
 
+## Completion Status
+
+Return one of: DONE | DONE_WITH_CONCERNS | BLOCKED | NEEDS_CONTEXT with structured reason.
+See [Completion Status Protocol](./../_shared/SKILL-DESIGN-SPEC.md#13) for output format.
+
 ## Next Phase
 
 {{next_phase_link}}
@@ -456,6 +461,11 @@ Write(\`${workDir}/${phaseConfig.output}\`, JSON.stringify(result, null, 2));
 - [ ] Core logic executed successfully
 - [ ] Output format correct
 
+## Completion Status
+
+Return one of: DONE | DONE_WITH_CONCERNS | BLOCKED | NEEDS_CONTEXT with structured reason.
+See [Completion Status Protocol](./../_shared/SKILL-DESIGN-SPEC.md#13) for output format.
+
 ${nextPhase ?
   `## Next Phase\n\n→ [Phase ${index + 2}: ${nextPhase.name}](${nextPhase.id}.md)` :
   '## Completion\n\nThis is the final phase.'}

package/.claude/skills/skill-generator/templates/skill-md.md

@@ -80,6 +80,10 @@ Bash(\`mkdir -p "\${workDir}"\`);
 {{output_structure}}
 \`\`\`
 
+## Completion Protocol
+
+Follow [Completion Status Protocol](./../_shared/SKILL-DESIGN-SPEC.md#13) and [Escalation Protocol](./../_shared/SKILL-DESIGN-SPEC.md#14).
+
 ## Reference Documents by Phase
 
 > **Important**: Reference documents should be organized by execution phase, clearly marking when and in what scenarios they are used. Avoid listing documents in a flat manner.

package/.claude/skills/team-interactive-craft/SKILL.md

@@ -0,0 +1,127 @@
+---
+name: team-interactive-craft
+description: Unified team skill for interactive component crafting. Vanilla JS + CSS interactive components with zero dependencies. Research -> interaction design -> build -> a11y test. Uses team-worker agent architecture. Triggers on "team interactive craft", "interactive component".
+allowed-tools: Agent, AskUserQuestion, Read, Write, Edit, Bash, Glob, Grep, TaskList, TaskGet, TaskUpdate, TaskCreate, TeamCreate, TeamDelete, SendMessage, mcp__ccw-tools__read_file, mcp__ccw-tools__write_file, mcp__ccw-tools__edit_file, mcp__ccw-tools__team_msg
+---
+
+# Team Interactive Craft
+
+Systematic interactive component pipeline: research -> interaction design -> build -> a11y test. Built on **team-worker agent architecture** -- all worker roles share a single agent definition with role-specific Phase 2-4 loaded from `roles/<role>/role.md`.
+
+## Architecture
+
+```
+Skill(skill="team-interactive-craft", args="task description")
+                    |
+         SKILL.md (this file) = Router
+                    |
+     +--------------+--------------+
+     |                             |
+  no --role flag              --role <name>
+     |                             |
+  Coordinator                  Worker
+  roles/coordinator/role.md    roles/<name>/role.md
+     |
+     +-- analyze -> dispatch -> spawn workers -> STOP
+                                    |
+                    +-------+-------+-------+-------+
+                    v       v       v       v
+           [team-worker agents, each loads roles/<role>/role.md]
+        researcher  interaction-designer  builder  a11y-tester
+```
+
+## Role Registry
+
+| Role | Path | Prefix | Inner Loop |
+|------|------|--------|------------|
+| coordinator | [roles/coordinator/role.md](roles/coordinator/role.md) | -- | -- |
+| researcher | [roles/researcher/role.md](roles/researcher/role.md) | RESEARCH-* | false |
+| interaction-designer | [roles/interaction-designer/role.md](roles/interaction-designer/role.md) | INTERACT-* | false |
+| builder | [roles/builder/role.md](roles/builder/role.md) | BUILD-* | true |
+| a11y-tester | [roles/a11y-tester/role.md](roles/a11y-tester/role.md) | A11Y-* | false |
+
+## Role Router
+
+Parse `$ARGUMENTS`:
+- Has `--role <name>` -> Read `roles/<name>/role.md`, execute Phase 2-4
+- No `--role` -> `@roles/coordinator/role.md`, execute entry router
+
+## Shared Constants
+
+- **Session prefix**: `IC`
+- **Session path**: `.workflow/.team/IC-<slug>-<date>/`
+- **CLI tools**: `ccw cli --mode analysis` (read-only), `ccw cli --mode write` (modifications)
+- **Message bus**: `mcp__ccw-tools__team_msg(session_id=<session-id>, ...)`
+- **Max GC rounds**: 2
+
+## Worker Spawn Template
+
+Coordinator spawns workers using this template:
+
+```
+Agent({
+  subagent_type: "team-worker",
+  description: "Spawn <role> worker for <task-id>",
+  team_name: "interactive-craft",
+  name: "<role>",
+  run_in_background: true,
+  prompt: `## Role Assignment
+role: <role>
+role_spec: <skill_root>/roles/<role>/role.md
+session: <session-folder>
+session_id: <session-id>
+team_name: interactive-craft
+requirement: <task-description>
+inner_loop: <true|false>
+
+Read role_spec file (@<skill_root>/roles/<role>/role.md) to load Phase 2-4 domain instructions.
+Execute built-in Phase 1 (task discovery) -> role Phase 2-4 -> built-in Phase 5 (report).`
+})
+```
+
+## User Commands
+
+| Command | Action |
+|---------|--------|
+| `check` / `status` | View execution status graph |
+| `resume` / `continue` | Advance to next step |
+
+## Specs Reference
+
+- [specs/pipelines.md](specs/pipelines.md) -- Pipeline definitions and task registry
+- [specs/interaction-patterns.md](specs/interaction-patterns.md) -- Interaction pattern catalog
+- [specs/vanilla-constraints.md](specs/vanilla-constraints.md) -- Zero-dependency rules
+
+## Session Directory
+
+```
+.workflow/.team/IC-<slug>-<date>/
++-- .msg/
+|   +-- messages.jsonl         # Team message bus
+|   +-- meta.json              # Pipeline config + GC state
++-- research/                  # Researcher output
+|   +-- interaction-inventory.json
+|   +-- browser-api-audit.json
+|   +-- pattern-reference.json
++-- interaction/               # Interaction designer output
+|   +-- blueprints/
+|       +-- {component-name}.md
++-- build/                     # Builder output
+|   +-- components/
+|       +-- {name}.js
+|       +-- {name}.css
++-- a11y/                      # A11y tester output
+|   +-- a11y-audit-{NNN}.md
++-- wisdom/                    # Cross-task knowledge
+```
+
+## Error Handling
+
+| Scenario | Resolution |
+|----------|------------|
+| Unknown command | Error with available command list |
+| Role not found | Error with role registry |
+| Session corruption | Attempt recovery, fallback to manual |
+| Fast-advance conflict | Coordinator reconciles on next callback |
+| Completion action fails | Default to Keep Active |
+| GC loop stuck > 2 rounds | Escalate to user: accept / retry / terminate |

package/.claude/skills/team-interactive-craft/roles/a11y-tester/role.md

@@ -0,0 +1,159 @@
+---
+role: a11y-tester
+prefix: A11Y
+inner_loop: false
+message_types: [state_update]
+---
+
+# Accessibility Tester
+
+Test interactive components for keyboard navigation, screen reader compatibility, reduced motion fallback, focus management, and color contrast. Act as Critic in the builder<->a11y-tester Generator-Critic loop. Serve as quality gate before pipeline completion.
+
+## Phase 2: Context & Artifact Loading
+
+| Input | Source | Required |
+|-------|--------|----------|
+| Built components | <session>/build/components/*.js, *.css | Yes |
+| Interaction blueprints | <session>/interaction/blueprints/*.md | Yes |
+| Research artifacts | <session>/research/browser-api-audit.json | No |
+| Previous audits | <session>/a11y/a11y-audit-*.md | Only for GC re-audit |
+| .msg/meta.json | <session>/wisdom/.msg/meta.json | Yes |
+
+1. Extract session path from task description
+2. Read all built component files (JS + CSS)
+3. Read interaction blueprints for expected behavior reference
+4. If GC re-audit: read previous audit to track improvement/regression
+5. Load audit history from meta.json for trend analysis
+
+## Phase 3: Audit Execution
+
+Test 5 accessibility dimensions. For each, evaluate every built component:
+
+### Dimension 1: Keyboard Navigation (Weight: 25%)
+
+| Check | Method | Pass Criteria |
+|-------|--------|---------------|
+| Tab order | Scan tabindex values, focusable elements | Logical tab order, no tabindex > 0 |
+| Arrow key navigation | Check onKeyDown for ArrowLeft/Right/Up/Down | All navigable items reachable via arrows |
+| Enter/Space activation | Check onKeyDown for Enter, Space | All interactive elements activatable |
+| Escape dismissal | Check onKeyDown for Escape | Overlays/modals dismiss on Escape |
+| Focus trap (overlays) | Check focus cycling logic | Tab stays within overlay when open |
+| No keyboard trap | Verify all states have keyboard exit | Can always Tab/Escape out of component |
+
+Score: count(pass) / count(total_checks) * 10
+
+### Dimension 2: Screen Reader Compatibility (Weight: 25%)
+
+| Check | Method | Pass Criteria |
+|-------|--------|---------------|
+| ARIA role | Scan for role attribute | Appropriate role set (slider, dialog, tablist, etc.) |
+| ARIA label | Scan for aria-label, aria-labelledby | All interactive elements have accessible name |
+| ARIA states | Scan for aria-expanded, aria-selected, aria-hidden | Dynamic states update with interaction |
+| Live regions | Scan for aria-live, aria-atomic | State changes announced (polite/assertive as needed) |
+| Semantic HTML | Check element types | Uses button/a/input where appropriate, not div-only |
+| Alt text | Check img/svg elements | Decorative: aria-hidden; informative: alt/aria-label |
+
+Score: count(pass) / count(total_checks) * 10
+
+### Dimension 3: Reduced Motion (Weight: 20%)
+
+| Check | Method | Pass Criteria |
+|-------|--------|---------------|
+| Media query present | Search CSS for prefers-reduced-motion | @media (prefers-reduced-motion: reduce) exists |
+| Transitions disabled | Check reduced-motion block | transition-duration near 0 or removed |
+| Animations disabled | Check reduced-motion block | animation-duration near 0 or removed |
+| Content still accessible | Verify no content depends on animation | Information conveyed without motion |
+| JS respects preference | Check matchMedia usage | JS checks prefers-reduced-motion before animating |
+
+Score: count(pass) / count(total_checks) * 10
+
+### Dimension 4: Focus Management (Weight: 20%)
+
+| Check | Method | Pass Criteria |
+|-------|--------|---------------|
+| Visible focus indicator | Search CSS for :focus-visible | Visible outline/ring on keyboard focus |
+| Focus contrast | Check outline color against background | >= 3:1 contrast ratio |
+| Focus on open | Check overlay/modal open logic | Focus moves to first interactive element |
+| Focus on close | Check overlay/modal close logic | Focus returns to trigger element |
+| No focus loss | Check state transitions | Focus never moves to non-interactive element |
+| Skip link (page mode) | Check for skip navigation | Present if multiple interactive sections |
+
+Score: count(pass) / count(total_checks) * 10
+
+### Dimension 5: Color Contrast (Weight: 10%)
+
+| Check | Method | Pass Criteria |
+|-------|--------|---------------|
+| Text contrast | Evaluate CSS color vs background | >= 4.5:1 for normal text, >= 3:1 for large text |
+| UI component contrast | Evaluate interactive element borders/fills | >= 3:1 against adjacent colors |
+| Focus indicator contrast | Evaluate outline color | >= 3:1 against background |
+| State indication | Check non-color state indicators | State not conveyed by color alone |
+
+Score: count(pass) / count(total_checks) * 10
+
+### Overall Score Calculation
+
+`overallScore = round(keyboard*0.25 + screenReader*0.25 + reducedMotion*0.20 + focus*0.20 + contrast*0.10)`
+
+### Issue Classification
+
+| Severity | Definition | Examples |
+|----------|-----------|----------|
+| Critical | Component unusable for assistive tech users | No keyboard access, no ARIA role, focus trap |
+| High | Significant barrier, workaround exists | Missing aria-label, no reduced motion, poor focus |
+| Medium | Minor inconvenience | Suboptimal tab order, missing live region |
+| Low | Enhancement opportunity | Could improve contrast, better semantic HTML |
+
+### Signal Determination
+
+| Condition | Signal |
+|-----------|--------|
+| 0 critical AND 0 high issues | `a11y_passed` (GC CONVERGED) |
+| 0 critical AND high_count > 0 | `a11y_result` (GC REVISION NEEDED) |
+| critical_count > 0 | `fix_required` (CRITICAL FIX NEEDED) |
+
+## Phase 4: Report & Output
+
+1. Write audit report to `<session>/a11y/a11y-audit-{NNN}.md`:
+
+```markdown
+# A11y Audit Report - {NNN}
+
+## Summary
+- **Overall Score**: X/10
+- **Signal**: a11y_passed | a11y_result | fix_required
+- **Critical**: N | **High**: N | **Medium**: N | **Low**: N
+
+## Dimension Scores
+
+| Dimension | Score | Weight | Weighted |
+|-----------|-------|--------|----------|
+| Keyboard Navigation | X/10 | 25% | X.XX |
+| Screen Reader | X/10 | 25% | X.XX |
+| Reduced Motion | X/10 | 20% | X.XX |
+| Focus Management | X/10 | 20% | X.XX |
+| Color Contrast | X/10 | 10% | X.XX |
+
+## Issues
+
+### Critical
+- [C-001] {description} | File: {file}:{line} | Fix: {remediation}
+
+### High
+- [H-001] {description} | File: {file}:{line} | Fix: {remediation}
+
+### Medium
+- [M-001] {description} | File: {file}:{line} | Fix: {remediation}
+
+## GC Loop Status
+- **Signal**: {signal}
+- **Action Required**: {none | builder fix | escalate}
+
+## Trend (if previous audit exists)
+- Previous score: X/10 -> Current: X/10 ({improving|stable|declining})
+- Resolved issues: [list]
+- New issues: [list]
+```
+
+2. Update `<session>/wisdom/.msg/meta.json` under `a11y-tester` namespace:
+   - Read existing -> merge `{ "a11y-tester": { audit_id, score, critical_count, high_count, signal, timestamp } }` -> write back