@zigrivers/scaffold 2.1.2 → 2.38.0

package/knowledge/core/ux-specification.md

@@ -1,9 +1,22 @@
 ---
 name: ux-specification
-description: UX documentation patterns, design systems, accessibility, and component architecture
-topics: [ux, design-system, accessibility, wireframes, user-flows, responsive-design, components]
+description: UX documentation patterns — user flows, interaction states, component architecture, accessibility, and responsive behavior
+topics: [ux, accessibility, wireframes, user-flows, responsive-design, components, interaction-states]
 ---
 
+# UX Specification
+
+## Summary
+
+- **User flow documentation**: Map each story's Given/When/Then scenarios to screen states and transitions. Document entry points, preconditions, happy path, decision points, error paths, empty states, and exit points.
+- **Component architecture**: Organize components as atoms (base), molecules (composite), organisms (feature), templates (layouts), and pages. Define prop/data flow with top-down props and events/callbacks up.
+- **Design system reference**: Consume design tokens from `docs/design-system.md` by name (e.g., `--color-error`, `--space-4`). Never hard-code values.
+- **Accessibility**: Target WCAG AA as baseline. Keyboard navigation for all interactive elements, semantic HTML, screen reader support with ARIA, 4.5:1 color contrast, and proper focus management.
+- **Responsive design**: Mobile-first breakpoints (mobile < 640px, tablet 640-1024px, desktop 1024-1280px, large > 1280px). Touch targets minimum 44x44px. Document layout behavior per breakpoint.
+- **Common pitfalls**: Designing for happy path only, accessibility as afterthought, missing loading states, breaking text on resize, and modal abuse for content that should be pages.
+
+## Deep Guidance
+
 ## User Flow Documentation
 
 ### Journey Mapping
@@ -128,148 +141,11 @@ Define how data flows through the component tree:
 
 **Promotion rule:** A component starts as page-specific. When a second feature needs the same component, promote it to shared. Don't pre-optimize by making everything shared from the start.
 
