@zigrivers/scaffold 2.28.1 → 2.38.0

package/knowledge/core/user-story-innovation.md

@@ -4,6 +4,19 @@ description: Techniques for discovering UX enhancements and innovation opportuni
 topics: [innovation, ux-enhancements, user-stories, gap-analysis, differentiators]
 ---
 
+# User Story Innovation
+
+## Summary
+
+- **Scope**: UX-level improvements to existing features only (smart defaults, error handling, accessibility, progressive disclosure, AI-native enhancements). Feature-level innovation belongs in PRD innovation.
+- **High-value low-effort patterns**: Smart defaults, inline validation, keyboard shortcuts, progressive disclosure, leveraging existing data, undo/redo, and batch operations.
+- **Differentiators**: "Wow" moments, AI-native features (natural language search, auto-categorization, smart suggestions), and personalization without configuration.
+- **Defensive gaps**: Accessibility (WCAG AA minimum), mobile responsiveness, offline/degraded mode, performance under load, error recovery, and empty states.
+- **Evaluation framework**: Assess cost (trivial/moderate/significant) and impact (nice-to-have/noticeable/differentiator). Must-have for v1 = high impact + trivial or moderate cost.
+- **Integration**: Approved innovations become additional acceptance criteria, new stories, or modified story scope. All must be traceable to PRD requirements.
+
+## Deep Guidance
+
 ## Scope Boundary
 
 This knowledge covers UX-level improvements only — making existing features better, not adding new features. Feature-level innovation belongs in PRD innovation (`innovate-prd`). If an enhancement requires a new PRD section, it is out of scope for user story innovation.

package/knowledge/core/ux-specification.md

@@ -4,6 +4,19 @@ description: UX documentation patterns — user flows, interaction states, compo
 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

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

package/knowledge/execution/tdd-execution-loop.md

