devflow-kit 0.8.1 → 1.0.0

package/shared/skills/accessibility/references/violations.md

@@ -0,0 +1,419 @@
+# Accessibility Violations
+
+Extended violation patterns for accessibility reviews. Reference from main SKILL.md.
+
+## Keyboard Navigation Violations
+
+### No Keyboard Access
+
+```tsx
+// VIOLATION: onClick without keyboard equivalent
+<div onClick={handleClick} className="card">
+  Click me
+</div>
+
+// VIOLATION: Custom element not focusable
+<span className="link" onClick={() => navigate('/page')}>
+  Go to page
+</span>
+
+// VIOLATION: Drag-only interaction
+<div
+  draggable
+  onDragStart={handleDrag}
+  onDragEnd={handleDrop}
+>
+  Drag me (no keyboard alternative)
+</div>
+```
+
+### Missing Focus Management
+
+```tsx
+// VIOLATION: Modal doesn't trap focus
+function Modal({ isOpen, children }) {
+  return isOpen ? (
+    <div className="modal-overlay">
+      <div className="modal-content">
+        {children}
+        <button onClick={onClose}>Close</button>
+      </div>
+    </div>
+  ) : null;
+}
+
+// VIOLATION: Dropdown doesn't return focus on close
+function Dropdown() {
+  const [isOpen, setIsOpen] = useState(false);
+
+  return (
+    <div>
+      <button onClick={() => setIsOpen(true)}>Open</button>
+      {isOpen && (
+        <ul>
+          <li onClick={() => setIsOpen(false)}>Option 1</li>
+          {/* Focus lost when dropdown closes */}
+        </ul>
+      )}
+    </div>
+  );
+}
+```
+
+### Poor Focus Visibility
+
+```css
+/* VIOLATION: Focus removed entirely */
+*:focus {
+  outline: none;
+}
+
+/* VIOLATION: Focus invisible on dark backgrounds */
+button:focus {
+  outline: 1px solid #333;
+}
+
+/* VIOLATION: Focus style same as hover */
+button:hover,
+button:focus {
+  background: #eee;
+}
+```
+
+### Illogical Tab Order
+
+```tsx
+// VIOLATION: tabIndex breaks natural order
+<div>
+  <input tabIndex={3} placeholder="Third" />
+  <input tabIndex={1} placeholder="First" />
+  <input tabIndex={2} placeholder="Second" />
+</div>
+
+// VIOLATION: Positive tabIndex on many elements
+<nav>
+  <a href="/" tabIndex={1}>Home</a>
+  <a href="/about" tabIndex={2}>About</a>
+  <a href="/contact" tabIndex={3}>Contact</a>
+</nav>
+```
+
+---
+
+## ARIA Violations
+
+### Missing Labels
+
+```tsx
+// VIOLATION: Icon button without accessible name
+<button onClick={handleClose}>
+  <CloseIcon />
+</button>
+
+// VIOLATION: Input without label
+<input type="text" placeholder="Search" />
+
+// VIOLATION: Image without alt
+<img src="/logo.png" />
+
+// VIOLATION: Link without text
+<a href="/profile">
+  <Avatar src={user.avatar} />
+</a>
+```
+
+### Incorrect ARIA Usage
+
+```tsx
+// VIOLATION: role="button" on already-button element
+<button role="button" onClick={handleClick}>Submit</button>
+
+// VIOLATION: aria-hidden on focusable element
+<button aria-hidden="true" onClick={handleClick}>
+  Hidden but focusable
+</button>
+
+// VIOLATION: Missing required ARIA attributes
+<div role="slider">
+  {/* Missing aria-valuenow, aria-valuemin, aria-valuemax */}
+</div>
+
+// VIOLATION: aria-label duplicating visible text
+<button aria-label="Submit form">Submit form</button>
+```
+
+### Overuse of ARIA
+
+```tsx
+// VIOLATION: ARIA where semantic HTML suffices
+<div role="navigation" aria-label="Main navigation">
+  <div role="list">
+    <div role="listitem">
+      <div role="link" onClick={() => navigate('/')}>Home</div>
+    </div>
+  </div>
+</div>
+
+// Should be:
+<nav aria-label="Main">
+  <ul>
+    <li><a href="/">Home</a></li>
+  </ul>
+</nav>
+```
+
+---
+
+## Color and Contrast Violations
+
+### Insufficient Contrast
+
+```css
+/* VIOLATION: Light gray on white (1.5:1 ratio) */
+.muted-text {
+  color: #aaa;
+  background: #fff;
+}
+
+/* VIOLATION: Placeholder text too light */
+input::placeholder {
+  color: #ccc;
+}
+
+/* VIOLATION: Disabled state invisible */
+button:disabled {
+  color: #eee;
+  background: #f5f5f5;
+}
+```
+
+### Color-Only Information
+
+```tsx
+// VIOLATION: Status only indicated by color
+<span style={{ color: status === 'error' ? 'red' : 'green' }}>
+  {status}
+</span>
+
+// VIOLATION: Required fields only marked red
+<label style={{ color: required ? 'red' : 'inherit' }}>
+  {label}
+</label>
+
+// VIOLATION: Chart using only color to differentiate data
+<LineChart>
+  <Line stroke="red" data={series1} />
+  <Line stroke="blue" data={series2} />
+  {/* No pattern, icon, or label differentiation */}
+</LineChart>
+```
+
+---
+
+## Form Violations
+
+### Missing Error Association
+
+```tsx
+// VIOLATION: Error not associated with input
+<div>
+  <input id="email" type="email" />
+  {error && <span className="error">{error}</span>}
+</div>
+
+// VIOLATION: Error not announced to screen readers
+<div>
+  <input aria-invalid={!!error} />
+  {error && <div className="error-message">{error}</div>}
+</div>
+```
+
+### Placeholder as Label
+
+```tsx
+// VIOLATION: Placeholder disappears, no persistent label
+<input placeholder="Email address" />
+
+// VIOLATION: Floating label without visible label initially
+function FloatingInput({ label }) {
+  const [value, setValue] = useState('');
+  return (
+    <div>
+      <input
+        value={value}
+        onChange={(e) => setValue(e.target.value)}
+      />
+      <label className={value ? 'floating' : 'hidden'}>{label}</label>
+    </div>
+  );
+}
+```
+
+### Form Not Keyboard Navigable
+
+```tsx
+// VIOLATION: Custom select not keyboard accessible
+function CustomSelect({ options, value, onChange }) {
+  const [isOpen, setIsOpen] = useState(false);
+
+  return (
+    <div className="select" onClick={() => setIsOpen(!isOpen)}>
+      <span>{value}</span>
+      {isOpen && (
+        <ul className="options">
+          {options.map(opt => (
+            <li onClick={() => onChange(opt)}>{opt}</li>
+          ))}
+        </ul>
+      )}
+    </div>
+  );
+}
+```
+
+---
+
+## Motion and Animation Violations
+
+### No Reduced Motion Support
+
+```css
+/* VIOLATION: Animation ignores user preference */
+.hero {
+  animation: slideIn 1s ease-in-out;
+}
+
+@keyframes slideIn {
+  from { transform: translateY(100%); }
+  to { transform: translateY(0); }
+}
+```
+
+### Autoplay Without Pause
+
+```tsx
+// VIOLATION: Video autoplays without pause control
+<video autoPlay loop muted>
+  <source src="/background.mp4" />
+</video>
+
+// VIOLATION: Carousel auto-advances without pause
+function Carousel({ slides }) {
+  useEffect(() => {
+    const interval = setInterval(nextSlide, 3000);
+    return () => clearInterval(interval);
+  }, []);
+  // No pause on hover or focus
+}
+```
+
+### Flashing Content
+
+```css
+/* VIOLATION: Flash rate > 3 per second */
+@keyframes flash {
+  0%, 100% { opacity: 1; }
+  50% { opacity: 0; }
+}
+.alert {
+  animation: flash 0.2s infinite;
+}
+```
+
+---
+
+## Touch Target Violations
+
+### Small Touch Targets
+
+```css
+/* VIOLATION: Icon buttons too small */
+.icon-btn {
+  width: 24px;
+  height: 24px;
+  padding: 4px;
+}
+
+/* VIOLATION: Inline links with no padding */
+.inline-link {
+  /* Natural text height only */
+}
+
+/* VIOLATION: Close button in corner */
+.modal-close {
+  position: absolute;
+  top: 4px;
+  right: 4px;
+  width: 16px;
+  height: 16px;
+}
+```
+
+### Targets Too Close Together
+
+```tsx
+// VIOLATION: Adjacent small targets
+<div className="button-group">
+  <button className="icon-btn">A</button>
+  <button className="icon-btn">B</button>
+  <button className="icon-btn">C</button>
+  {/* No spacing between 24px buttons */}
+</div>
+```
+
+---
+
+## Screen Reader Violations
+
+### Hidden Important Content
+
+```tsx
+// VIOLATION: Visually hidden but important content
+<span className="sr-only">
+  Loading... {/* Never announced because sr-only wrong implementation */}
+</span>
+
+// VIOLATION: aria-hidden on important element
+<main aria-hidden="true">
+  {/* Page content hidden from AT */}
+</main>
+```
+
+### Meaningless Link Text
+
+```tsx
+// VIOLATION: Generic link text
+<p>
+  To learn more about our services, <a href="/services">click here</a>.
+</p>
+
+// VIOLATION: Repeated "Read more" links
+{posts.map(post => (
+  <article>
+    <h2>{post.title}</h2>
+    <p>{post.excerpt}</p>
+    <a href={post.url}>Read more</a>
+  </article>
+))}
+```
+
+### Missing Page Structure
+
+```tsx
+// VIOLATION: No landmark regions
+function App() {
+  return (
+    <div>
+      <div className="header">...</div>
+      <div className="sidebar">...</div>
+      <div className="content">...</div>
+      <div className="footer">...</div>
+    </div>
+  );
+}
+
+// VIOLATION: Skipped heading levels
+<h1>Page Title</h1>
+<h3>Section</h3>  {/* h2 skipped */}
+<h5>Subsection</h5>  {/* h4 skipped */}
+```