-## Design System
-
-A design system is the set of constraints and building blocks that ensure visual consistency across the entire application. It includes design tokens, base components, and usage patterns.
-
-### Design Tokens
-
-Design tokens are the atomic values that define the visual language. They are variables, not hard-coded values. Every visual property in the application references a token.
-
-**Color tokens:**
-
-```
---color-primary: #2563EB          // Main brand/action color
---color-primary-hover: #1D4ED8    // Interactive state
---color-primary-light: #DBEAFE    // Backgrounds, subtle highlights
-
---color-secondary: #7C3AED        // Supporting brand color
-
---color-neutral-50: #FAFAFA       // Lightest background
---color-neutral-100: #F5F5F5      // Card backgrounds
---color-neutral-200: #E5E5E5      // Borders
---color-neutral-400: #A3A3A3      // Muted text, placeholders
---color-neutral-700: #404040      // Secondary text
---color-neutral-900: #171717      // Primary text
-
---color-success: #16A34A          // Success states, positive actions
---color-warning: #CA8A04          // Warning states, caution
---color-error: #DC2626            // Error states, destructive actions
---color-info: #2563EB             // Informational states
-```
-
-**Typography tokens:**
-
-```
---font-family: 'Inter', system-ui, sans-serif
-
---text-xs: 0.75rem    // 12px — fine print, labels
---text-sm: 0.875rem   // 14px — secondary text, table cells
---text-base: 1rem     // 16px — body text
---text-lg: 1.125rem   // 18px — subheadings
---text-xl: 1.25rem    // 20px — section titles
---text-2xl: 1.5rem    // 24px — page titles
---text-3xl: 1.875rem  // 30px — hero text
-
---font-weight-normal: 400
---font-weight-medium: 500
---font-weight-semibold: 600
---font-weight-bold: 700
-
---line-height-tight: 1.25
---line-height-normal: 1.5
---line-height-relaxed: 1.75
-```
-
-**Spacing tokens:**
-
-```
---space-1: 0.25rem    // 4px  — tight gaps (icon to label)
---space-2: 0.5rem     // 8px  — compact spacing (list items)
---space-3: 0.75rem    // 12px — default padding (buttons, inputs)
---space-4: 1rem       // 16px — standard spacing (form fields)
---space-6: 1.5rem     // 24px — section padding
---space-8: 2rem       // 32px — large gaps
---space-12: 3rem      // 48px — section separators
---space-16: 4rem      // 64px — page-level spacing
-```
-
-**Border and shadow tokens:**
-
-```
---radius-sm: 0.25rem   // 4px  — subtle rounding (tags, badges)
---radius-md: 0.5rem    // 8px  — standard rounding (cards, inputs, buttons)
---radius-lg: 0.75rem   // 12px — prominent rounding (modals, panels)
---radius-full: 9999px  // Pill shapes, avatars
-
---shadow-sm: 0 1px 2px rgba(0,0,0,0.05)
---shadow-md: 0 4px 6px rgba(0,0,0,0.07)
---shadow-lg: 0 10px 15px rgba(0,0,0,0.1)
---shadow-xl: 0 20px 25px rgba(0,0,0,0.1)
-```
-
-### Dark Mode
-
-When dark mode is required, define a parallel set of semantic tokens that switch based on the color scheme:
-
-```css
-:root {
-  --bg-primary: var(--color-neutral-50);
-  --bg-card: white;
-  --text-primary: var(--color-neutral-900);
-  --text-secondary: var(--color-neutral-700);
-  --border-default: var(--color-neutral-200);
-}
-
-@media (prefers-color-scheme: dark) {
-  :root {
-    --bg-primary: var(--color-neutral-900);
-    --bg-card: var(--color-neutral-800);
-    --text-primary: var(--color-neutral-50);
-    --text-secondary: var(--color-neutral-400);
-    --border-default: var(--color-neutral-700);
-  }
-}
-```
-
-Use semantic tokens (`--bg-primary`, `--text-primary`) in components, not raw color tokens. This makes dark mode automatic.
-
-### Base Components
+## Design System Reference
 
-Define the standard appearance and behavior for every common component:
+Design tokens (colors, typography, spacing, borders, shadows), base component visual specs, dark mode patterns, and the pattern library are defined in `docs/design-system.md`. The UX specification consumes these tokens — it does not redefine them.
 
-**Buttons:**
-- Variants: Primary (solid fill), Secondary (subtle fill), Outline (border only), Ghost (no border), Destructive (red/danger)
-- Sizes: sm (28px height), md (36px height), lg (44px height)
-- States: default, hover, active, focused, disabled, loading
-- Loading state replaces label with spinner, disables interaction
-
-**Form elements:**
-- All inputs: border, focus ring, error state (red border + error message below), disabled state (reduced opacity)
-- Labels: always visible (never placeholder-only), required indicator (asterisk or "(required)")
-- Help text: below input, muted color, explains what the field expects
-- Error messages: below input, error color, describes what went wrong and how to fix it
-
-**Cards:**
-- Default: white/card background, subtle shadow or border, rounded corners
-- Interactive: hover state (shadow increase or border color change), cursor pointer
-- Header/footer sections: visually separated, structured content areas
-
-**Feedback:**
-- Toast notifications: temporary, non-blocking, auto-dismiss (with manual dismiss option)
-- Alert banners: persistent until dismissed, full-width or contained within a section
-- Empty states: illustration or icon, explanatory text, call-to-action button
-- Loading: skeleton loaders (preferred over spinners for content areas), spinner for actions
-
-### Pattern Library
-
-Document recurring UI patterns with implementation guidance:
-
-- **Search with autocomplete:** Debounced input, dropdown results, keyboard navigation, "no results" state
-- **Confirmation dialogs:** Before destructive actions, clearly state what will happen, "Cancel" as primary action (preventing accidents)
-- **Inline editing:** Click to edit, Enter to save, Escape to cancel, loading indicator during save
-- **Bulk actions:** Select all, individual select, action toolbar appears when items selected
-- **Wizard/stepper:** Progress indicator, back/next navigation, save progress between steps
+When specifying component behavior in user flows and interaction states, reference design system tokens by name (e.g., `--color-error`, `--space-4`) rather than hard-coding values. If `docs/design-system.md` does not exist yet, note which tokens are needed and defer visual decisions to the design-system step.
 
 ## Accessibility
 