@@ -0,0 +1,172 @@
+---
+name: tdd-execution-loop
+description: Red-green-refactor execution cycle for AI agents
+topics: [tdd, execution, testing, workflow]
+---
+
+# TDD Execution Loop
+
+Expert knowledge for the core TDD execution loop that AI agents follow during implementation. This defines the disciplined red-green-refactor cycle, commit timing, and test-first practices that ensure every change is verified before it ships.
+
+## Summary
+
+### Red-Green-Refactor Cycle
+
+```
+  RED         GREEN        REFACTOR
+  Write a  →  Write the  →  Clean up
+  failing     minimal       without
+  test        code to       changing
+              pass it       behavior
+```
+
+Each cycle produces one small, verified increment of functionality.
+
+### Commit Timing
+
+- **Commit after green** — every passing test is a safe checkpoint
+- **Commit after refactor** — clean code locked in before the next feature
+- **Never commit red** — a failing test in history breaks bisect and reverts
+
+### Test-First Discipline
+
+- Always write the test before the implementation
+- Verify the test actually fails (red) before writing production code
+- A test that never failed might not be testing anything meaningful
+
+## Deep Guidance
+
+### Red-Green-Refactor Cycle — Extended
+
+#### Red Phase: Write a Failing Test
+
+Write a test that describes the next small piece of behavior you want to add. Run it and confirm it fails. The failure message should clearly indicate what is missing.
+
+**Key rules:**
+- The test must fail for the right reason (missing function, wrong return value — not a syntax error or import failure)
+- Write only one test at a time — don't batch multiple behaviors into a single red phase
+- The test name should describe the expected behavior: `returns 404 when user not found`, not `test user endpoint`
+
+#### Green Phase: Minimal Implementation
+
+Write the smallest amount of production code that makes the failing test pass. Do not add logic for future tests, handle edge cases you haven't tested yet, or optimize.
+
+**Key rules:**
+- If you can make the test pass by returning a hard-coded value, that's valid — the next test will force generalization
+- Don't refactor during the green phase — just make it pass
+- Run the full relevant test suite (not just the new test) to confirm you haven't broken anything
+
+#### Refactor Phase: Clean Up
+
+With all tests green, improve the code's structure, readability, and design without changing its behavior. The tests are your safety net.
+
+**Common refactors:**
+- Extract duplicate code into helper functions
+- Rename variables and functions for clarity
+- Simplify conditionals
+- Move code to better locations (closer to where it's used)
+
+**Key rules:**
+- All tests must remain green throughout refactoring
+- If a refactor breaks a test, undo and take a smaller step
+- Commit after a successful refactor before starting the next red phase
+
+### When to Commit
+
+| Event | Commit? | Why |
+|-------|---------|-----|
+| Test goes green | Yes | Safe checkpoint with verified behavior |
+| Refactor complete, tests still green | Yes | Lock in clean code |
+| Test is red (failing) | No | Broken state in history breaks bisect |
+| Mid-implementation, nothing passes yet | No | Partial work has no verified value |
+| Multiple tests green at once | Yes | But prefer smaller commits |
+
+Ideal commit cadence: every 5-15 minutes during active TDD. If you haven't committed in 30 minutes, you're taking too large a step.
+
+### PR Creation Patterns
+
+- **One PR per task** — a PR should map to a single task, story, or unit of work
+- **Descriptive titles** — `feat(auth): add password reset flow` not `auth changes`
+- **Test evidence in description** — include which tests were added, what they cover, and that they pass
+- **Link to task ID** — reference the task, story, or issue that motivated the work
+- **Small PRs** — prefer 50-200 lines changed; split larger work into sequential PRs
+
+### Test-First Discipline — Extended
+
+**Why test-first matters:**
+- Forces you to think about the interface before the implementation
+- Prevents writing untestable code (if you can't test it first, the design needs work)
+- Creates a failing test that proves your test actually exercises the code path
+- Produces a test suite where every test has been observed to fail — higher confidence
+
+**Common violations to avoid:**
+- Writing implementation first, then adding tests after (tests may not cover the actual behavior)
+- Writing a test that passes immediately (it might be testing the wrong thing)
+- Skipping the red step "because you know the implementation is correct" (hubris)
+
+### Handling Flaky Tests
+
+Flaky tests — tests that pass sometimes and fail other times — are bugs. Treat them with urgency.
+
+**Investigation steps:**
+1. Run the test in isolation 10 times to confirm flakiness
+2. Check for common causes: time-dependent logic, race conditions, shared mutable state, network calls, random data
+3. Fix the root cause, don't add retries
+
+**Never:**
+- Add `retry(3)` to make a flaky test pass — this hides the bug
+- Mark as `skip` without filing a tracking issue
+- Ignore flaky tests in CI — they erode trust in the entire suite
+
+### Slow Test Suites
+
+When the full test suite takes too long for rapid TDD:
+
+**During development:**
+- Run only the focused subset (tests for the module you're changing)
+- Use test runner watch mode to re-run on file change
+- Tag tests by level (unit, integration, e2e) and run only unit during red-green-refactor
+
+**Before PR creation:**
+- Run the full test suite locally
+- Confirm CI will run the complete suite
+- Don't submit a PR if you haven't verified the full suite passes
+
+**Reducing suite time:**
+- Move logic tests from integration/e2e to unit level
+- Parallelize test execution
+- Use transaction rollback instead of database recreation
+- Profile the slowest tests and optimize or split them
+
+### Test Isolation
+
+Each test must be independent — it should pass or fail regardless of what other tests run before it, after it, or alongside it.
+
+**Rules:**
+- No shared mutable state between tests (global variables, class-level state, database rows from a previous test)
+- Each test sets up its own preconditions and cleans up after itself
+- Tests should pass when run individually, in any order, or in parallel
+- Use `beforeEach`/`setUp` for common setup, not test-to-test data flow
+- Avoid `beforeAll`/`setUpClass` unless the shared resource is truly read-only
+
+**Detecting isolation violations:**
+- Run tests in random order — if they fail, they have hidden dependencies
+- Run a single test in isolation — if it fails only when run alone, it depends on setup from another test
+
+### When to Stop and Ask
+
+TDD assumes clear requirements. When requirements are unclear, continuing to write tests is wasteful. Stop and ask when:
+
+- **Unclear requirements** — the acceptance criteria are ambiguous or contradictory
+- **Architectural ambiguity** — you're unsure which module should own the behavior
+- **Conflicting documentation** — the PRD says one thing, the user stories say another
+- **Scope creep** — the task is growing beyond what was originally planned
+- **Blocked by another task** — you need output from a task that hasn't been completed yet
+- **Unfamiliar domain** — you don't understand the business rules well enough to write a meaningful test
+
+Document what you know, what you don't, and what decision you need — then ask.
+
+## See Also
+
+- [testing-strategy](../core/testing-strategy.md) — Test pyramid, coverage strategy, quality gates
+- [task-claiming-strategy](./task-claiming-strategy.md) — Task selection and dependency awareness