package/shared/skills/agent-teams/SKILL.md

@@ -0,0 +1,124 @@
+---
+name: agent-teams
+description: This skill should be used when the user asks to "create an agent team", "spawn teammates", "set up debate protocol", "coordinate agents", or discusses peer-to-peer agent collaboration, consensus formation, or team-based workflows. Provides patterns for team spawning, message passing, adversarial debate, and quality gates driven by multi-agent consensus.
+user-invocable: false
+allowed-tools: Read, Grep, Glob
+---
+
+# Agent Teams Patterns
+
+Patterns for collaborative multi-agent workflows using Claude Code's Agent Teams feature. Teams enable peer-to-peer communication between agents, replacing one-way subagent reporting with adversarial debate and consensus.
+
+## Iron Law
+
+> **TEAMMATES CHALLENGE EACH OTHER**
+>
+> Every finding must survive peer scrutiny. No unchallenged claims reach the final
+> report. A single agent's opinion is a hypothesis; consensus from debate is a finding.
+
+---
+
+## When This Activates
+
+- Creating agent teams for review, implementation, or debugging
+- Spawning teammates with distinct perspectives
+- Coordinating multi-agent debate rounds
+- Forming consensus from conflicting findings
+
+## Core Patterns
+
+### Team Spawning
+
+Size team to task complexity. Assign distinct, non-overlapping perspectives.
+
+| Task Complexity | Team Size | Rationale |
+|----------------|-----------|-----------|
+| Simple review | 2-3 | Security + architecture sufficient |
+| Full review | 4-5 | Core perspectives covered |
+| Debug investigation | 3-5 | One per hypothesis |
+| Implementation | 2-4 | Domain-separated work units |
+| Specification | 3-4 | Debate requirements before user gates |
+| Resolution | 2-4 | Cross-validate fixes across batches |
+
+**Model guidance**: Explorers/Reviewers inherit parent model. Validators use `model: haiku`.
+
+### Detection and Fallback
+
+Attempt `TeamCreate`. If it fails or the tool is unavailable, fall back to parallel subagents:
+
+```
+try TeamCreate → success → proceed with team workflow
+                → failure → fall back to parallel Task() calls
+```
+
+Always document which mode was used in the final report.
+
+### Task List Coordination
+
+Use `TaskCreate` to give each teammate a trackable work unit. Lead checks `TaskList` for structured progress visibility beyond ad-hoc messages:
+
+```
+1. Lead creates tasks for each teammate's work unit
+2. Teammates claim tasks via TaskUpdate (owner: self)
+3. Teammates mark tasks completed when done
+4. Lead checks TaskList before proceeding to next phase
+```
+
+### Challenge Protocol
+
+1. **Initial work**: Each teammate completes independent analysis
+2. **Exchange**: Lead broadcasts "Share findings and challenge others"
+3. **Direct debate**: Teammates message each other with evidence
+4. **Resolution**: Contradictions resolved through 1-2 exchanges
+5. **Escalation**: Unresolved after 2 exchanges → report disagreement to lead
+
+### Consensus Formation
+
+| Agreement Level | Confidence | Report As |
+|----------------|------------|-----------|
+| Unanimous | HIGH | Confirmed finding |
+| Majority (>50%) | MEDIUM | Finding with noted dissent |
+| Split (50/50) | LOW | Disagreement with both perspectives |
+
+### Team Cleanup
+
+Lead MUST always handle cleanup:
+1. Ensure all teammates have completed or been shut down
+2. Call `TeamDelete` to release resources
+3. Verify no orphaned sessions remain
+4. **CRITICAL**: Confirm cleanup completed before creating next team
+
+---
+
+## Limitations
+
+| Limitation | Impact | Guidance |
+|-----------|--------|----------|
+| One team per session | Cannot run two teams concurrently | Shut down and verify cleanup before creating next team |
+| No nested teams | Teammates cannot spawn sub-teams | Keep hierarchy flat; only lead creates teams |
+| No session resumption | Teammate state lost if interrupted | Start fresh; don't rely on teammate state persistence |
+| Shutdown can be slow | Cleanup may take several seconds | Wait for confirmation; don't race to create next team |
+| Task status may lag | Task list updates aren't instant | Use direct messages for time-sensitive coordination |
+| Permissions inherited | Teammates get lead's permissions at spawn | Cannot escalate permissions mid-session |
+
+---
+
+## Anti-Patterns
+
+| Anti-Pattern | Correct Approach |
+|-------------|-----------------|
+| Overlapping perspectives | Assign distinct, non-overlapping focus areas |
+| Skipping debate round | Always require peer challenge before synthesis |
+| Unlimited debate | Cap at 2 exchanges per topic, then escalate |
+| Lead does analysis work | Lead coordinates only; teammates do analysis |
+| Ignoring minority opinion | Report dissent with evidence in final output |
+| Creating team before prior cleanup | Wait for TeamDelete confirmation, then create |
+| Messaging-only coordination | Use task list for structured progress tracking |
+
+---
+
+## Extended References
+
+- `references/team-patterns.md` - Team structures for review, implement, debug, specify, resolve workflows
+- `references/communication.md` - Message protocols, broadcast patterns, debate formats
+- `references/cleanup.md` - Session management, orphan detection, resource cleanup