@@ -367,14 +243,8 @@ Mobile touch targets must be at least 44x44px (Apple) or 48x48px (Material). Ens
 
 **Accessibility as afterthought.** Building the entire UI first, then trying to add accessibility. Results in ARIA hacks layered on top of inaccessible markup. Fix: use semantic HTML from the start. Test keyboard navigation during development, not after.
 
-**Inconsistent spacing and typography.** Five different font sizes that are all "kind of like body text." Spacing that varies randomly between 12px and 17px with no system. Fix: define a spacing scale and type scale in the design system. Only use values from the scale.
-
-**Placeholder text as labels.** Using placeholder text instead of labels for form fields. Placeholders disappear when the user starts typing, leaving them with no indication of what the field expects. Fix: always use visible labels. Placeholders are supplementary hints, not replacements for labels.
-
 **Missing loading states.** The page shows nothing (white screen) while data loads, then content pops in. Users think the app is broken. Fix: use skeleton loaders that match the shape of the content being loaded.
 
-**Ignoring touch targets on mobile.** Tiny links and buttons that require precise finger tapping. Fix: ensure all interactive elements meet minimum 44x44px touch target size on mobile.
-
 **Breaking text on resize.** Content that looks fine at the design width but overflows, truncates, or overlaps at other widths. Fix: test with variable-length content and multiple viewport widths. Use CSS that handles overflow gracefully (truncation with ellipsis, wrapping, or scrolling).
 
 **Modal abuse.** Using modals for content that should be a page (long forms, complex workflows, multi-step processes). Modals are for brief, focused interactions. Fix: if the modal content would benefit from a back button or URL, it should be a page.

package/knowledge/execution/enhancement-workflow.md

