@deftai/directive-content 0.55.0

package/interfaces/rest.md

@@ -0,0 +1,212 @@
+# REST API Design
+
+Resource-based, stateless, standard HTTP methods, JSON by default.
+
+Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
+
+## Core Architecture
+
+REST APIs are resource-based, stateless, and use standard HTTP methods with JSON as the default format. Design resources as nouns, use HTTP verbs for operations, and maintain strict statelessness with token-based authentication.
+
+## URIs
+
+- ! Use nouns, ⊗ use verbs (`/products` not `/getProducts`)
+- ~ Use plural nouns for collections (`/users` not `/user`)
+- ! Lowercase with hyphens (⊗ underscores)
+- ~ Limit nesting to 1-2 levels; beyond that use query params
+- ! Use reserved chars correctly: `/` hierarchy, `?` queries, `#` fragments
+
+```
+GET /products                     # Collection
+GET /products/123                 # Single resource
+GET /products/123/reviews         # Nested (max 2 levels)
+GET /products?category=electronics&sort=price  # Filtering/sorting
+```
+
+## HTTP Methods
+
+! Use methods per RFC 7231/9110 semantics:
+
+- **GET**: Retrieve (idempotent, safe, cacheable)
+- **POST**: Create (not idempotent)
+- **PUT**: Replace entire resource (idempotent)
+- **PATCH**: Partial update (not idempotent)
+- **DELETE**: Remove (idempotent)
+- **HEAD**: Headers only (idempotent, safe, cacheable)
+- **OPTIONS**: Allowed methods (idempotent, safe)
+
+```
+GET /users/123              # Retrieve
+POST /users                 # Create
+PUT /users/123              # Replace
+PATCH /users/123            # Update fields
+DELETE /users/123           # Remove
+```
+
+## Status Codes
+
+! Use standard HTTP status codes (RFC 7231):
+
+**2xx Success**:
+- ! `200 OK` for successful GET/PUT/PATCH
+- ! `201 Created` for POST; ~ include Location header
+- ~ `204 No Content` for DELETE or PUT with no body
+
+**3xx Redirection**:
+- ? `301 Moved Permanently`, `304 Not Modified` as appropriate
+
+**4xx Client Error**:
+- ! `400 Bad Request` for malformed/validation errors
+- ! `401 Unauthorized` for missing/invalid auth
+- ! `403 Forbidden` for authenticated but not authorized
+- ! `404 Not Found` for nonexistent resource
+- ? `422 Unprocessable Entity` for semantic errors
+
+**5xx Server Error**:
+- ~ `500 Internal Server Error` for generic errors
+- ~ `502 Bad Gateway` for upstream failure
+- ! `503 Service Unavailable` for temporary unavailability
+
+## Request/Response
+
+- ! Use JSON (`application/json`) by default
+- ? Support other formats via content negotiation
+
+```http
+POST /users
+Content-Type: application/json
+{"name": "Alice", "email": "alice@example.com"}
+
+HTTP/1.1 201 Created
+Location: /users/456
+{"id": 456, "name": "Alice", "email": "alice@example.com"}
+```
+
+**Error format**:
+```json
+{"error": {"code": "VALIDATION_ERROR", "message": "...", "details": [...]}}
+```
+
+## Statelessness
+
+- ! Be stateless; each request contains all needed info
+- ⊗ Maintain client session state on server
+- ! Use token auth in headers: `Authorization: Bearer <token>`
+- ! Client manages its own state
+- ⊗ Use session cookies for state
+
+## Collections
+
+~ Support filtering, sorting, pagination for collections:
+
+- **Filtering**: `?category=electronics&brand=apple`
+- **Sorting**: `?sort=price` (asc), `?sort=-price` (desc)
+- **Pagination**: `?page=2&size=20` (~ page-based; offset-based optional)
+- ~ Include metadata: `{"data": [...], "page": 2, "total": 450, "links": {...}}`
+
+## Versioning
+
+- ! Implement versioning from day one
+- URI: `/v1/products` (most common)
+- Header: `API-Version: 2` (cleaner)
+- Content negotiation: `Accept: application/vnd.example.v2+json` (purist)
+- ~ Follow semantic versioning: vMAJOR.MINOR.PATCH
+- ! Give 6-12 months deprecation notice; ! document migration path
+
+## Caching
+
+~ Use HTTP cache headers (RFC 9111) for cacheable resources:
+
+- **Cache-Control**: `Cache-Control: public, max-age=3600, must-revalidate`
+- **ETag**: `ETag: "abc123"` + conditional `If-None-Match` → `304 Not Modified`
+- **Last-Modified**: `Last-Modified` + conditional `If-Modified-Since`
+- Only GET/HEAD may be cached; ⊗ cache POST/PUT/DELETE
+
+## Security
+
+**Transport**:
+- ! Public APIs use HTTPS; local/internal APIs may use HTTP
+
+**Authentication**:
+- ! Public APIs implement auth; ~ local APIs implement auth; prototypes may defer initially
+- ~ OAuth 2.0 for user auth, JWT for stateless, API keys for service-to-service
+
+**Authorization**:
+- ~ Implement RBAC
+
+**Security Headers**:
+- ~ Include: `Strict-Transport-Security`, `Content-Security-Policy`, `X-Content-Type-Options`, `X-Frame-Options`
+
+**Input Validation**:
+- ! Validate all inputs (type, format, range)
+- ! Sanitize to prevent SQL injection, XSS
+- ~ Use allow-lists; ≉ rely on deny-lists alone
+
+**Rate Limiting** (~ implement):
+- `X-RateLimit-*` headers; ~ sliding window; ! return `429 Too Many Requests`
+
+## Performance
+
+- ~ Support compression: `Accept-Encoding: gzip, brotli`
+- ? Support sparse fieldsets: `?fields=id,name,email`
+- ~ Large resources support Range requests: `206 Partial Content`
+- ~ Long-running tasks use async pattern: POST → `201` + Location → GET status
+
+## Documentation
+
+- ! Provide comprehensive documentation; ~ use OpenAPI/Swagger
+- ! Include: all endpoints, schemas, auth methods, error codes, rate limits, versioning, changelog
+- ? Use tools: Swagger UI, ReDoc, or Postman
+
+## HATEOAS
+
+? Implement HATEOAS (hypermedia links guide navigation):
+
+```json
+{"id": 123, "links": [
+  {"rel": "self", "href": "/products/123"},
+  {"rel": "reviews", "href": "/products/123/reviews"}
+]}
+```
+
+Trade-off: flexibility vs response size
+
+## Testing
+
+See [testing.md](../coding/testing.md) for universal requirements.
+
+- ! Unit tests: individual endpoints, edge cases
+- ! Integration tests: full workflows, realistic scenarios
+- ~ Load tests: JMeter, Gatling, k6
+- ! Security tests: SQL injection, XSS, auth bypass (OWASP ZAP, Burp Suite)
+
+## Monitoring
+
+- ! Implement monitoring; ~ track: uptime, response times, error rates, request volume, rate limits, auth failures
+- ~ Use correlation IDs (`X-Request-ID`) for tracing
+
+## Anti-patterns
+
+- ⊗ Verbs in URIs (`/getUsers`)
+- ⊗ Non-standard status codes (`200 OK` with error in body)
+- ⊗ Session state on server
+- ⊗ Different data types from same endpoint
+- ⊗ Deep nesting (`/a/1/b/2/c/3/d/4`)
+- ⊗ Ignoring HTTP method semantics
+- ⊗ No versioning from start
+- ⊗ Exposing internal DB structure directly
+
+## Summary
+
+1. ! Resources as nouns, HTTP methods as verbs
+2. ! JSON for requests/responses
+3. ! Stateless with token auth
+4. ! Standard HTTP status codes
+5. ! Version from day one
+6. ~ Filter, sort, paginate collections
+7. ~ Cache with ETags/Cache-Control
+8. ! HTTPS for public APIs
+9. ~ Rate limit
+10. ! Document with OpenAPI
+11. ! Test: unit, integration, security
+12. ! Monitor health, performance, usage

