devflow-kit 1.8.2 → 2.0.0

package/src/assets/skills/accessibility/references/violations.md

@@ -0,0 +1,358 @@
+# Accessibility Violations
+
+Extended violation patterns for accessibility reviews. Reference from main SKILL.md.
+Sources in `references/sources.md`.
+
+---
+
+## Keyboard Navigation Violations [1][3]
+
+### No Keyboard Access [1]
+
+```tsx
+// VIOLATION: onClick without keyboard equivalent — WCAG 2.1.1 [1]
+<div onClick={handleClick} className="card">Click me</div>
+
+// VIOLATION: Custom element not focusable [1]
+<span className="link" onClick={() => navigate('/page')}>Go to page</span>
+
+// VIOLATION: Drag-only interaction — no keyboard alternative [1] §2.1.1
+<div draggable onDragStart={handleDrag} onDragEnd={handleDrop}>
+  Drag me
+</div>
+```
+
+### Missing Focus Management [3]
+
+```tsx
+// VIOLATION: Modal doesn't trap focus — APG dialog requirement [3]
+function Modal({ isOpen, children }) {
+  return isOpen ? (
+    <div className="modal-overlay">
+      <div className="modal-content">
+        {children}
+        <button onClick={onClose}>Close</button>
+        {/* Focus can escape to background; no return-focus on close */}
+      </div>
+    </div>
+  ) : null;
+}
+
+// VIOLATION: Dropdown doesn't return focus on close [3]
+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 [1][16]
+
+```css
+/* VIOLATION: Focus removed entirely — fails WCAG 2.4.7 and 2.4.11 [1][16] */
+*:focus { outline: none; }
+
+/* VIOLATION: Focus invisible on dark backgrounds [16] */
+button:focus { outline: 1px solid #333; }
+
+/* VIOLATION: Focus style same as hover — no distinct focus indicator [1] §2.4.7 */
+button:hover, button:focus { background: #eee; }
+```
+
+### Illogical Tab Order [1]
+
+```tsx
+// VIOLATION: Positive tabIndex breaks natural DOM order — WCAG 2.4.3 [1]
+<div>
+  <input tabIndex={3} placeholder="Third" />
+  <input tabIndex={1} placeholder="First" />
+  <input tabIndex={2} placeholder="Second" />
+</div>
+```
+
+---
+
+## ARIA Violations [2][15]
+
+### Missing Labels [1][5]
+
+```tsx
+// VIOLATION: Icon button without accessible name — WebAIM Million #4 violation [5]
+<button onClick={handleClose}><CloseIcon /></button>
+
+// VIOLATION: Input without label — WebAIM Million #1 violation [5]
+<input type="text" placeholder="Search" />
+
+// VIOLATION: Image without alt — WebAIM Million #3 violation [5]
+<img src="/logo.png" />
+
+// VIOLATION: Link without text content [1] §2.4.4
+<a href="/profile"><Avatar src={user.avatar} /></a>
+```
+
+### Incorrect ARIA Usage [2][15]
+
+```tsx
+// VIOLATION: role="button" on already-button element — redundant [15]
+<button role="button" onClick={handleClick}>Submit</button>
+
+// VIOLATION: aria-hidden on focusable element — keyboard trap [2]
+<button aria-hidden="true" onClick={handleClick}>Hidden but focusable</button>
+
+// VIOLATION: Missing required ARIA attributes — incomplete widget [2]
+<div role="slider">
+  {/* Missing aria-valuenow, aria-valuemin, aria-valuemax */}
+</div>
+
+// VIOLATION: aria-label duplicating visible text — redundant, no benefit [15]
+<button aria-label="Submit form">Submit form</button>
+```
+
+### Overuse of ARIA [15][18]
+
+```tsx
+// VIOLATION: ARIA where semantic HTML suffices — "no ARIA is better than bad ARIA" [15]
+<div role="navigation" aria-label="Main navigation">
+  <div role="list">
+    <div role="listitem">
+      <div role="link" onClick={() => navigate('/')}>Home</div>
+    </div>
+  </div>
+</div>
+
+// CORRECT: Native HTML [18]
+<nav aria-label="Main">
+  <ul><li><a href="/">Home</a></li></ul>
+</nav>
+```
+
+---
+
+## Color and Contrast Violations [1][5]
+
+### Insufficient Contrast [1]
+
+```css
+/* VIOLATION: Light gray on white — ~1.5:1, fails AA [1] §1.4.3 — WebAIM Million #2 [5] */
+.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 [1]
+
+```tsx
+// VIOLATION: Status only indicated by color — fails WCAG 1.4.1 [1]
+<span style={{ color: status === 'error' ? 'red' : 'green' }}>{status}</span>
+
+// VIOLATION: Required fields only marked red [1]
+<label style={{ color: required ? 'red' : 'inherit' }}>{label}</label>
+
+// VIOLATION: Chart using only color to differentiate data [1]
+<LineChart>
+  <Line stroke="red" data={series1} />
+  <Line stroke="blue" data={series2} />
+  {/* No pattern, icon, or label differentiation */}
+</LineChart>
+```
+
+---
+
+## Form Violations [1][5]
+
+### Missing Error Association [1]
+
+```tsx
+// VIOLATION: Error not associated with input — WCAG 3.3.1 [1]
+<div>
+  <input id="email" type="email" />
+  {error && <span className="error">{error}</span>}
+  {/* No aria-describedby linking input to error */}
+</div>
+
+// VIOLATION: Error not announced to screen readers [1]
+<div>
+  <input aria-invalid={!!error} />
+  {error && <div className="error-message">{error}</div>}
+  {/* No role="alert" or aria-live */}
+</div>
+```
+
+### Placeholder as Label [1][5]
+
+```tsx
+// VIOLATION: Placeholder disappears — WebAIM Million #1 violation [5]
+<input placeholder="Email address" />
+
+// VIOLATION: Floating label hidden initially — no persistent label [1] §1.3.1
+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 [1][3]
+
+```tsx
+// VIOLATION: Custom select not keyboard accessible — fails WCAG 2.1.1 [1]
+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 [1]
+
+### No Reduced Motion Support [1]
+
+```css
+/* VIOLATION: Animation ignores user preference — fails WCAG 2.3.3 [1] */
+.hero { animation: slideIn 1s ease-in-out; }
+/* No @media (prefers-reduced-motion: reduce) counterpart */
+```
+
+### Autoplay Without Pause [1]
+
+```tsx
+// VIOLATION: Video autoplays without pause control — WCAG 2.2.2 [1]
+<video autoPlay loop muted><source src="/background.mp4" /></video>
+
+// VIOLATION: Carousel auto-advances without pause [1]
+function Carousel({ slides }) {
+  useEffect(() => {
+    const interval = setInterval(nextSlide, 3000);
+    return () => clearInterval(interval);
+  }, []);
+  // No pause on hover, focus, or user control
+}
+```
+
+### Flashing Content [1]
+
+```css
+/* VIOLATION: Flash rate > 3Hz — risks seizures, fails WCAG 2.3.1 [1] */
+@keyframes flash { 0%, 100% { opacity: 1; } 50% { opacity: 0; } }
+.alert { animation: flash 0.2s infinite; }
+```
+
+---
+
+## Touch Target Violations [1][8][16]
+
+### Small Touch Targets [1][16]
+
+```css
+/* VIOLATION: Below WCAG 2.5.8 minimum of 24×24px [16] */
+.icon-btn { width: 24px; height: 24px; padding: 4px; }
+
+/* VIOLATION: Inline links with no padding */
+.inline-link { /* Natural text height only — no extra tap area */ }
+
+/* VIOLATION: Close button too small and in corner */
+.modal-close { position: absolute; top: 4px; right: 4px; width: 16px; height: 16px; }
+```
+
+### Targets Too Close Together [1][8]
+
+```tsx
+// VIOLATION: Adjacent small targets without spacing [8]
+<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 — combined miss area */}
+</div>
+```
+
+---
+
+## Screen Reader Violations [4][6]
+
+### Hidden Important Content [1][4]
+
+```tsx
+// VIOLATION: aria-hidden on important element — hides from all AT [2]
+<main aria-hidden="true">{/* Page content invisible to screen readers */}</main>
+
+// VIOLATION: sr-only misimplemented — content not exposed [4]
+<span style={{ display: 'none' }}>Loading...</span>  {/* display:none hides from AT */}
+```
+
+### Meaningless Link Text [1][6]
+
+```tsx
+// VIOLATION: Generic link text — fails WCAG 2.4.4 [1]; users navigate by link list [6]
+<p>To learn more, <a href="/services">click here</a>.</p>
+
+// VIOLATION: Repeated "Read more" links — indistinguishable out of context [6]
+{posts.map(post => (
+  <article>
+    <h2>{post.title}</h2>
+    <a href={post.url}>Read more</a>
+  </article>
+))}
+```
+
+### Missing Page Structure [1][4]
+
+```tsx
+// VIOLATION: No landmark regions — screen reader navigation impossible [1] §1.3.6
+function App() {
+  return (
+    <div>
+      <div className="header">...</div>
+      <div className="sidebar">...</div>
+      <div className="content">...</div>
+    </div>
+  );
+}
+
+// VIOLATION: Skipped heading levels — breaks document outline [1] §1.3.1
+<h1>Page Title</h1>
+<h3>Section</h3>   {/* h2 skipped */}
+<h5>Subsection</h5> {/* h4 skipped */}
+```
+
+---
+
+## Cognitive Accessibility Violations [17]
+
+```tsx
+// VIOLATION: Inaccessible authentication — WCAG 3.3.8 [16][17]
+<input type="password" onPaste={(e) => e.preventDefault()} />
+// Blocking paste forces users to type complex passwords,
+// harming users with cognitive disabilities or password managers
+
+// VIOLATION: Vague error message — no recovery path [17]
+{error && <span role="alert">Invalid input.</span>}
+// Should identify the field, the error, and how to fix it
+```

package/src/assets/skills/apply-decisions/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: apply-decisions
+description: Canonical algorithm for consuming DECISIONS_CONTEXT index — scan index, identify relevant entries, Read full bodies on demand, cite verbatim IDs inline.
+user-invocable: false
+allowed-tools: Read
+---
+
+# Apply Decisions
+
+Canonical consumer algorithm for the `DECISIONS_CONTEXT` index passed by orchestrators. The index lists each ADR/PF entry with ID, truncated title, status, and area — not the full body. Use this skill to surface the right decisions and pitfalls for your task without loading the entire corpus.
+
+## Iron Law
+
+> **VERBATIM IDs ONLY — NEVER FABRICATE**
+>
+> Cite only IDs that appear verbatim in DECISIONS_CONTEXT. If an ADR/PF ID is not
+> in the index, do not cite it. If an entry looks relevant but you haven't Read its
+> full body, do not cite it. Fabricated citations are worse than no citations.
+
+---
+
+## 5-Step Algorithm
+
+### Step 1: Scan the index
+
+Read through all entries in `DECISIONS_CONTEXT`. The index format is:
+
+```
+Decisions (N):
+  ADR-001  Title truncated to 60 chars  [Active]
+  ADR-002  Another decision             [Active]
+
+Pitfalls (M):
+  PF-004  Background hook god scripts  [Active]  —  src/assets/scripts/hooks/foo.cjs
+  PF-011  DECISIONS_CONTEXT fan-out    [Active]  —  src/assets/commands/...
+
+ADR-NNN entries live in {worktree}/.devflow/learning/decisions.md
+PF-NNN  entries live in {worktree}/.devflow/learning/pitfalls.md
+Read the relevant file and locate the matching `## ADR-NNN:` or `## PF-NNN:` heading for the full body.
+```
+
+### Step 2: Identify plausibly-relevant entries
+
+From the index, identify entries whose title or area plausibly overlaps with:
+- The files you are modifying or reviewing
+- The category of issue you are addressing (e.g., error handling, hook scripts, JSON parsing)
+- The architectural area of your change
+
+Titles are truncated to 60 characters — if a truncated title looks relevant, proceed to Step 3.
+
+### Step 3: Read the full body
+
+For each plausibly-relevant entry, use the Read tool to open the decisions file listed in the `DECISIONS_CONTEXT` footer and locate the matching `## ADR-NNN:` or `## PF-NNN:` heading. Read the full section to confirm relevance and understand the decision or pitfall completely.
+
+**The footer is the single source of truth for file paths.** Never substitute hardcoded paths — the footer resolves to the correct worktree, which may differ from your cwd in multi-worktree flows.
+
+```
+Use the exact paths from the DECISIONS_CONTEXT footer, e.g.:
+  {worktree-from-footer}/.devflow/learning/decisions.md   → find ## ADR-NNN: heading
+  {worktree-from-footer}/.devflow/learning/pitfalls.md    → find ## PF-NNN: heading
+```
+
+Only cite an entry after you have read its full body and confirmed it applies.
+
+### Step 4: Cite inline
+
+When applying a prior decision, cite as `applies ADR-NNN` in your reasoning or output. When avoiding a known pitfall, cite as `avoids PF-NNN`. Place citations in the Reasoning column of decision tables, in inline comments, or in your structured output — wherever your agent's output format captures rationale.
+
+### Step 5: Use verbatim IDs only
+
+Cite only IDs that appear verbatim in `DECISIONS_CONTEXT`. Do not guess at IDs that might exist. Do not construct IDs from memory. If no entry is clearly relevant, skip citation entirely — silence is correct when nothing applies.
+
+---
+
+## Worked Example
+
+**Scenario**: Reviewing `src/assets/scripts/hooks/background-learning` for issues.
+
+1. **Scan** — Index shows `PF-004  Background hook god scripts  [Active]  —  src/assets/scripts/hooks/foo.cjs`
+2. **Identify** — Area field includes `src/assets/scripts/hooks/` which overlaps with the file under review
+3. **Read** — Open the pitfalls file at the path given in the DECISIONS_CONTEXT footer (e.g., `<worktree>/.devflow/learning/pitfalls.md`), find `## PF-004:` section, read full body
+4. **Cite** — If the file shows signs of the god-script pattern, note `avoids PF-004` in reasoning
+5. **Verbatim** — ID `PF-004` appeared in the index; citation is valid
+
+---
+
+## Skip Guard
+
+When `DECISIONS_CONTEXT` is empty, `(none)`, or not provided: skip this skill entirely. Do not attempt to load decisions files independently. Do not speculate about what decisions or pitfalls might exist.
+
+---
+
+## Citation Format Reference
+
+| Situation | Citation |
+|-----------|----------|
+| Applying a prior architectural decision | `applies ADR-NNN` |
+| Avoiding a known pitfall | `avoids PF-NNN` |
+| Entry not in index | (no citation — silence is correct) |
+| Entry in index but not read yet | (no citation — read first) |

package/src/assets/skills/apply-feature-knowledge/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: apply-feature-knowledge
+description: Consumption algorithm for FEATURE_KNOWLEDGE variable — pre-computed feature context
+user-invocable: false
+allowed-tools: Read
+---
+
+# Apply Feature Knowledge
+
+## Iron Law
+
+> **Pre-computed context, not a cage. Verify against current code — always.**
+>
+> A feature knowledge captures patterns AS THEY WERE when last written. Code evolves.
+> Use the feature knowledge as a starting point, not gospel truth. When something feels
+> off, Read the actual files. Code is authoritative; feature knowledge is supplementary.
+
+---
+
+## 3-Step Algorithm
+
+### Step 1: Read the Feature Knowledge
+
+When `FEATURE_KNOWLEDGE` is provided and is not `(none)`:
+
+1. Read each feature knowledge section (separated by `--- Feature knowledge: {slug} ---` headers)
+2. Absorb: architecture, data flow, key patterns, anti-patterns, gotchas
+3. Note integration points that relate to your current task
+
+### Step 2: Apply to Current Task
+
+1. **Patterns as defaults**: Follow documented patterns unless you have a specific reason not to
+2. **Anti-patterns as warnings**: Check your work against documented anti-patterns
+3. **Gotchas as checklists**: Verify each gotcha doesn't apply to your changes
+4. **Integration points**: Ensure your changes respect documented boundaries
+5. **Key files**: Use as starting points for exploration
+
+### Step 3: Verify Against Current Code
+
+The feature knowledge may not reflect recent changes:
+- If the feature knowledge doesn't address your specific area, explore further
+- **When an assertion seems outdated**: Read the relevant source files to confirm — code wins
+- When you find a contradiction between the KB and actual code, trust the code
+- Note discrepancies in your output when they matter for the task
+
+---
+
+## Skip Guard
+
+When `FEATURE_KNOWLEDGE` is `(none)`, empty, or not provided — skip this skill entirely.
+Do not mention feature knowledge or its absence in your output.
+
+## Freshness Model
+
+Feature knowledge uses **write-through + verify-on-read** for freshness:
+- KBs are written at the point a documented area changes (not on a background schedule)
+- Readers verify key assertions against current code rather than relying on staleness markers
+- When in doubt, Read the file — that resolves any uncertainty immediately
+
+## Concatenation Format
+
+Multiple feature knowledge entries are concatenated with slug headers:
+```
+--- Feature knowledge: payments ---
+[full KNOWLEDGE.md content]
+
+--- Feature knowledge: auth ---
+[full KNOWLEDGE.md content]
+```

package/src/assets/skills/architecture/SKILL.md

@@ -0,0 +1,138 @@
+---
+name: architecture
+description: This skill should be used when reviewing code for SOLID violations, tight coupling, or layering issues.
+user-invocable: false
+allowed-tools: Read, Grep, Glob
+---
+
+# Architecture Patterns
+
+Domain expertise for software architecture and design pattern analysis. Full bibliography: `references/sources.md`.
+
+## Iron Law
+
+> **SEPARATION OF CONCERNS IS NON-NEGOTIABLE** [1][2]
+>
+> Every module has one reason to change. Every layer has clear boundaries. Every dependency
+> points in one direction. Parnas (1972): decompose by information hiding, not by task.
+> Violations compound into unmaintainable systems. [1][19]
+
+---
+
+## SOLID Violations [2]
+
+**SRP** — One class, one reason to change. [1][2][8]
+```
+VIOLATION: UserController handles HTTP + validation + DB + email
+CORRECT:   Inject UserService, UserValidator — each class has one reason to change
+```
+
+**OCP** — Extend without modifying. [2]
+```
+VIOLATION: if (type === 'credit') ... else if (type === 'paypal') ...
+CORRECT:   Strategy pattern — new payment = new class, existing code unchanged
+```
+
+**LSP** — Subtypes must be substitutable. [3] Liskov & Wing (1994): subtype cannot strengthen preconditions. Throwing where parent doesn't throw is a violation.
+```
+VIOLATION: ReadOnlyStorage extends FileStorage { write() { throw new Error(...) } }
+CORRECT:   Segregated interfaces (Readable, Writable) — compile-time, not runtime
+```
+
+**ISP** — No forced unused implementations. [2]
+```
+VIOLATION: interface Worker { work(); eat(); sleep(); }  // Robot forced to implement eat()
+CORRECT:   interface Workable { work(): void; }  — implement only what you support
+```
+
+**DIP** — Depend on abstractions, not concretions. [2][18] Fowler (2004): constructor injection is the cleanest form. [18]
+```typescript
+// VIOLATION: class OrderService { private db = new PostgresDatabase(); }
+// CORRECT:   class OrderService { constructor(private repo: OrderRepository) {} }
+```
+
+---
+
+## Coupling Issues [8][17]
+
+Stevens, Myers & Constantine (1974): content coupling (direct instantiation) is the tightest and worst form. [8]
+
+**Tight Coupling** [8][18]: Direct instantiation — can't mock, can't swap.
+```
+VIOLATION: class ReportGenerator { generate() { new DatabaseService().query(...) } }
+CORRECT:   Inject dependencies via constructor
+```
+
+**Circular Dependencies** [19]: A imports B, B imports A. Extract shared concern or use events.
+
+**Feature Envy** [21] / **Law of Demeter** [17]: `order.customer.profile.contact.email` — knows too much.
+```
+VIOLATION: OrderProcessor computes order.customer.profile.total
+CORRECT:   order.getTotal() — behavior belongs to the data owner
+```
+
+---
+
+## Layering Violations [5][7][10]
+
+Clean Architecture (Martin, 2017) Dependency Rule: source code dependencies can only point inward. [5]
+
+**Skipping Layers**: Controller directly accessing database. [5][7]
+```typescript
+// VIOLATION: Controller → DB (skips service)
+const user = await db.query('SELECT...', [req.params.id]);
+// CORRECT: Controller → Service → Repository [5][7]
+const user = await this.userService.findById(req.params.id);
+```
+
+**Leaky Abstractions**: Infrastructure details in domain. [9]
+```
+VIOLATION: interface User { id: string; _mongoId: ObjectId; __v: number; }
+CORRECT:   interface User { id: string; name: string; }  — map in repository [7]
+```
+
+**Wrong Direction**: Domain must not import infrastructure. [5][10] Hexagonal Architecture (Cockburn, 2005): ports define what core needs; adapters implement them. [10]
+
+---
+
+## Modularity Issues [1][9]
+
+**Deep vs Shallow Modules** (Ousterhout, 2018): deep module = simple interface, rich implementation. Shallow = more complexity exposed than hidden. [9]
+
+**God Class** [1][6]: Splits into bounded contexts. Warning signs: 500+ lines, `*Manager`, `*Processor`, 7+ constructor parameters.
+
+**Inappropriate Intimacy** [17][21]: `a.b().c()` chains — use "tell, don't ask."
+
+---
+
+## Severity Guidelines
+
+| Severity | Examples |
+|----------|----------|
+| **CRITICAL** | Circular dependencies, domain depends on infrastructure, god class 1000+ lines [5][19] |
+| **HIGH** | SOLID violations in core logic, tight coupling between services, leaky abstractions [2][8] |
+| **MEDIUM** | Dependencies not injected, minor layering violations, missing interfaces [18] |
+| **LOW** | Naming issues, minor organization, missing architecture docs |
+
+---
+
+## Architecture Principles Reference
+
+| Principle | Violation Sign | Source | Fix |
+|-----------|----------------|--------|-----|
+| SRP | Multiple reasons to change | [1][2] | Extract classes |
+| OCP | Modifying to add features | [2] | Strategy pattern |
+| LSP | Subclass throws "not supported" | [3] | Composition + segregated interfaces |
+| ISP | Unused interface methods | [2] | Split interfaces |
+| DIP | `new ConcreteClass()` in business | [2][18] | Inject via constructor |
+| Law of Demeter | `a.b().c()` chains | [17] | Tell, don't ask |
+| Deep Modules | Shallow abstractions | [9] | Encapsulate complexity |
+
+---
+
+## Extended References
+
+- `references/sources.md` — Full bibliography (25 sources)
+- `references/patterns.md` — Extended correct patterns with citations [2][3][5][7][10][18]
+- `references/violations.md` — Extended violations with citations [1][2][3][8][17][19][21]
+- `references/detection.md` — Grep patterns and bash commands for automated detection