devflow-kit 1.8.2 → 2.0.0

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

@@ -0,0 +1,272 @@
+# Python Violation Examples
+
+Extended violation patterns for Python reviews. Reference from main SKILL.md.
+All citations reference `sources.md`.
+
+## Type Safety Violations
+
+### Missing Type Hints [4][17][18]
+
+PEP 484 made type hints standard in 2014; unannotated public APIs are a code smell [4].
+Dropbox's 4-million-line migration showed that annotations catch bugs before runtime [18]:
+
+```python
+# VIOLATION: No type annotations [4]
+def process(data, config):
+    result = transform(data)
+    return result
+
+# VIOLATION: Partial annotations (inconsistent) [4]
+def save(user: User, db):  # db missing type
+    return db.insert(user)
+
+# VIOLATION: Missing return type [17]
+def calculate_total(items: list[Item]):
+    return sum(item.price for item in items)
+```
+
+### Bare Except Clauses [2][8]
+
+Google Style Guide prohibits bare `except:` — it catches `SystemExit` and
+`KeyboardInterrupt`, preventing clean shutdown [8]. Slatkin's Item 87 recommends
+specific exception types [2]:
+
+```python
+# VIOLATION: Catches everything including SystemExit and KeyboardInterrupt [8]
+try:
+    process_data()
+except:
+    pass
+
+# VIOLATION: Catches too broadly and silences [2]
+try:
+    user = fetch_user(user_id)
+except Exception:
+    user = None  # Hides real errors (network, auth, parsing)
+
+# VIOLATION: Bare except with logging but no re-raise [8]
+try:
+    critical_operation()
+except:
+    logger.error("Something failed")
+    # Swallows the error — caller never knows
+```
+
+## Data Modeling Violations
+
+### Raw Dicts Instead of Dataclasses [6][14][19]
+
+PEP 557 dataclasses add typed fields and IDE support at zero runtime cost [6].
+Viafore argues raw dicts make wrong code look right — type system cannot catch
+misspelled keys or incorrect value types [14]. Spolsky's principle: make wrong code
+look wrong [19]:
+
+```python
+# VIOLATION: Untyped dict — no IDE support, no validation [14][19]
+user = {
+    "name": "Alice",
+    "email": "alice@example.com",
+    "age": 30,
+}
+
+# VIOLATION: Accessing dict keys without safety [19]
+def get_display_name(user: dict) -> str:
+    return f"{user['first_name']} {user['last_name']}"  # KeyError risk
+
+# VIOLATION: Nested untyped dicts [14]
+config = {
+    "database": {
+        "host": "localhost",
+        "port": 5432,
+    },
+    "cache": {
+        "ttl": 300,
+    },
+}
+```
+
+### Mutable Default Arguments [2][3]
+
+Slatkin's Item 24: never use mutable values as default arguments [2].
+PEP 20's "Explicit is better than implicit" applies — the shared-state behavior is
+invisible to callers [3]:
+
+```python
+# VIOLATION: Mutable default shared across calls [2]
+def add_item(item: str, items: list[str] = []) -> list[str]:
+    items.append(item)
+    return items
+
+# VIOLATION: Dict default mutated in place [2]
+def register(name: str, registry: dict[str, bool] = {}) -> None:
+    registry[name] = True
+
+# VIOLATION: Set default [2]
+def collect(value: int, seen: set[int] = set()) -> set[int]:
+    seen.add(value)
+    return seen
+```
+
+## String Formatting Violations
+
+### Percent Formatting [8][2]
+
+Google Style Guide and Slatkin both require f-strings (Python 3.6+) over
+`%` or `.format()` [8][2]:
+
+```python
+# VIOLATION: Old-style % formatting [8]
+message = "Hello %s, you have %d messages" % (name, count)
+
+# VIOLATION: % formatting with dict — hard to read, error-prone [8]
+log = "%(timestamp)s - %(level)s - %(message)s" % log_data
+```
+
+### String Concatenation in Loops [2][10]
+
+Slatkin Item 11 and Beazley & Jones both flag O(n²) string concatenation [2][10]:
+
+```python
+# VIOLATION: O(n^2) string building [2]
+result = ""
+for line in lines:
+    result += line + "\n"
+
+# CORRECT: Use join [2]
+result = "\n".join(lines)
+```
+
+## Global State Violations
+
+### Module-Level Mutable State [9][3]
+
+Cosmic Python's service layer design eliminates global mutable state — side effects
+are in explicit service functions, not module-level variables [9]. PEP 20: "Explicit
+is better than implicit" [3]:
+
+```python
+# VIOLATION: Global mutable state [9]
+_cache = {}
+_connections = []
+
+def get_cached(key: str) -> Any:
+    return _cache.get(key)
+
+def add_connection(conn: Connection) -> None:
+    _connections.append(conn)
+
+# VIOLATION: Global variable modified by functions [9]
+current_user = None
+
+def login(username: str) -> None:
+    global current_user
+    current_user = authenticate(username)
+```
+
+### Singleton via Module Import [9][13]
+
+Cosmic Python shows this pattern makes testing impossible — the module-level object
+cannot be swapped for a test double [9][13]:
+
+```python
+# VIOLATION: Hard-to-test singleton [9]
+# db.py
+connection = create_connection(os.environ["DATABASE_URL"])
+
+# service.py
+from db import connection  # Cannot mock or swap for tests [13]
+```
+
+## Import Violations
+
+### Wildcard Imports [8][3]
+
+Google Style Guide prohibits `import *` — it pollutes the namespace and hides
+dependencies [8]. PEP 20: "Explicit is better than implicit" [3]:
+
+```python
+# VIOLATION: Pollutes namespace, hides dependencies [8]
+from os.path import *
+from utils import *
+
+# VIOLATION: Star import in __init__.py [8]
+# mypackage/__init__.py
+from .models import *
+from .services import *
+```
+
+### Circular Imports [9][8]
+
+Cosmic Python's layered architecture (domain → adapters → service layer) prevents
+circular imports by enforcing one-way dependency flow [9]:
+
+```python
+# VIOLATION: Circular dependency [9]
+# models.py
+from services import UserService  # services imports models too
+
+# services.py
+from models import User  # Circular!
+```
+
+## Testing Violations
+
+### Assert in Production Code [2][13]
+
+Slatkin Item 88: `assert` is disabled with Python `-O` flag — use explicit checks
+with proper exceptions instead [2]:
+
+```python
+# VIOLATION: assert is stripped with -O flag [2]
+def withdraw(account: Account, amount: float) -> None:
+    assert amount > 0, "Amount must be positive"  # Disabled in production!
+    assert account.balance >= amount, "Insufficient funds"
+    account.balance -= amount
+```
+
+### No pytest Fixtures [13][9]
+
+pytest fixture composition avoids repeated setup — Cosmic Python's test patterns
+show service fixtures built from smaller, reusable parts [13][9]:
+
+```python
+# VIOLATION: Repeated setup in every test [13]
+def test_create_user():
+    db = Database(":memory:")
+    db.create_tables()
+    service = UserService(db)
+    # ... test logic
+
+def test_update_user():
+    db = Database(":memory:")  # Duplicated setup [13]
+    db.create_tables()
+    service = UserService(db)
+    # ... test logic
+```
+
+## Protocol Violations
+
+### ABC Where Protocol Suffices [5][1][14]
+
+PEP 544 Protocols provide structural subtyping without coupling the implementor
+to the interface module [5]. Ramalho calls ABC-based designs "nominal typing" that
+creates unnecessary coupling [1]:
+
+```python
+# VIOLATION: Forces third-party class to inherit from your ABC [1]
+from abc import ABC, abstractmethod
+
+class Serializable(ABC):
+    @abstractmethod
+    def to_dict(self) -> dict: ...
+
+# Pydantic models can't be passed without subclassing — breaks duck typing
+
+# CORRECT: Protocol — any class with to_dict() works [5]
+from typing import Protocol
+
+class Serializable(Protocol):
+    def to_dict(self) -> dict: ...
+
+# Pydantic models, dataclasses, any class with to_dict() works automatically
+```

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