package/shared/skills/agent-teams/references/cleanup.md

@@ -0,0 +1,104 @@
+# Session Management and Cleanup
+
+## Team Lifecycle
+
+```
+1. Lead creates team
+2. Lead spawns teammates
+3. Teammates work independently
+4. Debate rounds (teammates message directly)
+5. Lead collects consensus
+6. Lead shuts down teammates
+7. Lead calls cleanup
+8. Lead verifies no orphans
+```
+
+---
+
+## Cleanup Rules
+
+### Lead Responsibilities
+
+1. **Always call cleanup** - Even if team work was interrupted or errored
+2. **Shut down teammates first** - Before calling cleanup
+3. **Verify completion** - Check that no orphaned sessions remain
+
+### Error Handling
+
+If a teammate errors or hangs:
+1. Send shutdown message to the teammate
+2. Wait briefly for graceful shutdown
+3. Proceed with cleanup for remaining team
+4. Report the failed teammate in final output
+
+### Orphan Detection
+
+After cleanup, verify:
+- No tmux sessions from the team remain (split-pane mode)
+- No background processes from teammates
+- Team config at `~/.claude/teams/{team-name}/` is cleaned up
+
+---
+
+## Known Limitations
+
+| Limitation | Mitigation |
+|-----------|------------|
+| No session resumption for teammates | Start fresh; don't rely on teammate state persistence |
+| One team per session | Queue team work sequentially if needed |
+| Task status may lag | Use direct messages for time-sensitive coordination |
+| No nested teams | Teammates cannot spawn sub-teams; keep hierarchy flat |
+| Split-pane requires tmux/iTerm2 | Fall back to in-process mode if unavailable |
+
+---
+
+## Cost Management
+
+### Token Optimization
+
+| Strategy | Savings |
+|----------|---------|
+| Use haiku for validation teammates | ~70% per validation agent |
+| Limit debate to 2 rounds | Prevents runaway token usage |
+| Size teams to task (don't over-spawn) | Fewer agents = fewer tokens |
+| Shut down teammates promptly | No idle token consumption |
+
+### When NOT to Use Teams
+
+- Simple, single-focus tasks (use regular subagent)
+- Tasks requiring sequential dependency (no parallelism benefit)
+- Cost-sensitive operations where subagent is sufficient
+- Tasks where debate adds no value (e.g., formatting, simple fixes)
+
+---
+
+## Sequential Team Transition Protocol
+
+Commands that create multiple teams (e.g., `/implement`, `/specify`) MUST follow this 4-step protocol between teams. Skipping steps causes silent failures due to the one-team-per-session constraint.
+
+```
+Step 1: SHUTDOWN — Send shutdown_request to each teammate by name
+  SendMessage(type: "shutdown_request", recipient: "{name}", content: "Phase complete")
+  Wait for each shutdown_response (approve: true)
+
+Step 2: DELETE — Remove team resources
+  TeamDelete
+
+Step 3: VERIFY — Confirm cleanup succeeded
+  If TeamDelete returned success → proceed
+  If TeamDelete failed → retry once after 5s
+  If retry fails → HALT and report to user:
+    "Team cleanup failed for {team-name}. Cannot create next team."
+
+Step 4: CREATE — Only now create the next team
+  TeamCreate(team_name: "{next-team-name}")
+```
+
+### Failure Modes
+
+| Failure | Action |
+|---------|--------|
+| Teammate ignores shutdown_request | Wait 30s, then proceed to TeamDelete (force cleanup) |
+| TeamDelete fails | Retry once after 5s delay |
+| TeamDelete retry fails | HALT execution, report to user |
+| TeamCreate fails after successful delete | Retry once; if fails, fall back to parallel Task() subagents |