@zigrivers/scaffold 2.28.1 → 2.38.0

package/pipeline/build/quick-task.md

@@ -0,0 +1,381 @@
+---
+name: quick-task
+description: Create a focused task for a bug fix, refactor, or small improvement
+summary: "Takes a one-off request (bug fix, refactor, performance tweak) and creates a single well-scoped task with acceptance criteria and a test plan — for work outside the main implementation plan."
+phase: "build"
+order: 1550
+dependencies: [implementation-playbook]
+outputs: []
+conditional: null
+stateless: true
+category: pipeline
+knowledge-base: [task-claiming-strategy]
+reads: [create-prd, user-stories, coding-standards, tdd, project-structure]
+argument-hint: "<task description>"
+---
+
+## Purpose
+Create a focused, implementation-ready task for a small, well-defined piece
+of work — a bug fix, refactor, performance improvement, accessibility fix,
+or minor refinement. Produces a single task with clear acceptance criteria
+and a TDD test plan, without the full discovery process of the Enhancement
+prompt.
+
+## Inputs
+- $ARGUMENTS (required) — description of the task to create
+- CLAUDE.md (required) — project conventions, key commands, workflow
+- docs/plan.md (optional) — PRD for requirement context
+- docs/user-stories.md (optional) — existing stories and epics
+- docs/coding-standards.md (required) — code conventions, naming, patterns
+- docs/tdd-standards.md (required) — test categories, mocking strategy, test file locations
+- docs/project-structure.md (required) — where files live, module organization
+- docs/implementation-playbook.md (optional) — quality gates section for project-specific gates
+- tasks/lessons.md (optional) — previous lessons learned
+- .beads/ (conditional) — Beads task tracking if configured
+- Relevant source code — files that will be modified
+
+## Expected Outputs
+- One well-defined task with acceptance criteria, test plan, and implementation notes
+- Task created via Beads (`bd create`) if configured, or documented inline
+- Task summary presented for review
+
+## Quality Criteria
+- (mvp) Complexity gate applied — redirects to Enhancement if scope is too large
+- (mvp) Acceptance criteria are testable Given/When/Then scenarios
+- (mvp) Every criterion maps to at least one test case
+- (mvp) File paths match project-structure.md conventions
+- (mvp) Task uses conventional commit title format: type(scope): description
+- (deep) Duplicate check performed against existing tasks
+- (deep) lessons.md consulted for relevant anti-patterns
+- (deep) Implementation notes reference specific coding standards, not generic advice
+- (deep) Edge cases and regression guards included in acceptance criteria
+
+## Methodology Scaling
+- **deep**: Full complexity gate, duplicate check, lessons.md review, detailed
+  acceptance criteria with edge cases and regression guards, comprehensive
+  test plan with mocking strategy, specific implementation notes referencing
+  coding standards.
+- **mvp**: Complexity gate, basic acceptance criteria (happy path + one edge
+  case), test plan with category and cases, file list. Skip duplicate check
+  and detailed implementation notes.
+- **custom:depth(1-5)**: Depth 1-2: complexity gate, basic AC, test cases,
+  file list. Depth 3: add duplicate check, lessons.md review, regression
+  guards. Depth 4: add mocking strategy, specific coding standard references.
+  Depth 5: full analysis with innovation suggestions and cross-module impact.
+
+## Mode Detection
+This is a stateless execution command. No persistent document is created.
+- Always operates in CREATE MODE — produces a task definition.
+- If Beads is configured, the task is created via `bd create`.
+- If not, the task is documented inline and implementation begins.
+
+## Update Mode Specifics
+Not applicable — this creates a new task each time. If a similar task already
+exists, the duplicate check will surface it for the user to decide.
+
+## Instructions
+
+### The Request
+
+$ARGUMENTS
+
+---
+
+### Phase 0: Complexity Gate
+
+Before proceeding, evaluate whether this task is actually small enough for Quick Task. If **any** of these are true, **stop and redirect**:
+
+1. The change requires updating `docs/plan.md` or `docs/user-stories.md`
+2. The change introduces a new user-facing feature (not a fix or improvement to an existing one)
+3. The change affects 3+ unrelated modules or features
+4. The change requires new data model entities or schema migrations
+5. The change requires competitive analysis or UX research
+6. You estimate 4+ Beads tasks will be needed
+
+**If any criteria match**, tell the user:
+
+> This looks like an enhancement, not a quick task. Redirecting to the Enhancement prompt which handles PRD updates, user stories, and multi-task planning.
+>
+> Run: `/scaffold:new-enhancement <description>`
+
+**Hard stop** — do not continue with the Quick Task flow.
+
+---
+
+### Phase 1: Understand & Contextualize
+
+#### Review Project Context
+Before asking questions, review:
+- `CLAUDE.md` — Project conventions, Key Commands, workflow
+- `docs/coding-standards.md` — Code conventions, naming, patterns
+- `docs/tdd-standards.md` — Test categories, mocking strategy, test file locations
+- `docs/project-structure.md` — Where files live, module organization
+- `tasks/lessons.md` — Previous lessons learned (extract any relevant to this task)
+- If `docs/implementation-playbook.md` exists, check its quality gates section for project-specific gates
+- Relevant source code — Read the files that will be modified
+
+#### Check for Duplicates
+**If Beads:** Run `bd list` and check for existing tasks that overlap with this request. If a matching or overlapping task exists:
+- Tell the user which task(s) already cover this work
+- Ask whether to proceed (create a new task) or use the existing one
+- If proceeding, note the relationship in the new task's description
+
+#### Extract Relevant Lessons
+Review `tasks/lessons.md` for anti-patterns, gotchas, or conventions related to:
+- The area of code being modified
+- The type of change (fix, refactor, perf, etc.)
+- Similar past mistakes to avoid
+
+#### Clarify Ambiguities
+If anything is unclear about the request, use AskUserQuestionTool to batch all questions in a single call. Common clarifications:
+- What is the expected behavior vs. current behavior? (for bugs)
+- What metric or outcome defines success? (for performance)
+- What should NOT change? (for refactors)
+
+---
+
+### Phase 2: Define the Task
+
+#### Categorize
+Determine the task type using conventional commit prefixes:
+- `fix` — Bug fix (something is broken)
+- `feat` — Small feature addition within an existing feature area
+- `perf` — Performance improvement
+- `a11y` — Accessibility fix
+- `refactor` — Code restructuring with no behavior change
+- `chore` — Tooling, dependencies, config
+- `test` — Adding or fixing tests only
+- `style` — Code style, formatting (no logic change)
+
+#### Priority
+Assign priority using Beads conventions:
+- **P0** — Blocking release or breaking production
+- **P1** — Must-have for current milestone
+- **P2** — Should-have (default for most quick tasks)
+- **P3** — Nice-to-have, backlog
+
+#### Acceptance Criteria
+Write 2-5 testable acceptance criteria in Given/When/Then format:
+
+```
+Given <precondition>
+When <action>
+Then <expected result>
+```
+
+Each criterion must be unambiguous — pass/fail should be obvious. Cover:
+- The primary fix or change (happy path)
+- At least one edge case or error state
+- Any regression guard (behavior that must NOT change)
+
+#### Files to Modify
+List exact file paths from `docs/project-structure.md`:
+```
+Files:
+- src/features/auth/services/session.ts (modify)
+- src/features/auth/services/__tests__/session.test.ts (modify)
+```
+
+#### Test Plan
+Reference `docs/tdd-standards.md` for the project's test conventions:
+- **Test category**: unit / integration / e2e (per tdd-standards.md rules for this code area)
+- **Test cases**: Map each acceptance criterion to at least one test case
+- **Mocking**: What to mock and what NOT to mock (per the project's mocking strategy)
+- **Test file location**: Per the project's test file convention
+
+#### Implementation Notes
+- Patterns to follow (reference specific conventions from coding-standards.md)
+- Known gotchas or pitfalls (from lessons.md or code review)
+- What is explicitly out of scope
+
+---
+
+### Phase 3: Create the Task
+
+**If Beads:**
+```bash
+bd create "type(scope): description" -p <priority>
+# Example: bd create "fix(auth): prevent duplicate session creation on rapid re-login" -p 2
+```
+
+**Without Beads:** Document the task inline and proceed directly to implementation.
+
+Then set the task description with the full context from Phase 2. Include all of:
+
+```
+## Acceptance Criteria
+
+- Given <precondition>, when <action>, then <expected result>
+- ...
+
+## Files to Modify
+
+- path/to/file.ts (modify — reason)
+- path/to/test.ts (modify — add test cases)
+
+## Test Plan
+
+**Category**: unit
+**Cases**:
+1. Test description -> validates AC #1
+2. Test description -> validates AC #2
+**Mocking**: Mock X, do not mock Y
+**Location**: path/to/__tests__/file.test.ts
+
+## Implementation Notes
+
+- Follow pattern from [reference]
+- Watch out for [gotcha from lessons.md]
+- Out of scope: [what NOT to do]
+```
+
+---
+
+### Phase 4: Output Summary
+
+Present the task summary:
+
+```
++---------------------------------------------------+
+| Quick Task Created                                |
++----------+----------------------------------------+
+| ID       | <task-id>                              |
+| Title    | type(scope): description               |
+| Priority | P<n>                                   |
+| Status   | open                                   |
++----------+----------------------------------------+
+| Acceptance Criteria                               |
+| - Given... When... Then...                        |
+| - Given... When... Then...                        |
++---------------------------------------------------+
+| Files                                             |
+| - path/to/file.ts                                 |
+| - path/to/test.ts                                 |
++---------------------------------------------------+
+| Test Plan                                         |
+| - Category: unit                                  |
+| - Cases: N test cases                             |
++---------------------------------------------------+
+| Implementation Notes                              |
+| - Key note 1                                      |
+| - Key note 2                                      |
++---------------------------------------------------+
+```
+
+---
+
+### Process Rules
+
+1. **Respect the complexity gate** — If it is bigger than a quick task, redirect immediately. Do not try to squeeze a feature into the quick task format.
+2. **One task only** — Quick Task creates exactly one Beads task. If you need multiple, use the Enhancement prompt.
+3. **Check for duplicates first** — Run `bd list` before creating. Do not create tasks that already exist.
+4. **Lessons.md is required reading** — Always check `tasks/lessons.md` for relevant anti-patterns before defining the task.
+5. **Acceptance criteria drive tests** — Every criterion must map to at least one test case. If you cannot test it, rewrite the criterion.
+6. **Conventional commit titles** — Always use `type(scope): description` format. This feeds directly into commit messages.
+
+---
+
+### When to Use This Prompt
+
+- Bug fixes — something is broken and needs fixing
+- Refactoring — restructuring code without changing behavior
+- Performance improvements — targeted optimizations
+- Accessibility fixes — a11y improvements to existing features
+- Test gaps — adding missing test coverage
+- Chores — dependency updates, config changes, tooling fixes
+- Small refinements — polish within an existing feature
+
+### When NOT to Use This Prompt
+
+- **New features**: Use `/scaffold:new-enhancement` — new features need PRD updates and user stories
+- **Multi-task work**: Use `/scaffold:new-enhancement` — if you need 4+ tasks, it is an enhancement
+- **Initial project setup**: Use the pipeline from `/scaffold:create-prd` forward
+- **Major refactors**: If the refactor touches 3+ unrelated modules, use `/scaffold:new-enhancement` for proper impact analysis
+
+---
+
+### Quality Standards
+
+#### From `docs/tdd-standards.md`:
+- Every acceptance criterion maps to at least one test case
+- Test category (unit/integration/e2e) follows the project's rules for this code area
+- Mocking strategy matches the project's conventions — do not over-mock or under-mock
+
+#### From `docs/coding-standards.md`:
+- File paths match `docs/project-structure.md` conventions
+- Naming follows project patterns
+- Implementation notes reference specific standards, not generic advice
+
+#### Eval Gate
+- If `tests/evals/` exists, run `make eval` (or equivalent eval command from CLAUDE.md Key Commands) as a required pre-commit check
+
+---
+
+### Example
+
+Here is what the output looks like for a typical quick task:
+
+**Request**: "The save button shows a success toast even when the API returns a 409 conflict"
+
+```
++---------------------------------------------------+
+| Quick Task Created                                |
++----------+----------------------------------------+
+| ID       | abc-123                                |
+| Title    | fix(editor): show error toast on       |
+|          | 409 conflict during save               |
+| Priority | P1                                     |
+| Status   | open                                   |
++----------+----------------------------------------+
+| Acceptance Criteria                               |
+| 1. Given the user saves a document,               |
+|    when the API returns 409 Conflict,             |
+|    then an error toast "Save conflict --          |
+|    someone else edited this document"             |
+|    is shown instead of the success toast          |
+| 2. Given the user saves a document,               |
+|    when the API returns 200 OK,                   |
+|    then the success toast still appears           |
+|    (regression guard)                             |
+| 3. Given the user sees a 409 error toast,         |
+|    when they click "Refresh",                     |
+|    then the latest version is fetched             |
++---------------------------------------------------+
+| Files                                             |
+| - src/features/editor/services/save.ts            |
+| - src/features/editor/services/__tests__/         |
+|   save.test.ts                                    |
++---------------------------------------------------+
+| Test Plan                                         |
+| - Category: unit                                  |
+| - Cases: 3 (one per AC)                           |
+| - Mock: HTTP client. Don't mock toast service.    |
++---------------------------------------------------+
+| Implementation Notes                              |
+| - save.ts catches errors but doesn't check        |
+|   status codes -- add 409 handling in catch       |
+| - Follow error handling pattern from              |
+|   src/features/auth/services/login.ts             |
+| - Out of scope: auto-merge or diff view           |
++---------------------------------------------------+
+```
+
+---
+
+## After This Step
+
+When this step is complete, tell the user:
+
+---
+**Quick task created** — Task ready with acceptance criteria, test plan, and implementation notes.
+
+**After implementation:**
+- If this fix revealed a pattern or gotcha: update `tasks/lessons.md`.
+- If this fix changed a convention or pattern: consider updating `docs/implementation-playbook.md` and `docs/coding-standards.md`.
+- After merging, consider running `/scaffold:version-bump` if the change is user-facing.
+
+**Next:** Run `/scaffold:single-agent-start` or `/scaffold:single-agent-resume` to begin implementation (or `/scaffold:multi-agent-start <agent-name>` / `/scaffold:multi-agent-resume <agent-name>` for worktree agents).
+
+**Pipeline reference:** `/scaffold:prompt-pipeline`
+
+---

package/pipeline/build/single-agent-resume.md

@@ -0,0 +1,210 @@
+---
+name: single-agent-resume
+description: Resume single-agent work after a break
+summary: "Recovers context from the previous session — reads lessons learned, checks git state, reconciles merged PRs — and continues the TDD loop from where you left off."
+phase: "build"
+order: 1520
+dependencies: [implementation-playbook]
+outputs: []
+conditional: null
+stateless: true
+category: pipeline
+knowledge-base: [tdd-execution-loop, task-claiming-strategy]
+reads: [coding-standards, tdd, git-workflow]
+---
+
+## Purpose
+Resume single-agent implementation work after a break — whether from a
+context window reset, a paused session, or returning the next day. Recovers
+session context by checking git state, task status, and open PRs, then
+continues the TDD execution loop from where you left off.
+
+## Inputs
+- CLAUDE.md (required) — project conventions, key commands, workflow
+- docs/implementation-playbook.md (required if exists) — primary task execution reference
+- docs/implementation-plan.md (fallback) — task list when no playbook exists
+- docs/onboarding-guide.md (optional) — project context for orientation
+- docs/coding-standards.md (required) — code conventions, naming, patterns
+- docs/tdd-standards.md (required) — test categories, mocking strategy
+- docs/project-structure.md (required) — where files live
+- tests/acceptance/ (optional) — TDD test skeletons
+- tests/evals/ (optional) — project eval checks for quality gates
+- tasks/lessons.md (optional) — previous lessons learned
+- .beads/ (conditional) — Beads task tracking if configured
+
+## Expected Outputs
+- Completed in-progress work from previous session
+- Continued task implementation with passing tests
+- Pull requests for each completed task
+- Updated task status in playbook/plan or Beads
+
+## Quality Criteria
+- (mvp) In-progress work is identified and completed before starting new tasks
+- (mvp) Merged PRs are reconciled with task status
+- (mvp) Each task follows red-green-refactor TDD cycle
+- (mvp) All quality gates pass before PR creation
+- (deep) Git state is fully reconciled (stale branches cleaned, rebased on latest main)
+- (deep) lessons.md is consulted before resuming work
+
+## Methodology Scaling
+- **deep**: Full state reconciliation, rebase on latest main, review onboarding
+  guide, consult lessons.md, reconcile all open PRs, detailed PR descriptions.
+- **mvp**: Quick git state check, identify in-progress work, finish or pick
+  next task, TDD loop, make check, create PR.
+- **custom:depth(1-5)**: Depth 1-2: check branch and continue. Depth 3: add
+  PR reconciliation and lessons.md review. Depth 4: add rebase, full test
+  suite validation, onboarding review. Depth 5: full state audit with branch
+  cleanup and eval gates.
+
+## Mode Detection
+This is a stateless execution command. No document is created or updated.
+- Always operates in RESUME MODE.
+- If there is no prior work (clean main, no feature branches, no task
+  progress), redirect to `/scaffold:single-agent-start` instead.
+
+## Update Mode Specifics
+Not applicable — this is a stateless execution command that does not produce
+a persistent document.
+
+## Instructions
+
+### State Recovery
+
+Recover your context by checking the current state of work:
+
+1. **Read project context**
+   - Read `CLAUDE.md` for project conventions and key commands
+   - Read `docs/onboarding-guide.md` if it exists (refresh project context)
+   - Read `tasks/lessons.md` for relevant anti-patterns
+
+2. **Git state assessment**
+   - `git branch --show-current` — determine if you are on a feature branch (in-progress work) or main
+   - `git status` — check for uncommitted changes or staged files
+   - `git stash list` — check for stashed work
+   - `git log --oneline -5` — review recent commits for context
+
+3. **PR reconciliation**
+   - `gh pr list --author="@me"` — check for open PRs
+   - For each open PR, check if it has been merged: `gh pr view <number> --json state`
+   - If a PR was merged while you were away, reconcile the task status (see below)
+
+4. **Dependency sync**
+   - `git fetch origin` — get latest remote state
+   - Run the install command from CLAUDE.md Key Commands to ensure dependencies are current
+
+### Beads Recovery
+
+**If Beads is configured** (`.beads/` exists):
+- `bd list` — check for tasks with `in_progress` status
+- If a PR shows as merged, close the corresponding task: `bd close <id> && bd sync`
+- If there is in-progress work, finish it (see "Resume In-Progress Work" below)
+- Otherwise, start fresh with `bd ready` to find the next available task
+- Continue working until `bd ready` shows no available tasks
+
+**Without Beads:**
+- Read `docs/implementation-playbook.md` as the primary task reference.
+  Fall back to `docs/implementation-plan.md` when no playbook is present.
+- If a PR shows as merged, mark the corresponding task as complete in the plan/playbook
+- If there is in-progress work on your current branch, finish it
+- Otherwise, pick the next uncompleted task with no unfinished dependencies
+
+### Resume In-Progress Work
+
+If you are on a feature branch with changes:
+
+1. **Assess the state**
+   - `git diff --stat` — what files have been changed?
+   - `git log --oneline origin/main..HEAD` — what commits exist on this branch?
+   - Read the task description to understand what was being worked on
+
+2. **Rebase on latest main**
+   - `git fetch origin && git rebase origin/main`
+   - Resolve any conflicts, re-run tests
+
+3. **Check test state**
+   - Run the project's test suite
+   - If tests pass: you may be in the refactor phase or ready for PR
+   - If tests fail: determine if these are your in-progress test cases (red phase) or regressions
+
+4. **Continue the TDD loop**
+   - Pick up where the previous session left off
+   - Follow the same Red-Green-Refactor cycle as in `/scaffold:single-agent-start`
+
+### Continue to Next Task
+
+Once in-progress work is complete (or if there was none):
+
+1. **Quality gates**
+   - Run `make check` (or equivalent from CLAUDE.md Key Commands)
+   - If `tests/evals/` exists, run `make eval` (or equivalent eval command)
+
+2. **Create PR** (if not already created for in-progress work)
+   - Push the branch: `git push -u origin HEAD`
+   - Create a pull request: `gh pr create`
+   - Follow the PR workflow from `docs/git-workflow.md` or CLAUDE.md
+
+3. **Claim next task**
+   - Return to main: `git checkout main && git pull origin main`
+   - Pick the next task following the same process as `/scaffold:single-agent-start`
+   - Continue the TDD execution loop
+
+### Recovery Procedures
+
+**Uncommitted changes on a feature branch:**
+- Review the changes: `git diff`
+- If the changes look intentional, stage and continue implementation
+- If the changes look broken or experimental, stash them: `git stash`
+
+**Stale feature branch (main has diverged significantly):**
+- `git fetch origin && git rebase origin/main`
+- If conflicts are extensive, consider whether it is easier to start the task fresh
+- Re-run full test suite after rebase
+
+**PR was rejected or has requested changes:**
+- `gh pr view <number>` — read the review comments
+- Address the feedback on the existing branch
+- Push updates and re-request review
+
+**Task was completed by another agent (multi-agent overlap):**
+- If Beads: `bd sync` will show updated task states
+- Without Beads: check the plan/playbook for recently completed tasks
+- Skip to the next available task
+
+**Tests fail after pulling latest main:**
+- Determine if the failure is from your changes or from recently merged work
+- If from merged work: fix or flag to the user before continuing
+- If from your changes: debug and fix as part of your current task
+
+### Process Rules
+
+1. **Always recover state first** — Never start new work without checking for in-progress tasks and merged PRs.
+2. **Rebase before continuing** — Ensure your branch is up to date with main.
+3. **Reconcile task status** — Merged PRs must be reflected in the task tracker.
+4. **TDD is not optional** — Continue the red-green-refactor cycle for any in-progress work.
+5. **Quality gates before PR** — Never create a PR with failing checks.
+6. **Follow CLAUDE.md** — It is the authority on project conventions and commands.
+
+---
+
+## After This Step
+
+When this step is complete (all tasks done or session ending), tell the user:
+
+---
+**Resume session complete** — In-progress work reconciled, tasks continued.
+
+**Session summary:**
+- Recovered state: [in-progress task or "clean start"]
+- Tasks completed this session: [list task IDs/titles]
+- PRs created: [list PR numbers]
+- Remaining tasks: [count or "none"]
+
+**If resuming again later:** Run `/scaffold:single-agent-resume` again.
+
+**If all tasks are done:**
+- Review `tasks/lessons.md` and add any patterns learned during implementation.
+- Consider running `/scaffold:version-bump` for a release.
+
+**Pipeline reference:** `/scaffold:prompt-pipeline`
+
+---