@@ -0,0 +1,136 @@
+---
+name: qa
+description: This skill should be used when performing scenario-based acceptance testing,
+  designing QA test plans, or validating that implementation behavior matches acceptance
+  criteria beyond unit tests.
+user-invocable: false
+allowed-tools: Read, Grep, Glob, Bash
+---
+
+# QA Patterns
+
+Scenario-based acceptance testing methodology. Ensures implementations satisfy user-observable requirements beyond what unit tests cover.
+
+## Iron Law
+
+> **VERIFY BEHAVIOR FROM THE USER'S PERSPECTIVE** [1][2]
+>
+> Test what the user asked for, not implementation details. Every acceptance criterion
+> gets at least one scenario. Every scenario produces observable evidence. If you can't
+> demonstrate it works from the outside, it doesn't work. [3][8]
+
+---
+
+## Scenario Types [1][2][6]
+
+Five categories ensure comprehensive coverage:
+
+| Type | Purpose | Example |
+|------|---------|---------|
+| **Happy path** | Core functionality works as described | "Add item → item appears in list" |
+| **Boundary/edge** | Limits, empty, maximum, minimum values | "Add item with 1000-char name → truncated or rejected" |
+| **Negative path** | Invalid inputs, missing permissions, errors | "Add item without auth → 401 returned" |
+| **Integration** | Components work together correctly | "Add item → appears in search results" |
+| **Regression** | Existing behavior preserved after changes | "Old items still load after schema migration" |
+
+**Minimum coverage**: At least one scenario per acceptance criterion. At least one boundary and one negative scenario per feature. [1][6]
+
+## Scenario Design from Acceptance Criteria [4][8][9]
+
+Extract testable claims using Given/When/Then:
+
+```
+Acceptance criterion: "Users can upload files up to 10MB"
+
+S1 (happy):    Given auth user, When upload 5MB file, Then 200 + file accessible
+S2 (boundary): Given auth user, When upload 10MB file, Then 200 (exact limit)
+S3 (boundary): Given auth user, When upload 10.1MB file, Then 413 rejected
+S4 (negative): Given no auth, When upload 5MB file, Then 401
+S5 (negative): Given auth user, When upload empty file, Then 400
+```
+
+**Extracting criteria** [4]: If no explicit acceptance criteria, derive from the request:
+1. What new behavior was requested? → happy path scenarios
+2. What inputs does it accept? → boundary scenarios [7][10]
+3. What should it reject? → negative scenarios
+4. What existing behavior must survive? → regression scenarios
+
+## Equivalence Partitioning & Boundary Analysis [1][6][7]
+
+Reduce infinite inputs to representative cases:
+
+- **Valid partition**: One representative value from each valid class
+- **Invalid partition**: One representative from each invalid class
+- **Boundary values**: On, just below, just above each boundary [10]
+
+```
+Input: age (integer, 0-120 allowed)
+├── Valid: 25 (mid-range), 0 (minimum), 120 (maximum)
+├── Invalid: -1 (below min), 121 (above max), "abc" (wrong type)
+└── Boundary: 0, 1, 119, 120
+```
+
+## Exploratory Testing Heuristics [2][3][11]
+
+When acceptance criteria are vague, use structured exploration:
+
+- **CRUD tour** [11]: Create, Read, Update, Delete — does each operation work end-to-end?
+- **Configuration tour** [11]: Change every configurable value — does the system adapt?
+- **Error tour** [3]: Force every error path — are messages helpful, is state clean?
+- **Boundary tour** [3][11]: Push every input to its limits
+
+## Evidence Collection
+
+Every scenario must produce verifiable evidence:
+
+| Evidence Type | How to Capture | When to Use |
+|--------------|----------------|-------------|
+| Exit codes | `echo $?` after command | CLI tools, scripts |
+| Stdout/stderr | Redirect to capture | All command execution |
+| File state | `ls -la`, `diff`, `cat` | File creation/modification |
+| HTTP status | Response code from curl/fetch | API endpoints |
+| Log output | Grep logs after action | Background processes |
+
+## Browser-Based Scenarios [8][12]
+
+When implementation includes web-facing changes (.tsx, .jsx, .html, routes, pages):
+
+| Scenario Type | Browser Action | Evidence |
+|--------------|---------------|----------|
+| Page renders | Navigate → read page text | Page content, no console errors |
+| Form works | Find fields → input → submit | Redirect or DOM state change |
+| Validation fires | Input invalid data → check | Error messages visible in page |
+| Console clean | Navigate → read console | No errors/warnings logged |
+| Navigation works | Click links → verify URL change | Correct page loaded |
+
+**Dev server lifecycle**: Check for running server first. If none, auto-start from package.json scripts, poll for readiness, kill after testing. Never kill pre-existing servers.
+**Testability assessment**: Before designing scenarios, assess what local infrastructure is available (DB, Redis, external APIs). Mark scenarios requiring unavailable infrastructure as SKIPPED.
+**Graceful degradation**: If browser tools or dev server unavailable, fall back to curl/API testing. Always report what was skipped and why alongside what was tested.
+
+## Severity Classification
+
+| Level | Meaning | Action |
+|-------|---------|--------|
+| **BLOCKING** | Acceptance criterion violated — feature does not work as requested | Report FAIL — Code agent must fix |
+| **WARNING** | Edge case concern — feature works but edge behavior is unexpected | Report PASS with warnings — note for improvement |
+
+---
+
+## Extended References
+
+For additional scenario templates and anti-patterns:
+- `references/sources.md` — Full bibliography with access details
+- `references/patterns.md` — Correct scenario design patterns
+- `references/violations.md` — QA anti-patterns to avoid
+- `references/scenario-templates.md` — Templates for common feature types
+
+---
+
+## Success Criteria
+
+- [ ] Every acceptance criterion has at least one scenario
+- [ ] At least one boundary and one negative scenario per feature
+- [ ] Every scenario has Given/When/Then structure
+- [ ] Every result has captured evidence (stdout, exit code, file state)
+- [ ] Severity correctly assigned: BLOCKING for criteria violations, WARNING for edge cases
+- [ ] Non-testable changes (docs, config) correctly identified and skipped

