opencastle 0.32.5 → 0.32.6

package/src/orchestrator/prompts/bug-fix.prompt.md

@@ -15,8 +15,6 @@ You are the Team Lead. Investigate and fix the bug described below. Bugs are rea
 
 ---
 
-> **Canonical workflow:** `.github/agent-workflows/bug-fix.md` defines the phase structure. This prompt expands each phase with delegation-specific detail. If the two diverge, update the workflow first (SSOT) then sync the prompt.
-
 ## How Bug Fixes Differ from Other Workflows
 
 | Aspect | Roadmap Task | Follow-Up | Bug Fix |
@@ -33,52 +31,27 @@ You are the Team Lead. Investigate and fix the bug described below. Bugs are rea
 
 ### 1. Triage & Reproduce
 
-Before fixing anything, understand the bug:
-
 1. **Check known issues** — Search `.opencastle/KNOWN-ISSUES.md` for an existing entry. If found, note workarounds and decide if a fix is now feasible
 2. **Check tracker** — Search for existing bug tickets. If one exists, take it over instead of creating a duplicate
 3. **Read lessons learned** — Check `.opencastle/LESSONS-LEARNED.md` for related pitfalls
-4. **Reproduce the bug** — Start the dev server and confirm you can trigger the issue:
-   - Start the dev server (see the **codebase-tool** skill for the serve command)
-   - Navigate to the affected page in Chrome
-   - Follow the reproduction steps from the bug report
-   - Take a screenshot of the broken state as evidence
+4. **Reproduce the bug** — Start the dev server (see **codebase-tool** skill), navigate to the affected page in Chrome, follow the repro steps, and screenshot the broken state
 5. **Determine scope** — Which apps are affected? (see `project.instructions.md` for the app inventory)
-6. **Assess severity**:
-   - **Critical** — App crashes, data loss, auth bypass, page won't load
-   - **High** — Feature broken but workaround exists, significant UI breakage
-   - **Medium** — Minor functional issue, cosmetic but noticeable
-   - **Low** — Edge case, minor visual glitch
+6. **Assess severity**: Critical (crash/data loss/auth bypass) | High (broken + workaround) | Medium (minor functional) | Low (edge case/cosmetic)
 
 ### 2. Create Tracker Issue
 
 Every bug gets tracked. Create a tracker issue with:
 
 - **Title**: `[Bug] Short description of the symptom`
-- **Label**: `bug`
-- **Priority**: Based on severity assessment above
-- **Description**:
-  - **Symptom**: What the user sees
-  - **Reproduction steps**: Exact steps to trigger
-  - **Expected behavior**: What should happen
-  - **Actual behavior**: What happens instead
-  - **Affected apps**: which apps from the project inventory
-  - **Affected files** (once identified): File paths for the partition
-  - **Screenshot**: Link or description of the broken state
+- **Label**: `bug`; **Priority**: based on severity
+- **Description**: Symptom, reproduction steps, expected vs actual behavior, affected apps + files, screenshot
 
 ### 3. Root Cause Analysis
 
-Find WHY the bug happens, not just WHERE:
-
 1. **Search the codebase** — Find the components, queries, styles, and logic involved
-2. **Trace the data flow** — Follow the data from source (CMS/database) → query → component → render
-3. **Check recent changes** — Use `git log` on suspected files to see if a recent commit introduced the issue
-4. **Identify the root cause** — Distinguish between:
-   - **Code bug** — Logic error, wrong condition, missing null check
-   - **Data issue** — Unexpected data shape, missing field, bad reference
-   - **Race condition** — Timing issue, hydration mismatch, async ordering
-   - **CSS/Layout** — Specificity conflict, missing responsive rule, overflow
-   - **Integration** — API contract mismatch, schema drift, stale cache
+2. **Trace the data flow** — Source (CMS/database) → query → component → render
+3. **Check recent changes** — `git log` on suspected files
+4. **Identify the root cause** — Code bug, Data issue, Race condition, CSS/Layout, or Integration failure
 5. **Update the tracker issue** — Add root cause findings and affected file paths
 
 ### 4. Implement the Fix
@@ -91,37 +64,29 @@ All bug fixes are executed via the convoy engine — even single-task fixes —
 
 #### Convoy Task Prompt Must Include
 