@@ -0,0 +1,201 @@
+---
+name: enhancement-workflow
+description: Discovery and implementation workflow for adding features to existing projects
+topics: [enhancement, features, planning, discovery]
+---
+
+# Enhancement Workflow
+
+Expert knowledge for discovering, planning, and implementing enhancements to existing projects. Covers the four-phase discovery flow, impact analysis, documentation updates, and task creation patterns.
+
+## Summary
+
+### 4-Phase Discovery Flow
+
+1. **Discovery** — Understand the problem space, review existing docs, challenge scope, assess impact
+2. **Documentation** — Update project docs with the new feature, add user stories
+3. **Task Creation** — Break the enhancement into implementable tasks with dependencies
+4. **Summary** — Produce an enhancement summary with implementation order and follow-up suggestions
+
+### Impact Analysis
+
+Before committing to an enhancement, assess its fit within the existing architecture, its scope relative to the project, and its technical impact on existing modules.
+
+### Documentation Updates
+
+Every enhancement must update the project's planning and story documents with traceability markers so the change history is auditable.
+
+### Task Creation
+
+One task per user story for small/medium enhancements. Larger enhancements decompose into data model, backend, frontend, and polish phases with explicit dependencies.
+
+## Deep Guidance
+
+### Phase 1: Discovery
+
+Discovery is the most important phase. Skipping it leads to scope creep, architectural misalignment, and wasted implementation effort.
+
+#### Review Existing Documentation
+
+Read these documents in order before proposing any changes:
+
+1. **Product vision** (`docs/vision.md` or equivalent) — understand the project's purpose and direction
+2. **PRD** (`docs/prd.md`) — understand existing requirements and constraints
+3. **User stories** (`docs/user-stories.md`) — understand who uses the system and how
+4. **Architecture** (`docs/architecture.md` or ADRs) — understand the technical structure
+5. **Coding standards** (`docs/coding-standards.md`) — understand conventions you must follow
+6. **TDD standards** (`docs/tdd-standards.md`) — understand testing expectations
+7. **Project structure** (`docs/project-structure.md`) — understand where code lives
+8. **Source code** — read the modules most relevant to the enhancement
+
+#### Understand the Problem
+
+- What user problem does this enhancement solve?
+- Is the problem validated (user feedback, metrics, strategic direction)?
+- Are there existing features that partially solve this problem?
+- Could an existing feature be extended instead of building something new?
+
+#### Challenge Scope
+
+Actively resist scope expansion:
+
+- What is the minimum viable version of this enhancement?
+- What can be deferred to a follow-up?
+- Is this a single feature or actually multiple features bundled together?
+- Would a simpler approach solve 80% of the problem?
+
+#### Innovation Pass
+
+After understanding the problem and challenging the scope:
+
+- **Competitive analysis** — how do similar products solve this problem?
+- **Enhancement opportunities** — are there adjacent improvements that are low-effort but high-value?
+- **AI-native possibilities** — can AI capabilities enable a better solution than a traditional approach?
+
+#### Impact Analysis
+
+Assess the enhancement along three dimensions:
+
+**Fit check:**
+- Does this align with the product vision?
+- Does it complement existing features or conflict with them?
+- Is now the right time to build this?
+
+**Scope assessment:**
+- How many modules are affected?
+- How many new entities or data models are needed?
+- Estimate: small (1-2 tasks), medium (3-5 tasks), or large (6+ tasks)
+
+**Technical impact:**
+- Which existing modules need modification?
+- Are there performance implications?
+- Does this affect the API contract (breaking changes)?
+- Are there security implications?
+
+### Phase 2: Documentation
+
+Every enhancement must leave a documentation trail.
+
+#### Update Planning Documents
+
+Update `docs/plan.md` (or equivalent planning document) with the new feature:
+
+- Add a section describing the enhancement
+- Include traceability markers: `[Enhancement added YYYY-MM-DD]`
+- Reference the motivation (user feedback, strategic goal, bug report)
+- List affected modules and components
+
+#### Add User Stories
+
+Add new user stories to `docs/user-stories.md` following INVEST criteria:
+
+- **I**ndependent — can be implemented without other new stories
+- **N**egotiable — details can be discussed during implementation
+- **V**aluable — delivers value to a specific user role
+- **E**stimable — small enough to estimate effort
+- **S**mall — completable in one task or a small number of tasks
+- **T**estable — has clear acceptance criteria that can be automated
+
+**Story format:**
+
+```
+As a [role], I want [capability] so that [benefit].
+
+Acceptance criteria:
+- [ ] Given [context], when [action], then [result]
+- [ ] Given [context], when [action], then [result]
+```
+
+### Phase 3: Task Creation
+
+Convert user stories into implementable tasks.
+
+#### Small/Medium Enhancements (1-5 tasks)
+
+- One task per user story
+- Each task includes: description, acceptance criteria, test expectations, and affected files
+- Set dependencies between tasks where ordering matters
+
+#### Large Enhancements (6+ tasks)
+
+Decompose into implementation phases:
+
+1. **Data model** — schema changes, migrations, entity definitions
+2. **Backend** — API endpoints, business logic, service layer
+3. **Frontend** — UI components, pages, client-side logic
+4. **Polish** — error handling edge cases, performance optimization, documentation
+
+Each phase may contain multiple tasks. Dependencies flow downward: data model before backend, backend before frontend, frontend before polish.
+
+#### Task Creation with Beads
+
+If `.beads/` directory exists:
+
+```bash
+bd create --title "Add user endpoint" --depends-on bd-41
+```
+
+#### Task Creation Without Beads
+
+Add tasks to the project's task tracking system (implementation plan, GitHub Issues, etc.) with:
+- Unique ID
+- Title and description
+- Dependencies (list of blocking task IDs)
+- Acceptance criteria
+- Estimated scope (S/M/L)
+
+### Phase 4: Summary
+
+Produce an enhancement summary that includes:
+
+1. **Enhancement description** — one paragraph summarizing what was planned
+2. **Documentation changes** — list of docs updated and what was added
+3. **Tasks created** — numbered list of tasks with IDs, titles, and dependencies
+4. **Implementation order** — recommended sequence accounting for dependencies
+5. **Follow-up suggestions** — reviews to schedule, related enhancements to consider, risks to monitor
+
+### Complexity Gate
+
+Not every change requires the full enhancement workflow. Use the quick-task path for simple changes and redirect to enhancement workflow when complexity exceeds a threshold.
+
+**Redirect from quick-task to enhancement workflow when any of these are true:**
+
+- Requires updates to planning or design documents
+- Introduces a new user-facing feature (not just a fix or tweak)
+- Affects 3 or more modules
+- Requires new data entities, models, or schema changes
+- Needs 4 or more implementation tasks
+- Changes the API contract in a way that affects consumers
+
+**Stay on quick-task path when:**
+- Bug fix with clear root cause and limited scope
+- Configuration change
+- Documentation-only update
+- Single-file refactor
+- Test addition for existing behavior
+
+## See Also
+
+- [task-decomposition](../core/task-decomposition.md) — Breaking work into implementable tasks
+- [user-stories](../core/user-stories.md) — User story writing patterns
+- [task-claiming-strategy](./task-claiming-strategy.md) — How agents select and claim tasks