package/src/assets/skills/qa/references/browser-testing.md

@@ -0,0 +1,97 @@
+# Browser Testing Procedures
+
+Detailed procedures for dev server lifecycle and browser scenario execution in QA.
+
+---
+
+## Dev Server Lifecycle
+
+When web-facing changes detected, manage a dev server for browser testing:
+
+### 1. Check for Already Running Server
+
+Before starting anything, check if a dev server is already running:
+- `lsof -i :3000 -i :5173 -i :8080 -i :4200 -i :8000 -t 2>/dev/null`
+- If a server is already running on the expected port: USE IT (do not start another)
+- Record whether server was pre-existing (skip cleanup if so)
+
+### 2. Discover Server Command (if no running server)
+
+Read `package.json` (or equivalent) to find the dev server command:
+- Check `scripts.dev`, `scripts.start`, `scripts.serve` (in that order)
+- For Python: look for `manage.py`, Flask/FastAPI entry points
+- For Go: check `Makefile` or `go run` targets
+- If no dev script found: skip browser scenarios, report "No dev server script — browser scenarios skipped"
+
+### 3. Detect Port
+
+Determine port from (in order):
+- Framework config: `vite.config.ts` (server.port), `next.config.js`
+- `.env` file: extract only `PORT` — `grep ^PORT= .env | cut -d= -f2` (do NOT read entire .env)
+- Script definition: parse `--port` flags in the dev script
+- Defaults by framework: Next.js→3000, Vite→5173, CRA→3000, Django→8000, Go→8080
+
+### 4. Start Server (if not already running)
+
+- Create a unique log file: `SERVER_LOG=$(mktemp /tmp/devflow-tester-XXXXXX.log)`
+- Run in background: `npm run dev > "$SERVER_LOG" 2>&1 &`
+- Record PID: `DEV_SERVER_PID=$!`
+- Poll for readiness: `curl -s -o /dev/null -w "%{http_code}" http://localhost:{port}/`
+- Retry up to 15 times, 2s intervals (30s max)
+- If timeout: kill server, skip browser scenarios, report "Dev server did not become ready within 30s"
+
+### 5. Run Browser Scenarios
+
+(See Browser Execution section below)
+
+### 6. Cleanup (only for servers WE started)
+
+- Kill dev server: `kill $DEV_SERVER_PID 2>/dev/null`
+- Kill process group: `kill -- -$DEV_SERVER_PID 2>/dev/null || true`
+- Remove log file: `rm -f "$SERVER_LOG"`
+- NEVER kill a pre-existing server
+
+---
+
+## Browser Execution
+
+Requires: Chrome MCP tools available + dev server running.
+
+1. Check Chrome availability: attempt `mcp__claude-in-chrome__tabs_context_mcp`
+   - If unavailable: skip browser scenarios, note "Chrome MCP tools not available"
+   - If available: create a new tab with `mcp__claude-in-chrome__tabs_create_mcp`
+
+2. For each browser scenario:
+   a. Navigate: `mcp__claude-in-chrome__navigate` to the relevant page
+   b. Read content: `mcp__claude-in-chrome__get_page_text` or `mcp__claude-in-chrome__read_page`
+   c. Find elements: `mcp__claude-in-chrome__find` for buttons, forms, text
+   d. Interact: `mcp__claude-in-chrome__form_input` for form fields
+   e. Assert via JS: `mcp__claude-in-chrome__javascript_tool` for state checks
+   f. Check console: `mcp__claude-in-chrome__read_console_messages` for errors
+   g. Record evidence from each step
+
+3. After all browser scenarios: close the tab created in step 1
+
+---
+
+## Bash Execution Constraints
+
+When executing scenarios via Bash, these constraints are mandatory:
+
+**NEVER execute:**
+- Destructive filesystem commands: `rm -rf`, `rmdir`, `truncate`, `shred`
+- Privilege escalation: `sudo`, `su`, `chown`, `chmod` on system directories
+- Code injection vectors: `eval`, `exec`, shell substitution on untrusted input
+- Package management: `npm install -g`, `pip install`, `brew install`, `apt-get`
+- Network exfiltration: outbound curl/wget to external hosts not under test
+
+**ONLY run:**
+- Test runners: `npm test`, `pytest`, `go test`, `cargo test`, `jest`, `mocha`
+- Build commands: `npm run build`, `go build`, `cargo build`
+- Read-only file inspection: `cat`, `ls`, `diff`, `head`, `tail`, `grep`
+- Readiness checks: `curl` to `localhost` only, `lsof`, `pg_isready`, `redis-cli ping`
+- Process management for servers WE started: `kill $DEV_SERVER_PID`
+
+**Filesystem writes restricted to:**
+- Temporary files created via `mktemp` in `/tmp/devflow-tester-*`
+- Project test directories (e.g., `__tests__/fixtures/`, `test/data/`)