package/interfaces/tui.md

@@ -0,0 +1,242 @@
+# TUI Agent Guidelines
+
+Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
+
+**Scope:** Terminal User Interfaces (TUIs) with interactive components, event handling, layout management.
+
+## Framework Selection
+
+**Python Projects:**
+- ! Use Textual (https://textual.textualize.io/)
+- Rich integration, reactive system, CSS-like styling, component model
+- Examples: process monitors, log viewers, configuration tools, dev dashboards
+
+**TypeScript/JavaScript Projects:**
+- ! Use ink (https://github.com/vadimdemedes/ink)
+- React-like component model, hooks, JSX/TSX support
+- Examples: CLI installers, build watchers, interactive prompts
+
+**Other Languages:**
+- Rust: ratatui + crossterm
+- Go: bubbletea + lipgloss
+
+## Core Architecture
+
+**Component Structure:**
+- ! Single responsibility per component
+- ! Composable widgets (App → Screens → Widgets → Primitives)
+- ! Clear separation: UI logic vs business logic
+- ~ Keep components <150 lines; split if larger
+
+**State Management:**
+- ! Reactive data binding (Textual reactive properties, ink useState/useReducer)
+- ! Centralized state for shared data
+- ! Immutable updates (return new state, don't mutate)
+- ⊗ Global mutable state outside framework
+
+**Event Handling:**
+- ! Framework event system (Textual `on_*` methods, ink hooks)
+- ! Async event handlers for I/O operations
+- ! Debounce high-frequency events (key repeats, resize)
+- ~ Command pattern for complex actions
+
+## Textual-Specific (Python)
+
+**Components:**
+- ! Inherit from `Widget`, `Screen`, or primitives (`Static`, `Button`, `Input`, `DataTable`, etc.)
+- ! Use `reactive` for reactive properties: `count = reactive(0)`
+- ! Implement lifecycle methods: `compose()`, `on_mount()`, `on_show()`
+
+**Styling:**
+- ! CSS-like styling in `*.tcss` files or inline
+- ! Use design tokens for consistency: `$primary`, `$surface`, etc.
+- ! Responsive layouts: `grid`, `horizontal`, `vertical` containers
+- ~ Dark/light theme support via CSS variables
+
+**Async Patterns:**
+- ! Use `async def` for I/O operations
+- ! Workers for background tasks: `self.run_worker(task, exclusive=True)`
+- ! Timers for periodic updates: `self.set_interval(1.0, self.update)`
+- ⊗ Blocking operations in event handlers
+
+**Key Bindings:**
+```python
+BINDINGS = [
+    Binding("q", "quit", "Quit"),
+    Binding("ctrl+c", "quit", "Quit", show=False),
+]
+```
+
+## ink-Specific (TypeScript)
+
+**Components:**
+- ! Functional components with hooks
+- ! `useState` for local state, `useReducer` for complex state
+- ! `useEffect` for side effects (cleanup on unmount)
+- ! `useInput` for key handling
+
+**Layout:**
+- ! Flexbox-based layout via `<Box>` component
+- ! Props: `flexDirection`, `justifyContent`, `alignItems`, `padding`, `margin`
+- ! `<Text>` for content, `<Newline>` for line breaks
+- ~ Use `<Static>` for non-interactive output above interactive UI
+
+**Hooks Pattern:**
+```typescript
+const [state, setState] = useState(initialState);
+useEffect(() => { /* setup */ return () => { /* cleanup */ }; }, [deps]);
+useInput((input, key) => { if (key.escape) process.exit(0); });
+```
+
+**Rendering:**
+- ! Use `render(<App />)` from ink
+- ! `waitUntilExit()` for async CLIs
+- ⊗ Multiple render calls to same stdout
+
+## Performance
+
+**Rendering:**
+- ! Throttle updates (max 30-60 FPS): `@throttle(0.033)` (Textual) or debounce (ink)
+- ! Virtual scrolling for large lists (Textual `DataTable`, ink custom)
+- ~ Lazy loading for expensive components
+- ⊗ Re-render entire tree on every state change
+
+**Data Handling:**
+- ! Paginate or stream large datasets
+- ! Background workers for heavy computation
+- ~ Memoize expensive calculations (ink `useMemo`)
+- ⊗ Load unbounded data into memory
+
+## Testing
+
+See testing.md for universal requirements (! ≥85% coverage, fuzzing, integration tests).
+
+**Textual Testing:**
+```python
+async def test_app():
+    app = MyApp()
+    async with app.run_test() as pilot:
+        await pilot.press("j", "j", "k")  # Simulate keys
+        assert app.query_one("#status").renderable == "Expected"
+        await pilot.click("#button")
+```
+
+**ink Testing:**
+- Use `ink-testing-library` or snapshot tests
+- Render component, check output string, simulate stdin
+```typescript
+const {lastFrame, stdin} = render(<App />);
+expect(lastFrame()).toContain("Welcome");
+stdin.write("j"); // Simulate keypress
+```
+
+**Integration:**
+- ! Test full user workflows (navigation, input, output)
+- ! Test error states (network failures, invalid input)
+- ~ Snapshot tests for layout regression detection
+- ⊗ Unit test UI without framework test harness
+
+## Error Handling
+
+**Display:**
+- ! User-friendly error messages in UI (modal, notification, status bar)
+- ! Log technical details to file (don't dump stack traces in TUI)
+- ! Recoverable errors: show message, continue
+- ! Fatal errors: show message, wait for keypress, exit gracefully
+
+**Patterns:**
+```python
+# Textual
+try:
+    await risky_operation()
+except Exception as e:
+    self.notify(f"Error: {e}", severity="error")
+    log.exception("Detailed error")
+```
+```typescript
+// ink
+try {
+  await riskyOperation();
+} catch (error) {
+  setError(error.message); // Display in UI
+  console.error(error); // Log to stderr
+}
+```
+
+## Accessibility
+
+- ! Keyboard navigation for all interactive elements
+- ! Clear focus indicators (highlight, border change)
+- ! ARIA-like labels for screen reader compatibility (Textual has some support)
+- ~ Support standard shortcuts: Tab (next), Shift+Tab (prev), Enter (activate), Esc (cancel)
+- ~ Configurable key bindings
+
+## Commands & Tasks
+
+```bash
+task tui:dev          # ! Dev mode with hot reload
+task tui:run          # Run TUI app
+task tui:test         # Run TUI tests (≥85% coverage)
+task tui:console      # Console for debugging (Python/Textual only)
+```
+
+## Best Practices
+
+**Design:**
+- ! Responsive to terminal resize events
+- ! Graceful degradation for small terminals (min width/height checks)
+- ~ Consistent color scheme (use theme/design tokens)
+- ~ Status bar for context (current mode, help hints)
+- ≉ Assume 80x24 terminal without checking
+
+**User Experience:**
+- ! Instant visual feedback for user actions
+- ! Loading indicators for async operations
+- ! Help screen (show key bindings, context-sensitive help)
+- ~ Exit confirmation for destructive actions
+- ⊗ Silent failures (always show feedback)
+
+**Code Organization:**
+```
+src/
+├── app.py|tsx           # Main app component
+├── screens/             # Top-level screens
+├── widgets/             # Reusable widgets
+├── styles.tcss          # Textual styles (Python)
+├── theme.ts             # Theme constants (TypeScript)
+└── __tests__/           # Tests
+```
+
+## Anti-Patterns
+
+⊗ Blocking I/O in render or event handlers → use async/workers
+⊗ Direct terminal manipulation (print, ANSI codes) → use framework
+⊗ Polling for state changes → use reactive/event-driven patterns
+⊗ Hardcoded layouts → use flexible containers
+⊗ Unhandled exceptions in UI code → wrap in try/catch, show errors
+⊗ Testing by manual inspection only → automate with framework test tools
+
+## Documentation
+
+! Add to README.md:
+- Framework choice (Textual or ink)
+- `task tui:dev` for development
+- `task tui:run` to launch
+- Key bindings reference
+- Screenshot or demo GIF
+
+## References
+
+**Textual:**
+- Docs: https://textual.textualize.io/
+- Widget reference: https://textual.textualize.io/widget_gallery/
+- Tutorial: https://textual.textualize.io/tutorial/
+
+**ink:**
+- Docs: https://github.com/vadimdemedes/ink
+- Components: https://github.com/vadimdemedes/ink#built-in-components
+- Testing: https://github.com/vadimdemedes/ink-testing-library
+
+**Examples:**
+- Textual: https://github.com/Textualize/textual/tree/main/examples
+- ink: https://github.com/vadimdemedes/ink/tree/master/examples

package/interfaces/web.md

@@ -0,0 +1,123 @@
+# UI Skills
+
+Opinionated constraints for building better interfaces with agents.
+
+Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
+Tags: R+TW=React+Tailwind; htmx+BS=htmx+Bootstrap; CSS=plain CSS; JS=vanilla JS.
+
+## Framework Selection
+
+- ! Choose the stack that fits the project's complexity and team expertise
+- ~ React + Tailwind for SPAs and complex interactive UIs
+- ~ htmx + Bootstrap for server-rendered pages with progressive enhancement
+- ~ Vanilla JS + CSS for simple pages or when frameworks are overkill
+
+## Stack
+
+- ! Start from platform defaults (spacing/radius/shadows) before custom. (R+TW: Tailwind defaults; htmx+BS: Bootstrap utilities before custom CSS)
+- ! If JS animation is required, use established tooling. (React: motion/react (ex framer-motion); JS: Web Animations API or CSS transitions; htmx: CSS transitions or htmx swap animations)
+- ~ Use entrance/micro-animation primitives. (R+TW: tw-animate-css; CSS: @keyframes + prefers-reduced-motion)
+- ! Use class/style composition helpers. (React: cn=clsx+tailwind-merge; JS/htmx: templates/class builders)
+
+## Components
+
+- ! Use accessible primitives for keyboard/focus behavior. (React: Base UI / React Aria / Radix; JS/htmx: native HTML or ARIA-compliant custom elements)
+- ! Prefer project primitives first.
+- ⊗ Mix primitive systems within the same interaction surface.
+- ~ Prefer well-maintained primitives if compatible. (React: Base UI for new primitives if it fits)
+- ! Add `aria-label` to icon-only buttons.
+- ⊗ Rebuild keyboard/focus behavior by hand unless explicitly requested.
+
+## Interaction
+
+- ! Confirm destructive/irreversible actions. (React: AlertDialog; htmx+BS: modal confirmation)
+- ~ Use structural skeletons for loading (not spinners). (htmx: loading skeleton in placeholder)
+- ! Respect viewport sizing. (R+TW: h-dvh not h-screen; CSS: use dvh for fixed heights)
+- ! Respect safe-area-inset for fixed elements.
+- ! Show errors next to where the action happens.
+- ⊗ Block paste in input/textarea.
+
+## Animation
+
+- ⊗ Add animation unless explicitly requested.
+- ! Animate compositor props only: transform, opacity. (React: motion/react; CSS: @keyframes on transform/opacity only)
+- ⊗ Animate layout props: width, height, position, margin, padding.
+- ~ Avoid paint props (background, color) except small/local UI (text/icons).
+- ~ Use ease-out on entrance.
+- ⊗ Exceed 200ms for interaction feedback.
+- ! Pause looping animations when off-screen. (React: whileInView; CSS/JS: Intersection Observer or animation-timeline)
+- ! Respect prefers-reduced-motion. (React: useMediaQuery or CSS media query; CSS: @media (prefers-reduced-motion: reduce))
+- ⊗ Introduce custom easing unless explicitly requested.
+- ~ Avoid animating large assets or full-screen surfaces.
+
+## Typography
+
+- ! Headings: balance; body: pretty. (R+TW: text-balance/text-pretty; CSS: text-wrap: balance/pretty)
+- ! Numeric data: tabular figures. (R+TW: tabular-nums; CSS: font-variant-numeric: tabular-nums)
+- ~ Dense UI: truncate/clamp. (R+TW: truncate or line-clamp-\*; CSS: text-overflow: ellipsis or -webkit-line-clamp)
+- ⊗ Modify letter-spacing unless explicitly requested.
+
+## Layout
+
+- ! Fixed z-index scale. (R+TW: z-0/10/20; no arbitrary z-\*; CSS: define scale in variables/tokens)
+- ~ Square elements: use square utilities. (R+TW: size-_ not w-_+h-\*; CSS: aspect-ratio: 1 or paired width/height)
+- ! Respect safe areas (notches/rounded corners).
+
+## Performance
+
+- ⊗ Animate heavy filters/backdrops. (React: avoid animating blur() or backdrop-filter)
+- ⊗ Apply will-change outside an active animation. (React: remove will-change when animation completes)
+- ⊗ Use side-effect hooks for logic expressible as render logic. (React: don't use useEffect when render logic works)
+
+## Design
+
+- ⊗ Use gradients unless explicitly requested.
+- ⊗ Use overly decorative effects (glows) as primary affordances. (R+TW: no glow effects / shadow-glow as primary UI)
+- ~ Use default shadow/spacing scales unless explicitly requested. (R+TW: Tailwind default shadow scale; CSS: system design shadow tokens)
+- ~ Use SVG whenever possible for graphics.
+- ! Empty states: one clear next action.
+- ~ Limit accent color usage to one per view.
+- ~ Use existing theme tokens before introducing new ones. (R+TW: use Tailwind/theme colors before new tokens)
+
+## Authentication
+
+- ! Support SSO. (OIDC/SAML based on tenant/provider needs)
+- ! Support WebAuthn for either 2FA or passwordless authentication.
+- ! Preserve and validate post-auth return paths so users return to intended destinations.
+- ~ Keep authentication flows progressive and low-friction (minimal fields first, optional profile completion later).
+- ~ Provide clear recovery options (passkey fallback, backup codes, account recovery) without dead ends.
+- ! Enforce phishing-resistant MFA for privileged roles and high-risk actions.
+- ! Rate-limit and lock out abusive auth attempts with anomaly detection and alerting.
+- ! Use short-lived access tokens, rotate refresh tokens, and support immediate server-side session revocation.
+
+## Theming
+
+- ~ Web apps support theming.
+- ! Web apps support dark and light modes.
+- ! Respect system color-scheme preference on first visit; persist explicit user override.
+- ~ Build themes from design tokens (color, spacing, typography) rather than per-component hardcoding.
+
+---
+
+## Testing
+
+See [testing.md](../coding/testing.md) for universal requirements.
+
+- ! Test component interactions and state changes
+- ! Test accessibility (keyboard nav, screen readers)
+- ~ Snapshot test UI components
+- ~ Visual regression testing
+
+**Browser Testing:**
+- ~ Use chrome-devtools MCP server for development, debugging, integration tests
+- Tools: click, evaluate_script, get_console_messages, take_screenshot, wait_for, list_pages, navigate_page, take_snapshot
+
+**⚠️ IMPORTANT**: If chrome-devtools MCP is not installed, STRONGLY install it now:
+```bash
+npx @modelcontextprotocol/create-server chrome-devtools
+```
+This MCP provides 26 browser automation tools essential for effective web development and testing.
+
+---
+
+Adapted from https://www.ui-skills.com/