package/knowledge/execution/task-claiming-strategy.md

@@ -0,0 +1,130 @@
+---
+name: task-claiming-strategy
+description: Task selection and management patterns for AI agent execution
+topics: [tasks, execution, agents, planning]
+---
+
+# Task Claiming Strategy
+
+Expert knowledge for how AI agents select, claim, and manage tasks during implementation. Covers deterministic selection algorithms, dependency awareness, and multi-agent conflict avoidance patterns.
+
+## Summary
+
+### Task Selection Algorithm
+
+Select the lowest-ID unblocked task. This provides deterministic, conflict-free ordering when multiple agents operate on the same task list.
+
+### Dependency Awareness
+
+Before starting a task, verify all its blockers are resolved. After completing each task, re-check the dependency graph — your completion may have unblocked downstream tasks.
+
+### Multi-Agent Conflict Avoidance
+
+- Claim the task before starting work (branch creation = claim)
+- Communicate via git branches — branch existence signals ownership
+- Detect file overlap in implementation plans before starting — if two tasks modify the same files, they should not run in parallel
+
+## Deep Guidance
+
+### Task Selection — Extended
+
+**The algorithm:**
+1. List all tasks in the backlog
+2. Filter to tasks with status "ready" or "unblocked"
+3. Sort by task ID (ascending)
+4. Select the first task in the sorted list
+5. Claim it by creating a feature branch
+
+**Why lowest-ID first:**
+- Deterministic — two agents independently applying this rule will never pick the same task (the first agent claims it, the second sees it as taken)
+- Dependency-friendly — lower IDs are typically earlier in the plan and have fewer blockers
+- Predictable — humans can anticipate which tasks agents will pick next
+
+**Exceptions:**
+- If the lowest-ID task requires skills or context the agent doesn't have, skip it and document why
+- If a task is labeled "high priority" or "urgent," it takes precedence over ID ordering
+- If a human has assigned a specific task to the agent, honor the assignment
+
+### Dependency Awareness — Extended
+
+**Before starting a task:**
+1. Read the task's dependency list (blockers, prerequisites)
+2. Verify each blocker is in "done" or "merged" state
+3. If any blocker is incomplete, skip this task and select the next eligible one
+4. Pull the latest main branch to ensure you have the outputs from completed blockers
+
+**After completing a task:**
+1. Check which downstream tasks list the completed task as a blocker
+2. If any downstream tasks are now fully unblocked, they become eligible for selection
+3. If you're continuing work, re-run the selection algorithm — the next task may have changed
+
+**Dependency types:**
+- **Hard dependency** — cannot start until blocker is merged (e.g., "implement auth" blocks "implement protected routes")
+- **Soft dependency** — can start with a stub/mock, but must integrate before PR (e.g., "design API" informs "implement client," but the client can start with a contract)
+- **Data dependency** — needs output artifacts from another task (e.g., database schema must exist before writing queries)
+
+### Multi-Agent Conflict Avoidance — Extended
+
+**Claiming a task:**
+- Creating a feature branch (e.g., `bd-42/add-user-endpoint`) is the claim signal
+- Other agents should check for existing branches before claiming the same task
+- If two agents accidentally claim the same task, the one with fewer commits yields
+
+**Detecting file overlap:**
+- Before starting, review the implementation plan for file-level scope
+- If two tasks both modify `src/auth/middleware.ts`, they should not run in parallel
+- When overlap is detected: serialize the tasks (one blocks the other), or split the overlapping file into two files first
+
+**Communication via branches:**
+- Branch exists = task claimed
+- Branch merged = task complete
+- Branch deleted without merge = task abandoned, available for re-claim
+
+### What to Do When Blocked
+
+When no eligible tasks remain (all are blocked or claimed):
+
+1. **Document the blocker** — note which task you need and what it produces
+2. **Skip to the next available task** — don't wait idle; there may be non-dependent tasks further down the list
+3. **Look for prep work** — can you write tests, set up scaffolding, or create stubs for the blocked task?
+4. **If truly nothing is available** — report status and wait for new tasks to become unblocked
+
+**Never:**
+- Start a blocked task hoping the blocker will finish soon
+- Work on the same task as another agent without coordination
+- Sit idle without communicating status
+
+### Conditional Beads Integration
+
+Beads is an optional task-tracking tool. Detect its presence and adapt.
+
+**When `.beads/` directory exists:**
+- Use `bd ready` to list tasks that are ready for work
+- Use `bd claim <id>` to claim a task (if available)
+- Use `bd close <id>` after PR is merged to mark task complete
+- Task IDs come from Beads (`bd-42`, `bd-43`, etc.)
+- Branch naming follows Beads convention: `bd-<id>/<short-desc>`
+
+**Without Beads:**
+- Parse `implementation-plan.md` task list for task IDs and dependencies
+- Or use the project's task tracking system (GitHub Issues, Linear, Jira)
+- Branch naming uses the project's convention (e.g., `feat/US-001-slug`)
+- Task status is tracked via PR state: open PR = in progress, merged PR = done
+
+### Task Completion Criteria
+
+A task is complete when all of the following are true:
+
+1. **All acceptance criteria met** — every criterion listed in the task description is satisfied
+2. **Tests passing** — new tests written for the task, plus the full existing suite, all pass
+3. **PR created** — code is pushed and a pull request is open with a structured description
+4. **CI passing** — all automated quality gates pass on the PR
+5. **No regressions** — existing functionality is unchanged unless the task explicitly modifies it
+
+Only after all five criteria are met should the task be marked as done.
+
+## See Also
+
+- [tdd-execution-loop](./tdd-execution-loop.md) — Red-green-refactor cycle and commit timing
+- [worktree-management](./worktree-management.md) — Parallel agent worktree setup
+- [task-tracking](../core/task-tracking.md) — Task tracking systems and conventions