-- **Tracker issue ID and title** — e.g., `TAS-XX — [Bug] Description`
-- **Root cause** — What's wrong and why
-- **Fix approach** — How to fix it (be specific)
-- **File paths** — Exact files to read and modify
-- **Reproduction steps** — So the agent can verify the fix
-- **Boundaries** — "Only modify files listed above. Fix the bug, do not refactor surrounding code."
-- **Self-improvement reminder** — include per the **self-improvement** skill
+- Tracker issue ID and title, root cause, fix approach, file paths, reproduction steps
+- Boundaries: "Only modify files listed above. Fix the bug, do not refactor surrounding code."
+- Self-improvement reminder (see **self-improvement** skill)
 
 #### Implementation Rules
 
-- **Minimal change** — Fix the bug with the smallest correct change. Resist the urge to refactor
-- **Fix the cause, not the symptom** — A CSS `!important` or silent `catch {}` is not a fix
-- **DRY** — If the fix involves logic that exists elsewhere, reuse it
-- **Add a test** — If no test covers this scenario, add one. Bugs that aren't tested come back
-- **Cross-app awareness** — If the fix is in shared code (`libs/`), verify it works for both apps
+- **Fix cause not symptom** — Minimal change, no refactoring. A CSS `!important` or silent `catch {}` is not a fix
+- **Add a test** — If no test covers this scenario, add one
+- **Cross-app awareness** — If the fix is in `libs/`, verify it works in all consuming apps
 
 ### 5. Validate
 
 > Load the **validation-gates** skill for detailed steps on each gate.
 
-Every bug fix must pass ALL applicable gates:
-
-1. **Gate 1: Secret Scanning** — scan diff for API keys, tokens, passwords, connection strings — block immediately if found
-2. **Gate 2: Deterministic Checks** — run lint, test, and build for all affected projects (see the **codebase-tool** skill for commands) — all zero errors
-3. **Gate 3: Blast Radius Check** — verify the fix is minimal and scoped (bug fixes should be ≤100 lines, ≤3 files; escalate if larger)
-4. **Gate 4: Dependency Audit** (when `package.json` or lockfiles change) — vulnerability scan, license check, bundle size, duplicates
-5. **Gate 5: Fast Review** (MANDATORY) — single reviewer sub-agent validates the fix. No auto-PASS for sensitive files
-6. **Gate 6: Bug-Specific Verification** (MANDATORY) — start dev server, reproduce original bug (should be gone), verify correct behavior, test edge cases, screenshot before/after, check both apps if shared code
-7. **Gate 7: Browser Testing** (for UI-related bugs) — clear cache, start server, verify fix + responsive + screenshots
-8. **Gate 8: Regression Testing** — run tests for all projects consuming modified files, browser-test adjacent functionality
-9. **Gate 9: Panel Review** (only if needed) — use **panel-majority-vote** skill if fix touches auth/authorization, RLS, security headers/CSP, or sensitive data
+1. **Secret Scanning** — block if API keys/tokens/passwords found in diff
+2. **Deterministic Checks** — lint, test, build — zero errors (see **codebase-tool** skill)
+3. **Blast Radius** — bug fixes should be ≤100 lines / ≤3 files; escalate if larger
+4. **Dependency Audit** — when `package.json` or lockfiles change
+5. **Fast Review** (MANDATORY) — single reviewer sub-agent
+6. **Bug-Specific Verification** (MANDATORY) — reproduce original bug (should be gone), verify correct behavior, screenshot before/after, check both apps if shared code
+7. **Browser Testing** (for UI bugs) — clear cache, verify fix + responsive + screenshots
+8. **Regression Testing** — run tests for all projects consuming modified files
+9. **Panel Review** — only if fix touches auth/authorization, RLS, security headers, or sensitive data (use **panel-majority-vote** skill)
 
 ### 6. Delivery
 
@@ -129,10 +94,9 @@ Follow the **Delivery Outcome** defined in the **git-workflow** skill — commit
 
 ### 7. Wrap Up
 
-1. **Move tracker issue to Done** — Only after all validation passes
-2. **Update Known Issues** — If this was a documented known issue, remove or update the entry in `.opencastle/KNOWN-ISSUES.md`
-3. **Capture lessons** — If the root cause reveals a pattern that other agents should know about, use the **self-improvement** skill to add a lesson
-4. **Note prevention** — If this class of bug could be caught earlier (by a lint rule, test, or type check), note that in the tracker issue as a follow-up suggestion
+1. **Close out** — Move tracker to Done; remove or update any `.opencastle/KNOWN-ISSUES.md` entry if applicable
+2. **Capture lessons** — Use the **self-improvement** skill if the root cause reveals a pattern others should know
+3. **Note prevention** — If the bug class could be caught earlier, note it in the tracker as a follow-up
 
 ### 8. Completion Criteria
 