package/src/assets/skills/qa/references/patterns.md

@@ -0,0 +1,118 @@
+# QA Skill — Correct Patterns
+
+Scenario design patterns that produce reliable, maintainable acceptance tests.
+
+## Pattern 1: Criterion-Driven Scenario Design [4][9]
+
+Derive scenarios directly from acceptance criteria using Given/When/Then:
+
+```
+Criterion: "Admin users can delete any comment"
+
+S1 (happy):    Given admin user + existing comment
+               When DELETE /comments/{id}
+               Then 200 + comment removed from database
+
+S2 (negative): Given regular user + existing comment
+               When DELETE /comments/{id}
+               Then 403 + comment still exists
+
+S3 (negative): Given admin user + non-existent comment
+               When DELETE /comments/{id}
+               Then 404
+
+S4 (boundary): Given admin user + already-deleted comment
+               When DELETE /comments/{id}
+               Then 404 (idempotent)
+```
+
+**Why**: Direct criterion mapping ensures nothing is missed [4]. Every criterion generates at least one scenario.
+
+## Pattern 2: Boundary Triplet Testing [1][6][10]
+
+For every boundary, test three values: below, on, and above:
+
+```
+Constraint: "Username must be 3-20 characters"
+
+Below minimum: "ab" (2 chars) → rejected
+At minimum:    "abc" (3 chars) → accepted
+Above minimum: "abcd" (4 chars) → accepted
+Below maximum: 19 chars → accepted
+At maximum:    20 chars → accepted
+Above maximum: 21 chars → rejected
+```
+
+**Why**: Most defects cluster at boundaries [1][7]. The triplet pattern catches off-by-one errors systematically.
+
+## Pattern 3: State-Based Scenario Chains [6][7]
+
+Test state transitions that matter to the user:
+
+```
+Feature: Order lifecycle
+
+S1: Created → Paid (happy path)
+S2: Created → Cancelled (valid transition)
+S3: Paid → Shipped (happy path)
+S4: Shipped → Cancelled (should this be allowed? → negative)
+S5: Cancelled → Paid (invalid transition → error)
+```
+
+**Why**: State machines reveal invalid transitions that happy-path testing misses [6].
+
+## Pattern 4: Evidence-First Execution [8][12]
+
+Capture evidence before asserting:
+
+```bash
+# Execute
+OUTPUT=$(some-command 2>&1)
+EXIT_CODE=$?
+
+# Evidence captured — now assert
+echo "Exit code: $EXIT_CODE"
+echo "Output: $OUTPUT"
+
+# Check expectations
+if [ $EXIT_CODE -ne 0 ]; then
+  echo "FAIL: Expected exit code 0, got $EXIT_CODE"
+fi
+```
+
+**Why**: Raw evidence enables debugging when scenarios fail. Without it, you only know "it failed" but not why [8].
+
+## Pattern 5: Regression Guard Scenarios [5][12]
+
+After modifying existing code, verify unchanged behavior:
+
+```
+Feature: New search filter added to existing search
+
+S1 (regression): Existing search without filter still works
+S2 (regression): Existing search results unchanged
+S3 (happy):      New filter produces expected results
+S4 (integration): Filter + existing sort work together
+```
+
+**Why**: Most production bugs are regressions — features that used to work and stopped [12].
+
+## Pattern 6: Exploratory Charters [3][11]
+
+When criteria are vague, use structured exploration:
+
+```
+Charter: "Explore the file upload feature with hostile inputs"
+Time-box: 15 minutes
+
+Tour plan:
+1. Upload file with special characters in name
+2. Upload file with zero bytes
+3. Upload file with executable extension
+4. Simultaneous uploads of same file
+5. Upload during network interruption (kill mid-transfer)
+
+Record: What happened, what was surprising, what broke
+```
+
+**Why**: Scripted tests find expected bugs. Exploratory testing finds unexpected ones [3][11].