@@ -142,9 +106,7 @@ The bug fix is complete when:
 - [ ] Tracker issue created with full details
 - [ ] Fix implemented with minimal change
 - [ ] Test added covering the bug scenario
-- [ ] Lint, test, and build pass for all affected projects
 - [ ] Bug verified fixed in the browser
-- [ ] No regressions in adjacent functionality
 - [ ] Both apps checked if shared code was modified
 - [ ] Delivery Outcome completed (see the **git-workflow** skill) — branch pushed, PR opened (not merged), tracker linked
 - [ ] Tracker issue moved to Done

package/src/orchestrator/prompts/implement-feature.prompt.md

@@ -15,22 +15,16 @@ You are the Team Lead. Implement the roadmap task described below following this
 
 ---
 
-> **Canonical workflow:** `.github/agent-workflows/feature-implementation.md` defines the phase structure. This prompt adds tracker traceability, validation gate references, and completion criteria.
-
 ## Workflow
 
 > **HARD GATE:** Steps 1→2 are **blocking prerequisites**. Do NOT write, edit, or delegate any code until tracker issues exist for every subtask. If you catch yourself writing code before issues are created, STOP immediately, create the issues, then resume.
 
 ### 1. Research & Context Gathering
 
-Before writing any code, gather all relevant context:
-
-1. **Read the roadmap** — Open `.opencastle/project/roadmap.md` and find the full scope, status, and acceptance criteria for this task
-2. **Read known issues** — Check `.opencastle/KNOWN-ISSUES.md` for blockers or workarounds that affect this task
-3. **Read architecture docs** — Check `.opencastle/project.instructions.md` and `.opencastle/project/decisions.md` for constraints and prior decisions
-4. **Read lessons learned** — Check `.opencastle/LESSONS-LEARNED.md` for pitfalls relevant to this feature area
-5. **Search existing code** — Find all files, components, queries, and tests related to this feature area
-6. **Identify reusable code** — Before creating anything new, check if similar logic, components, or utilities already exist in the codebase that can be reused or extended
+1. **Read the roadmap** — Confirm scope, status, and acceptance criteria in `.opencastle/project/roadmap.md`
+2. **Check blockers** — Read `.opencastle/KNOWN-ISSUES.md` and `.opencastle/LESSONS-LEARNED.md` for pitfalls and workarounds
+3. **Read architecture docs** — Check `.opencastle/project.instructions.md` and `.opencastle/project/decisions.md` for constraints
+4. **Search existing code** — Find related files, components, queries, and tests; check for reusable implementations before creating anything new
 
 ### 2. Task Board Setup (BLOCKING — must complete before Step 3)
 
@@ -39,52 +33,37 @@ Every subtask must be tracked. **No issue = no implementation.** This step produ
 1. **Check existing issues** — Search the board for any in-progress or completed work related to this task
 2. **Decompose into issues** — Create one tracker issue per subtask using `[Area] Short description` naming
 3. **Set metadata** — Assign labels (agent name), priority, dependencies, and file partitions
-4. **Write descriptions** — Each issue must include:
-   - **Objective:** One sentence
-   - **Files (partition):** Exact paths this agent may modify
-   - **Acceptance criteria:** Verifiable checklist
-   - **Dependencies:** Links to prerequisite issues
+4. **Write descriptions** — Objective (1 sentence), files (partition paths), acceptance criteria (checklist), dependencies (links)
 5. **Link to roadmap** — Reference the roadmap section in the issue description so context is never lost
 6. **Verify issues exist** — List all created issue IDs. If count is 0, do NOT proceed to Step 2.5
 
 ### 2.5 Generate Convoy Spec (BLOCKING — decides how Step 3 proceeds)
 
-All project-related work is executed via the convoy engine — regardless of subtask count. This ensures consistent observability, crash recovery, and live progress.
+All project-related work is executed via the convoy engine — regardless of subtask count.
 
-1. **Generate the spec** — use the `generate-convoy` prompt with the decomposed task list as context. The spec IS the implementation plan — no manual per-task delegation is needed. Even single-task fixes go through convoy for observability.
+1. **Generate the spec** — use the `generate-convoy` prompt with the decomposed task list. The spec IS the implementation plan; even single-task fixes go through convoy for observability.
 2. **Hand the spec to the user** — tell them to run: `npx opencastle run -f .opencastle/convoys/<name>.convoy.yml`
 3. **The convoy engine handles** isolated git worktrees, parallel execution, merge queue ordering, crash recovery, and structured logging automatically.
-4. **After convoy completes** — proceed to Step 4 (validation) and Step 5 (delivery/PR). The convoy engine will have created its own commits on the configured branch.
-
-> **Why always convoy?** Convoy execution is the only path that guarantees observability logging, crash recovery, gate validation, and live progress. Direct sub-agent delegation produces no structured logs and cannot be resumed if interrupted.
+4. **After convoy completes** — proceed to Step 4 (validation) and Step 5 (delivery/PR).
 
 ### 3. Implementation Rules
 
-> **Convoy execution:** The convoy spec file IS the implementation plan — skip the manual delegation workflow below and jump to Step 4 after the user runs the convoy. The convoy engine delegates tasks internally using the agents and prompts defined in the spec.
+> **Convoy execution:** The convoy spec IS the implementation plan — skip manual delegation and jump to Step 4 after the user runs the convoy.
 
 #### Issue Traceability
 
-- **Pass issue ID to every agent** — When delegating a subtask (sub-agent or background), include the tracker issue ID and title in the prompt so the agent knows which tracked task it is completing
-- **Reference in commits** — Include the issue ID (e.g., `TAS-42`) in commit messages when possible
-- **Update issue status** — Move issues to In Progress before starting, Done after verification passes
+- Include the tracker issue ID and title in every delegation prompt
+- Reference issue IDs (e.g., `TAS-42`) in commit messages; move issues In Progress → Done as work progresses
 
 #### DRY Code
 
-- **Search before creating** — Before writing any new component, hook, utility, query, or type, search the codebase for existing implementations
-- **Extract shared logic** — If two agents need similar functionality, extract it to a shared library (`libs/`) first
-- **No copy-paste across apps** — Shared code belongs in shared libraries, not duplicated between apps
-- **Refactor on discovery** — If you find duplicated code during implementation, create a subtask to consolidate it
-
-#### Self-Improvement
-
-Include the self-improvement reminder in every delegation prompt (see the **self-improvement** skill).
+- Search before creating — check for existing components, hooks, utilities, and queries first
+- Extract shared logic to `libs/`; no copy-paste across apps. Refactor duplicates when discovered
 
 #### Visual Consistency
 
-- **Reuse existing components** — Use the shared component library; never re-implement a component that already exists
-- **Follow the design system** — Match spacing, typography, colors, and interaction patterns from existing pages
-- **Cross-app consistency** — Changes must look correct in all apps that share the codebase
-- **Browser verification required** — Every UI change must be visually confirmed in Chrome (see Testing below)
+- Use the shared component library; never re-implement existing components
+- Match spacing, typography, and colors from existing pages; verify in all affected apps
 
 ### 4. Validation & Testing
 
@@ -92,39 +71,26 @@ Include the self-improvement reminder in every delegation prompt (see the **self
 
 Every subtask must pass ALL gates before being marked Done:
 
-1. **Gate 1: Secret Scanning** — scan diff for API keys, tokens, passwords, connection strings — block immediately if found
-2. **Gate 2: Deterministic Checks** — run lint, test, and build for all affected projects (see the **codebase-tool** skill for commands) — all zero errors
-3. **Gate 3: Blast Radius Check** — verify scope is expected (≤200 lines, ≤5 files normal; escalate if >500 lines or >10 files)
-4. **Gate 4: Dependency Audit** (when `package.json` changes) — vulnerability scan, license check, bundle size, duplicates
-5. **Gate 5: Fast Review** (MANDATORY) — single reviewer sub-agent validates every delegation output. No auto-PASS for sensitive files
-6. **Gate 6: Browser Testing** (MANDATORY for UI changes) — clear cache, start server, verify features + responsive + screenshots
-7. **Gate 7: Regression Testing** — full test suite for affected projects, browser-test adjacent pages if shared components changed
-8. **Gate 8: Panel Review** (for high-stakes changes) — use **panel-majority-vote** skill for security, DB migrations, architecture
-9. **Gate 9: Final Smoke Test** — after all tasks Done, verify the complete feature end-to-end as a cohesive unit
+1. **Secret Scanning** — block if API keys/tokens/passwords found in diff
+2. **Deterministic Checks** — lint, test, build — zero errors (see **codebase-tool** skill)
+3. **Blast Radius** — ≤200 lines / ≤5 files normal; escalate if >500 lines or >10 files
+4. **Dependency Audit** — when `package.json` changes
+5. **Fast Review** (MANDATORY) — single reviewer sub-agent
+6. **Browser Testing** (MANDATORY for UI) — clear cache, verify features + responsive + screenshots
+7. **Regression Testing** — full suite for affected projects
+8. **Panel Review** — for security, DB migrations, architecture (use **panel-majority-vote** skill)
+9. **Final Smoke Test** — end-to-end verification of complete feature
 
 ### 5. Delivery
 
-Follow the **Delivery Outcome** defined in the **git-workflow** skill — commit, push, open PR (not merged), and link to the tracker.
-
-> The convoy engine creates commits on the configured `branch` directly. After validation passes, open the PR from that branch. No additional commits from the Team Lead are needed unless gates failed and required manual fixes.
+Follow the **Delivery Outcome** defined in the **git-workflow** skill — commit, push, open PR (not merged), and link to the tracker. The convoy engine creates commits on the configured `branch` directly; open the PR from that branch after validation passes.
 
 ### 6. Documentation & Traceability
 
-Keep documentation current so future sessions have full context:
-
-1. **Update roadmap** — Mark completed items in `.opencastle/project/roadmap.md` with ✅ and the completion date. **Include tracker issue IDs and links** next to each scope item so progress is traceable across sessions. Format:
-   ```
-   **Tracker Issues:**
-   - [PREFIX-6](<tracker-url>/PREFIX-6) — [Search] Description ✅ Done
-   - [PREFIX-7](<tracker-url>/PREFIX-7) — [UI] Description 📋 Todo
-   ```
-   > Replace `PREFIX` with the project's issue prefix (see `tracker-config.md`).
-2. **Update known issues** — If new limitations are discovered, add them to `.opencastle/KNOWN-ISSUES.md`
-3. **Update architecture docs** — If architectural decisions were made, add an ADR to `.opencastle/project/decisions.md`
-4. **Link tracker issues** — Every issue description should reference:
-   - Related roadmap section
-   - Files modified (the partition)
-   - Related issues (dependencies and follow-ups)
+1. **Update roadmap** — Mark completed items with ✅ and date; include tracker issue IDs next to each scope item (e.g., `[PREFIX-6](<url>) — Description ✅ Done`)
+2. **Update known issues** — Add new limitations to `.opencastle/KNOWN-ISSUES.md`
+3. **Update architecture docs** — Add ADRs for architectural decisions to `.opencastle/project/decisions.md`
+4. **Link tracker issues** — Reference roadmap section, partition files, and related issues in each description
 5. **Close issues properly** — Move to Done only after independent verification passes all gates
 
 ### 7. Completion Criteria
@@ -132,11 +98,8 @@ Keep documentation current so future sessions have full context:
 The roadmap task is complete when:
 
 - [ ] All tracker subtask issues are Done
-- [ ] All deterministic checks pass (lint, test, build) for affected projects
-- [ ] **Dev server started with CLEAN cache** (clear framework + task runner caches before serving — see the **codebase-tool** skill)
 - [ ] **All UI changes verified in Chrome browser via MCP with screenshots taken as proof**
 - [ ] **Every feature in the acceptance criteria visually confirmed** — not just "page loads"
-- [ ] Regression tests confirm no existing functionality is broken
 - [ ] No duplicated code — shared logic extracted to libraries
 - [ ] Visual consistency maintained across all affected pages and apps
 - [ ] Documentation updated (roadmap, known issues, decisions)

package/src/orchestrator/prompts/quick-refinement.prompt.md

@@ -31,68 +31,45 @@ You are the Team Lead. Handle the follow-up refinement described below. This is
 
 ### 1. Triage: Decide Tracking Level
 
-Before doing anything, decide whether this follow-up needs issue tracking:
-
 **Create a tracker issue if ANY of these are true:**
-- The change affects user-visible behavior (not just cosmetic)
-- It touches more than 2–3 files
-- It modifies shared library code (`libs/`)
-- It changes data queries, API routes, or Server Actions
-- It could introduce regressions in other features
-- You want a record for future reference (e.g., "why was this changed?")
+- Affects user-visible behavior, touches >2–3 files, or modifies `libs/`, queries, API routes, or Server Actions
+- Could introduce regressions in other features
+- You want a record for future reference
 
 **Skip tracking if ALL of these are true:**
-- Pure cosmetic/spacing/copy tweak
+- Pure cosmetic/spacing/copy change with no behavioral impact
 - Isolated to a single component or page
-- No behavioral change
 - Trivial to verify visually
 
-If creating a tracker issue, use:
-- **Title**: `[Follow-up] Short description`
-- **Label**: agent name + `follow-up`
-- **Priority**: Low or Medium
-- **Description**: What changed, why, and which files
+If creating: title `[Follow-up] Short description`, label `follow-up`, priority Low/Medium, description: what changed, why, files
 
 ### 2. Understand the Request
 
-Before touching any code:
-
 1. **Clarify scope** — Identify exactly which pages, components, or behaviors need to change
 2. **Find affected files** — Search the codebase for the relevant components, styles, queries, and tests
 3. **Check known issues** — Scan `.opencastle/KNOWN-ISSUES.md` in case this is a documented limitation
 4. **Read lessons learned** — Check `.opencastle/LESSONS-LEARNED.md` for relevant pitfalls before starting
-5. **Assess complexity** — If the request turns out to be larger than expected (touches >5 files, needs a migration, or affects auth/security), escalate it:
-   - Inform the user that this should be a tracked task
-   - Create a tracker issue (if not already created in triage) and switch to the `implement-feature` workflow
+5. **Assess complexity** — If larger than expected (>5 files, migration, or auth/security), inform the user, create a tracker issue, and switch to the `implement-feature` workflow
 
 ### 3. Plan the Fix
 
-Think before you act:
-
-1. **Identify root cause** — For bugs, find why it happens, not just where. For UI tweaks, understand the current styling/layout chain
-2. **Check for shared impact** — Will the fix affect other pages or apps? Check component usage across the codebase
-3. **Determine the minimal change** — Follow the principle of least surprise. Change only what's necessary
-4. **Reuse existing patterns** — Use components, utilities, and styles that already exist in the codebase. Never introduce a new pattern for a one-off fix
+1. **Identify root cause** — For bugs, find why; for UI tweaks, understand the styling/layout chain
+2. **Assess shared impact** — Will the fix affect other pages or apps? Check component usage across the codebase
+3. **Minimal change** — Reuse existing components, utilities, and styles. Never introduce a new pattern for a one-off fix
 
 ### 4. Implement
 
-Delegate to the appropriate specialist agent(s). Since follow-ups are scoped and focused, prefer **sub-agents** (inline) over background agents.
-
 #### Delegation Prompt Must Include
 
-- **What to fix** — clear description of the problem and desired outcome
-- **Where** — exact file paths to read and modify
-- **How to verify** — what the result should look like or how to test it
-- **Boundaries** — "Only modify files listed above. Do not refactor unrelated code."
-- **Self-improvement reminder** — include per the **self-improvement** skill
+- What to fix, exact file paths, and how to verify the result
+- Boundaries: "Only modify files listed above. Do not refactor unrelated code."
+- Self-improvement reminder (see **self-improvement** skill)
 
 #### Implementation Rules
 
-- **No scope creep** — Fix what was asked. If you notice other issues, note them but don't fix them in this pass
-- **DRY** — Search before creating. Reuse existing components and utilities
-- **Visual consistency** — Match the existing design system (spacing, colors, typography)
-- **Cross-app check** — If the change is in shared code (`libs/`), verify it works for both apps
-- **Accessibility** — Don't regress keyboard navigation, screen reader support, or contrast ratios
+- **No scope creep** — Fix only what was asked; note but don't fix adjacent issues
+- **DRY + Visual consistency** — Reuse existing components, utilities, and design system patterns
+- **Cross-app + Accessibility** — Verify `libs/` changes across apps; don't regress keyboard nav/contrast
 
 ### 5. Validate
 
@@ -100,46 +77,34 @@ Delegate to the appropriate specialist agent(s). Since follow-ups are scoped and
 
 Every follow-up, no matter how small, must pass these gates:
 
-1. **Gate 1: Secret Scanning** — scan diff for API keys, tokens, passwords, connection strings — block immediately if found
-2. **Gate 2: Deterministic Checks** — run lint, test, and build for all affected projects (see the **codebase-tool** skill for commands) — all zero errors
-3. **Gate 3: Blast Radius Check** — verify scope matches the "small follow-up" expectation (≤100 lines, ≤3 files normal; if larger, escalate to `implement-feature` workflow)
-4. **Gate 4: Dependency Audit** (when `package.json` or lockfiles change) — vulnerability scan, license check, bundle size, duplicates
-5. **Gate 5: Fast Review** (MANDATORY) — single reviewer sub-agent validates the change. No auto-PASS for sensitive files
-6. **Gate 6: Browser Testing** (MANDATORY for any visual change) — clear cache, start server, verify scenario + responsive + screenshot evidence
-7. **Gate 7: Regression Testing** — if shared component/library modified, run tests for all consuming projects and browser-test at least one page per affected app
+1. **Secret Scanning** — block if API keys/tokens/passwords found in diff
+2. **Deterministic Checks** — lint, test, build — zero errors (see **codebase-tool** skill)
+3. **Blast Radius** — ≤100 lines / ≤3 files for follow-ups; if larger, escalate to `implement-feature`
+4. **Dependency Audit** — when `package.json` or lockfiles change
+5. **Fast Review** (MANDATORY) — single reviewer sub-agent
+6. **Browser Testing** (MANDATORY for visual changes) — clear cache, verify + responsive + screenshots
+7. **Regression Testing** — if shared component/library modified, test all consuming projects
 
 ### 6. Delivery
 
-If triage determined this follow-up needs tracker tracking, follow the **Delivery Outcome** defined in the **git-workflow** skill — commit, push, open PR (not merged), and link to the tracker.
+If tracked: follow the **Delivery Outcome** in the **git-workflow** skill — commit, push, open PR (not merged), tracker linked.
 
-If triage determined no tracker tracking is needed (pure cosmetic/isolated/trivial), commit the changes to the current working branch. A dedicated branch and PR are not required because the Team Lead will include these changes in the parent task's existing PR — the "every change goes through a PR" rule is still satisfied via the parent PR.
+If untracked: commit to the current branch; Team Lead includes in the parent task's existing PR.
 
 ### 7. Escalation Triggers
 
-Stop the follow-up workflow and switch to a full roadmap task if:
-
-- The fix requires a **database migration**
-- The fix involves **authentication or authorization** changes
-- The fix touches **more than 5 files** across multiple libraries
-- The fix introduces a **new dependency** or **new API endpoint**
-- The fix changes **data models** (CMS schemas, database tables)
-- You discover the "small fix" is actually a **systemic issue** requiring architectural changes
-
-When escalating, explain to the user what you found and why it needs proper tracking.
-
-- **Multi-task escalation** — If the refinement decomposes into 3+ subtasks, switch to `implement-feature` (which will use convoy execution for multi-task work)
+- Requires a database migration or data model changes (CMS schemas, tables)
+- Involves auth/authorization changes
+- Touches >5 files across multiple libraries
+- Introduces a new dependency or API endpoint
+- Is a systemic issue requiring architectural changes
+- Decomposes into 3+ subtasks → switch to `implement-feature`
 
 ### 8. Completion
 
-The follow-up is complete when:
-
 - [ ] The specific request is resolved
 - [ ] Tracker issue created and moved to Done (if triage determined tracking was needed)
-- [ ] Lint, test, and build pass for all affected projects
-- [ ] **Dev server started with CLEAN cache** (clear framework + task runner caches before serving — see the **codebase-tool** skill)
 - [ ] **Visual changes verified in Chrome with screenshot taken as proof**
-- [ ] No regressions in adjacent functionality
 - [ ] Shared component changes tested across all consuming apps
 - [ ] Delivery Outcome completed if tracked (see the **git-workflow** skill) — branch pushed, PR opened (not merged), tracker linked
-- [ ] Lessons learned captured if any retries occurred
-- [ ] Known issues updated if a new limitation was discovered
+- [ ] Lessons learned captured and known issues updated if applicable