@lovehlmmm/primekit 1.0.0

package/skills/fix/references/skill-activation-matrix.md

@@ -0,0 +1,100 @@
+# Skill Activation Matrix
+
+When to activate each skill and tool during fixing workflows.
+
+## Always Activate (ALL Workflows)
+
+Before activating tools, capture or reuse the opening outcome, constraints,
+non-goals, and acceptance criteria. This is a workflow gate, not a separate
+mandatory subagent.
+
+| Skill/Tool | Step | Reason |
+|------------|------|--------|
+| `pk:scout` OR parallel `Explore` when permitted | Step 1 | Understand codebase context before diagnosing |
+| `pk:debug` | Step 2 | Systematic root cause investigation |
+| `pk:sequential-thinking` | Step 2 | Structured hypothesis formation — NO guessing |
+| `the engineer project-management skill` | Step 6 | MANDATORY for sync-back and progress tracking, every fix |
+
+## Task Orchestration (Moderate+ Only)
+
+| Tool | Activate When |
+|------|---------------|
+| Live task management | After complexity assessment, when runtime discovery confirms support |
+| `delegate_agent` | User explicitly requested subagents/delegation/parallel work and runtime permits it |
+
+Skip progress orchestration for Quick workflow (< 3 steps).
+
+## Auto-Triggered Activation
+
+| Skill | Auto-Trigger Condition |
+|-------|------------------------|
+| `pk:problem-solving` | 2+ hypotheses REFUTED in Step 2 diagnosis |
+| `pk:sequential-thinking` | Always in Step 2 (mandatory for hypothesis formation) |
+
+## Conditional Activation
+
+| Skill | Activate When |
+|-------|---------------|
+| `pk:brainstorm` | After diagnosis, when multiple valid fix approaches or an architecture decision remain |
+| `pk:context-engineering` | Fixing AI/LLM/agent code, context window issues |
+| `pk:ai-multimodal` | UI issues, screenshots provided, visual bugs |
+
+## Subagent Usage
+
+| Subagent | Activate When |
+|----------|---------------|
+| `debugger` | Root cause unclear, need deep investigation (Step 2) |
+| `Explore` (parallel) | Scout multiple areas simultaneously (Step 1), test hypotheses (Step 2), only when delegation is explicitly requested/permitted |
+| Verification workers | Verify implementation: typecheck, lint, build, test (Step 5), only when delegation is explicitly requested/permitted |
+| `researcher` | External docs needed, latest best practices (Deep only) |
+| `planner` | Complex fix needs breakdown, multiple phases (Deep only) |
+| `tester` | After implementation, verify fix works (Step 5) |
+| `pk:code-review` | After fix, verify quality and security (Step 5) |
+| `git-manager` | After approval, commit changes (Step 6) |
+| `docs-manager` | API/behavior changes need doc updates (Step 6) |
+| `fullstack-developer` | Parallel independent issues (each gets own agent) |
+
+## Parallel Patterns
+
+See `references/parallel-exploration.md` for detailed patterns.
+
+| When | Parallel Strategy |
+|------|-------------------|
+| Scouting (Step 1) | 2-3 `Explore` agents on different areas, only when delegation is permitted |
+| Testing hypotheses (Step 2) | 2-3 `Explore` agents per hypothesis, only when delegation is permitted |
+| Multi-module fix | `Explore` each module in parallel, only when delegation is permitted |
+| After implementation (Step 5) | `run_shell`: typecheck + lint + build + test; delegate only when permitted |
+| 2+ independent issues | Plan trees + delegated agents per issue when permitted |
+
+## Workflow → Skills Map
+
+| Workflow | Skills Activated |
+|----------|------------------|
+| Quick | opening intent frame, `pk:scout` (minimal), `pk:debug`, `pk:sequential-thinking`, `pk:code-review`, `the engineer project-management skill`, `run_shell` verification |
+| Standard | opening intent frame + Quick tools, optional live task management, `pk:problem-solving` (auto), optional post-diagnosis `pk:brainstorm`, optional delegated tester/Explore when permitted |
+| Deep | opening intent frame + all above, post-diagnosis `pk:brainstorm`, `pk:context-engineering`, `researcher`, `planner` |
+| Parallel | Per-issue plan trees + `pk:project-management` + delegated agents + live coordination when available |
+
+## Step → Skills Chain (Mandatory Order)
+
+| Step | Mandatory Chain |
+|------|----------------|
+| Opening gate | capture or reuse outcome → constraints → non-goals → acceptance criteria |
+| Step 0: Mode | `ask_user capability` only when mode is not explicit or safely inferable |
+| Step 1: Scout | `pk:scout` OR 2-3 parallel `Explore` when delegation is permitted → map files, deps, tests |
+| Step 2: Diagnose | Capture pre-fix state → `pk:debug` → `pk:sequential-thinking` → optional delegated Explore hypotheses → (`pk:problem-solving` if 2+ fail) |
+| Step 3: Assess | Classify complexity → choose direct cause-aligned fix or post-diagnosis `pk:brainstorm` → record dependencies in the active plan and optional live surface (moderate+) |
+| Step 4: Fix | Implement per workflow → follow root cause |
+| Step 5: Verify+Prevent | Iron-law verify → regression test → defense-in-depth → `run_shell` verify |
+| Step 6: Finalize | Report → `the engineer project-management skill` (MANDATORY) → docs-impact decision → conditional `docs-manager` → sync runtime tracking when available → `git-manager` → `/pk:journal` (unless the shared "Journal step — opt-out" applies — see SKILL.md) |
+
+## Detection Triggers
+
+| Keyword/Pattern | Skill to Consider |
+|-----------------|-------------------|
+| "AI", "LLM", "agent", "context" | `pk:context-engineering` |
+| "stuck", "tried everything" | `pk:problem-solving` |
+| "complex", "multi-step" | `pk:sequential-thinking` |
+| "which approach", "options" | `pk:brainstorm` |
+| "latest docs", "best practice" | `researcher` subagent |
+| Screenshot attached | `pk:ai-multimodal` |

package/skills/fix/references/workflow-ci.md

@@ -0,0 +1,28 @@
+# CI/CD Fix Workflow
+
+For GitHub Actions failures and CI/CD pipeline issues.
+
+## Prerequisites
+- `gh` CLI installed and authorized
+- GitHub Actions URL or run ID
+
+## Workflow
+
+1. **Fetch logs** with `debugger` agent:
+   ```bash
+   gh run view <run-id> --log-failed
+   gh run view <run-id> --log
+   ```
+
+2. **Analyze** root cause from logs
+
+3. **Implement fix** based on analysis
+
+4. **Test locally** with `tester` agent before pushing
+
+5. **Iterate** if tests fail, repeat from step 3
+
+## Notes
+- If `gh` unavailable, instruct user to install: `gh auth login`
+- Check both failed step and preceding steps for context
+- Common issues: env vars, dependencies, permissions, timeouts

package/skills/fix/references/workflow-deep.md

@@ -0,0 +1,165 @@
+# Deep Workflow
+
+Full pipeline with research, brainstorming, and planning for complex issues.
+Discover the live task-management surface and use it for dependency tracking
+when available. Otherwise, update the active plan. Plan files are the durable
+source of truth.
+
+The parent skill's opening intent frame is already satisfied. The brainstorm in
+this route is a later solution decision grounded in diagnosis; it does not
+replace or repeat the opening contract.
+
+## Plan Setup (Before Starting)
+
+Record phase dependencies upfront. Steps 1+2+3 may run in parallel when the
+runtime permits the needed delegation.
+
+- Scout codebase
+- Diagnose root cause
+- Research solutions
+- Brainstorm approaches, blocked by scout + diagnose + research
+- Create implementation plan, blocked by brainstorm
+- Implement fix, blocked by plan
+- Verify + prevent, blocked by implementation
+- Code review, blocked by verification
+- Finalize & docs, blocked by review
+
+## Steps
+
+### Step 1: Scout Codebase (parallel with Steps 2+3)
+Record the scout phase as active.
+
+**Mandatory:** Activate `pk:scout` skill or, when delegation is permitted,
+launch 2-3 `Explore` subagents in parallel through `delegate_agent`. In Codex
+Desktop, expose deferred multi-agent tools with `tool_search` first, then use
+`multi_agent_v1.spawn_agent(agent_type="Explore", message="...")`.
+
+Map: all affected files, module boundaries, call chains, test coverage gaps.
+
+See `references/parallel-exploration.md` for patterns.
+
+Record the scout phase as completed after its evidence is captured.
+**Output:** `✓ Step 1: Scouted - [N] files, system impact: [scope]`
+
+### Step 2: Diagnose Root Cause (parallel with Steps 1+3)
+Record the diagnose phase as active.
+
+**Mandatory skill chain:**
+1. **Capture pre-fix state:** Record ALL error messages, failing tests, stack traces, logs.
+2. Activate `pk:debug` skill (systematic-debugging + root-cause-tracing).
+3. Activate `pk:sequential-thinking` — structured hypothesis formation.
+4. Use delegated `Explore` subagents to test hypotheses only when delegation is explicitly requested/permitted.
+5. If 2+ hypotheses fail → auto-activate `pk:problem-solving`.
+6. Trace backward through call chain to ROOT CAUSE origin.
+
+Use the root-cause checklist in the parent skill as the diagnosis protocol.
+
+Record the diagnose phase as completed after the root cause is proven.
+**Output:** `✓ Step 2: Diagnosed - Root cause: [summary], Evidence: [chain]`
+
+### Step 3: Research (parallel with Steps 1+2)
+Record the research phase as active.
+Use `researcher` through `delegate_agent` only when delegation is explicitly requested/permitted.
+
+- Search latest docs, best practices
+- Find similar issues/solutions
+- Gather security advisories if relevant
+
+Record the research phase as completed after relevant evidence is retained.
+**Output:** `✓ Step 3: Research complete - [key findings]`
+
+### Step 4: Brainstorm
+Record brainstorming as active after scout, diagnosis, and research are complete.
+Activate `pk:brainstorm` skill.
+
+- Evaluate multiple approaches using scout + diagnosis + research findings
+- Consider trade-offs
+- Compare each option with the opening constraints, non-goals, and acceptance
+  criteria
+- Resolve the preferred direction; explicit auto mode may use the documented
+  recommendation without a routine pause
+
+Record brainstorming as completed after the direction is resolved.
+**Output:** `✓ Step 4: Approach selected - [chosen approach]`
+
+### Step 5: Plan
+Record planning as active.
+Use delegated `planner` only when delegation is explicitly requested/permitted;
+otherwise write the plan locally.
+
+- Break down into phases
+- Identify dependencies
+- Define success criteria
+- Include prevention measures in plan
+
+Record planning as completed after the durable plan is written.
+**Output:** `✓ Step 5: Plan created - [N] phases`
+
+### Step 6: Implement
+Record implementation as active.
+Implement per plan. Use `pk:context-engineering`, `pk:sequential-thinking`, `pk:problem-solving`.
+
+- Fix ROOT CAUSE per diagnosis — not symptoms
+- Follow plan phases
+- Minimal changes per phase
+
+Record implementation as completed.
+**Output:** `✓ Step 6: Implemented - [N] files, [M] phases`
+
+### Step 7: Verify + Prevent
+Record verification as active.
+
+**Mandatory skill chain:**
+1. **Iron-law verify:** Re-run EXACT commands from pre-fix state. Compare before/after.
+2. **Regression test:** Add comprehensive tests. Tests MUST fail without fix, pass with fix.
+3. **Side-effect sweep (HARD-GATE-NO-SIDE-EFFECTS):** Walk each dependent caller of changed functions from Step 1 blast-radius. Run tests in modules that share files/contracts. Confirm public contracts (signatures, schemas, APIs, env vars) unchanged. See SKILL.md HARD-GATE-NO-SIDE-EFFECTS.
+4. **Defense-in-depth:** Apply all relevant prevention layers from the parent skill.
+5. **Verification commands:** Run typecheck + lint + build + test through `run_shell`; delegate only when explicitly requested/permitted.
+6. **Edge cases:** Test boundary conditions, security implications, performance impact.
+
+**On regression / side effect:** `ask_user capability` with 2-4 concrete options (revert / narrow scope / update dependents / accept). Never silently patch.
+
+**If verification fails:** Loop back to Step 2 (re-diagnose). Max 3 attempts → question architecture.
+
+Use the prevention checklist in the parent skill.
+
+Record verification as completed only after fresh evidence passes.
+**Output:** `✓ Step 7: Verified + Prevented - [before/after], [N] tests, [M] guards`
+
+### Step 8: Code Review
+Record review as active.
+Use delegated `code-reviewer` only when delegation is explicitly requested/permitted; otherwise review locally.
+
+See `references/review-cycle.md` for mode-specific handling.
+
+Record review as completed after accepted findings are resolved.
+**Output:** `✓ Step 8: Review [score]/10 - [status]`
+
+### Step 9: Finalize
+Record finalization as active.
+- Report summary: root cause, evidence chain, changes, prevention measures, confidence score
+- Activate `pk:project-management` for task sync-back, plan status updates, and progress tracking
+- Evaluate docs impact; use delegated docs-manager only for affected authority
+  surfaces and git-manager only when explicitly requested/permitted
+- Run `/pk:journal` — unless the shared "Journal step — opt-out" applies (see SKILL.md; skip when `--skip-journal` or `journal.auto=false`)
+
+Record finalization as completed in the live surface when available and in the active plan.
+**Output:** `✓ Step 9: Complete - [actions taken]`
+
+## Skills/Subagents Activated
+
+| Step | Skills/Subagents |
+|------|------------------|
+| 1 | `pk:scout` OR parallel `Explore` subagents when delegation is permitted |
+| 2 | `pk:debug`, `pk:sequential-thinking`, optional delegated Explore when permitted, (`pk:problem-solving` auto) |
+| 3 | `researcher` via `delegate_agent` when permitted |
+| 4 | `pk:brainstorm` |
+| 5 | `planner` |
+| 6 | `pk:problem-solving`, `pk:sequential-thinking`, `pk:context-engineering` |
+| 7 | `run_shell` verification; optional delegated tester when permitted |
+| 8 | `code-reviewer` via `delegate_agent` when permitted, otherwise local review |
+| 9 | `pk:project-management`; docs/git delegation only when permitted |
+
+**Rules:** Don't skip steps. Validate before proceeding. One phase at a time.
+**Frontend:** Use `pk:agent-browser`, Chrome MCP / `chrome-devtools-mcp`, or any relevant project-native browser tests to verify.
+**Visual Assets:** Use `pk:ai-multimodal` for visual assets generation, analysis and verification.

package/skills/fix/references/workflow-logs.md

@@ -0,0 +1,59 @@
+# Log Analysis Fix Workflow
+
+For fixing issues found in application logs.
+
+## Prerequisites
+
+- Log file at `./logs.txt` or a project-specific equivalent
+
+## Setup When Logs Are Missing
+
+Add persistent log piping to project configuration:
+
+- **Bash/Unix:** `command 2>&1 | tee logs.txt`
+- **PowerShell:** `command *>&1 | Tee-Object logs.txt`
+
+## Progress Tracking
+
+The stages are `analyze logs → scout code → plan fix → implement → test →
+review`. Discover the live task-management surface and mirror this dependency
+chain when available. Otherwise, update the active plan as stages start and
+finish. Plan files are the durable source of truth.
+
+## Workflow
+
+### Step 1: Read and Analyze Logs
+
+- Read logs with `search_files capability`; start with a small result limit
+- Use the debugger agent for root-cause analysis
+- Inspect recent lines first
+- Capture stack traces, error codes, timestamps, and repeated patterns
+
+### Step 2: Scout the Codebase
+
+Use `pk:scout` or parallel Explore subagents to find affected code. See
+`references/parallel-exploration.md` for patterns.
+
+### Step 3: Plan the Fix
+
+Use the planner agent. Do not plan until log evidence and code paths agree on
+the root cause.
+
+### Step 4: Implement
+
+Implement the smallest cause-aligned fix.
+
+### Step 5: Test
+
+Use the tester agent. If the original symptom remains, return to Step 2 and
+re-diagnose before changing more code.
+
+### Step 6: Review
+
+Use the code-reviewer agent and retain fresh verification evidence.
+
+## Tips
+
+- Focus on the most recent errors first
+- Correlate stack traces, error codes, and timestamps
+- Group repeated errors before forming hypotheses

package/skills/fix/references/workflow-quick.md

@@ -0,0 +1,99 @@
+# Quick Workflow
+
+Fast scout-diagnose-fix-verify cycle for simple issues.
+
+The parent skill's opening intent frame is already satisfied before this route
+loads. Quick mode does not skip or repeat it.
+
+## Steps
+
+### Step 1: Scout (Minimal)
+Locate affected file(s) and their direct dependencies only.
+- Read error message → identify file path
+- Check direct imports/dependencies of affected file
+- Skip full codebase mapping
+
+**Output:** `✓ Step 1: Scouted - [file], [N] direct deps`
+
+### Step 2: Diagnose (Abbreviated)
+Activate `pk:debug` skill. Activate `pk:sequential-thinking` for structured analysis.
+
+- Read error message/logs
+- **Capture pre-fix state:** Record exact error output (this is your verification baseline)
+- Identify root cause (usually obvious for simple issues)
+- Skip parallel hypothesis testing for trivial cases
+- Confirm there is one direct, cause-aligned repair. If meaningful alternatives
+  remain, escalate to Standard or Deep before implementation.
+
+**Output:** `✓ Step 2: Diagnosed - Root cause: [brief description]`
+
+### Step 3: Fix & Verify
+Implement the fix directly.
+- Make minimal changes
+- Follow existing patterns
+- Preserve the opening constraints and non-goals
+
+**Parallel Verification:**
+Launch run_shell-capable agents in parallel:
+```
+delegate_agent capability("run_shell", "Run typecheck", "Verify types")
+delegate_agent capability("run_shell", "Run lint", "Verify lint")
+```
+
+**Before/After comparison:** Re-run the EXACT command from pre-fix state capture. Compare output.
+
+See `references/parallel-exploration.md` for patterns.
+
+**Output:** `✓ Step 3: Fixed - [N] files, verified (types/lint passed)`
+
+### Step 4: Review + Prevent
+Use `code-reviewer` subagent for quick review with explicit side-effect sweep.
+
+Prompt: "Quick review of fix for [issue]. Check: (a) acceptance criteria met, (b) no regression to business logic in blast-radius from Step 1 scout, (c) no breaking changes to public contracts (signatures, schemas, APIs, env vars), (d) follows existing patterns, (e) no new lint/type/build errors. Score X/10. Explicitly flag any side effects."
+
+See HARD-GATE-NO-SIDE-EFFECTS in SKILL.md — on reviewer-flagged regression → `ask_user capability` with 2-4 options (revert / narrow / update dependents / accept).
+
+**Prevention (abbreviated for Quick):**
+- Type errors/lint: type system IS the test → regression test optional
+- Bug fixes: add at least 1 test covering the fixed scenario
+- Still require before/after comparison of verification output
+
+**Review handling:** See `references/review-cycle.md`
+
+**Output:** `✓ Step 4: Review [score]/10 - [prevention measures]`
+
+### Step 5: Report
+Report summary to user (root cause, files changed, prevention).
+
+**Output:** `✓ Step 5: Reported`
+
+### Step 6: Finalize (MANDATORY — every fix)
+1. **Activate `the engineer project-management skill` skill (MANDATORY)** → sync plan status if the fix is part of a plan, update progress, and refresh runtime tracking when available.
+2. Evaluate docs impact; use `docs-manager` only when a routed authority surface changed.
+3. Reflect completion in the live task-management surface when available.
+4. Spawn `git-manager` subagent to commit.
+5. Run `/pk:journal` to log decisions — unless the shared "Journal step — opt-out" applies (see SKILL.md; skip when `--skip-journal` or `journal.auto=false`).
+
+**Output:** `✓ Step 6: Finalized - sync-back complete, committed, journaled`
+
+## Skills/Subagents Activated
+
+| Step | Skills/Subagents |
+|------|------------------|
+| 1 | `pk:scout` (minimal) or direct file read |
+| 2 | `pk:debug`, `pk:sequential-thinking` |
+| 3 | Parallel `run_shell` for verification |
+| 4 | `code-reviewer` subagent |
+| 5 | Report |
+| 6 | `the engineer project-management skill` (MANDATORY), conditional `docs-manager`, `git-manager`, `/pk:journal` (unless the shared "Journal step — opt-out" applies — see SKILL.md) |
+
+**Extra:** `pk:context-engineering` if dealing with AI/LLM code
+
+## Notes
+
+- Skip if review fails → escalate to Standard workflow
+- Total steps: 6
+- No planning phase needed
+- Opening brainstorm contract is inherited from the parent skill
+- Pre-fix state capture is STILL mandatory (even for quick fixes)
+- Step 6 finalize is MANDATORY for every fix — `the engineer project-management skill` is NOT optional

package/skills/fix/references/workflow-standard.md

@@ -0,0 +1,127 @@
+# Standard Workflow
+
+Full pipeline for moderate complexity issues. Discover the live
+task-management surface and use it for phase tracking when available.
+Otherwise, update the active plan. Plan files are the durable source of truth.
+
+The parent skill captures the opening intent frame before this route loads.
+
+## Plan Setup (Before Starting)
+
+Record the phase dependency order upfront. Mirror it into the live
+task-management surface when available; otherwise keep it in the active plan.
+
+- Scout codebase
+- Diagnose root cause
+- Implement fix, blocked by scout + diagnose
+- Verify + prevent, blocked by implementation
+- Code review, blocked by verification
+- Finalize, blocked by review
+
+## Steps
+
+### Step 1: Scout Codebase
+Record the scout phase as active.
+
+**Mandatory skill chain:**
+1. Activate `pk:scout` skill OR launch 2-3 parallel `Explore` subagents when delegation is explicitly requested/permitted.
+2. Map: affected files, module boundaries, dependencies, related tests, recent git changes.
+
+**Pattern:** If delegation is permitted, launch 2-3 Explore agents in one
+assistant turn through `delegate_agent`. In Codex Desktop, expose deferred
+multi-agent tools with `tool_search` first, then use
+`multi_agent_v1.spawn_agent(agent_type="Explore", message="...")`.
+
+See `references/parallel-exploration.md` for patterns.
+
+Record the scout phase as completed after its evidence is captured.
+**Output:** `✓ Step 1: Scouted [N] areas - [M] files, [K] tests found`
+
+### Step 2: Diagnose Root Cause
+Record the diagnose phase as active.
+
+**Mandatory skill chain:**
+1. **Capture pre-fix state:** Record exact error messages, failing test output, stack traces.
+2. Activate `pk:debug` skill. Use `debugger` subagent if needed.
+3. Activate `pk:sequential-thinking` — form hypotheses through structured reasoning.
+4. Use delegated `Explore` subagents to test hypotheses only when delegation is explicitly requested/permitted.
+5. If 2+ hypotheses fail → auto-activate `pk:problem-solving`.
+6. Trace backward to root cause (not just symptom location).
+
+Use the root-cause checklist in the parent skill as the diagnosis protocol.
+
+Record the diagnose phase as completed after the root cause is proven.
+**Output:** `✓ Step 2: Diagnosed - Root cause: [summary], Evidence: [brief], Scope: [N files]`
+
+Before implementation, compare only cause-aligned fixes. Record the direct
+choice and its fit with the opening acceptance criteria. If multiple viable
+approaches or an architecture decision remain, activate `pk:brainstorm` and
+escalate to Deep workflow for a plan.
+
+### Step 3: Implement Fix
+Record the implementation phase as active once scout and diagnosis are complete.
+
+Fix the ROOT CAUSE per diagnosis findings. Not symptoms.
+
+- Apply `pk:problem-solving` skill if stuck
+- Use `pk:sequential-thinking` for complex logic
+- Minimal changes. Follow existing patterns.
+- Preserve the opening constraints and non-goals.
+
+Record the implementation phase as completed.
+**Output:** `✓ Step 3: Implemented - [N] files changed`
+
+### Step 4: Verify + Prevent
+Record the verify phase as active.
+
+**Mandatory skill chain:**
+1. **Iron-law verify:** Re-run the EXACT commands from pre-fix state capture. Compare before/after.
+2. **Regression test:** Add/update test(s) covering the fixed issue. Test MUST fail without fix, pass with fix.
+3. **Side-effect sweep (HARD-GATE-NO-SIDE-EFFECTS):** Walk each dependent caller of changed functions from Step 1 blast-radius. Run tests in modules that share files/contracts. Confirm public contracts (signatures, schemas, APIs, env vars) unchanged. See SKILL.md HARD-GATE-NO-SIDE-EFFECTS.
+4. **Defense-in-depth:** Apply the relevant prevention layers from the parent skill.
+5. **Verification commands:** Run typecheck, lint, build, and tests through the
+   `run_shell` capability. Delegate verification only when the user explicitly
+   requested parallel delegation and the runtime permits it.
+
+**On regression / side effect:** `ask_user capability` with 2-4 concrete options (revert / narrow scope / update dependents / accept). Never silently patch.
+
+**If verification fails:** Loop back to Step 2 (re-diagnose). Max 3 attempts.
+
+Record the verify phase as completed only after fresh evidence passes.
+**Output:** `✓ Step 4: Verified + Prevented - [before/after], [N] tests added, [M] guards`
+
+### Step 5: Code Review
+Record the review phase as active.
+Use `code-reviewer` through `delegate_agent` when delegation is explicitly
+requested/permitted; otherwise review the changed files locally.
+
+See `references/review-cycle.md` for mode-specific handling.
+
+Record the review phase as completed after accepted findings are resolved.
+**Output:** `✓ Step 5: Review [score]/10 - [status]`
+
+### Step 6: Finalize
+Record the finalize phase as active.
+- Report summary: root cause, changes, prevention measures, confidence score
+- Activate `pk:project-management` for task sync-back and plan status updates
+- Evaluate docs impact and use `docs-manager` only for affected authority surfaces
+- Ask to commit via git workflow or delegated git-manager when explicitly requested/permitted
+- Run `/pk:journal` — unless the shared "Journal step — opt-out" applies (see SKILL.md; skip when `--skip-journal` or `journal.auto=false`)
+
+Record the finalize phase as completed in the live surface when available and in the active plan.
+**Output:** `✓ Step 6: Complete - [action]`
+
+## Skills/Subagents Activated
+
+| Step | Skills/Subagents |
+|------|------------------|
+| 1 | `pk:scout` OR parallel `Explore` subagents when delegation is permitted |
+| 2 | `pk:debug`, `pk:sequential-thinking`, optional delegated debugger/Explore when permitted, (`pk:problem-solving` auto), conditional `pk:brainstorm` after diagnosis |
+| 3 | `pk:problem-solving` (if stuck), `pk:sequential-thinking` (complex logic) |
+| 4 | `run_shell` verification; optional delegated tester/workers when permitted |
+| 5 | `code-reviewer` via `delegate_agent` when permitted, otherwise local review |
+| 6 | `pk:project-management`; docs/git delegation only when permitted |
+
+**Rules:** Don't skip steps. Validate before proceeding. One phase at a time.
+**Frontend:** Use `pk:agent-browser`, Chrome MCP / `chrome-devtools-mcp`, or any relevant project-native browser tests to verify.
+**Visual Assets:** Use `pk:ai-multimodal` for visual assets generation, analysis and verification.

package/skills/fix/references/workflow-test.md

@@ -0,0 +1,57 @@
+# Test Failure Fix Workflow
+
+For fixing failing tests and test-suite regressions.
+
+## Progress Tracking
+
+The stages are `collect failures → diagnose → plan → implement → retest →
+review`. Discover the live task-management surface and mirror this dependency
+chain when available. Otherwise, update the active plan. Plan files are the
+durable source of truth.
+
+## Workflow
+
+### Step 1: Compile and Collect Failures
+
+Use the tester agent. Fix syntax or compilation errors before running behavior
+tests. Run the relevant suite, collect every failure, and group failures by
+module or likely shared cause.
+
+### Step 2: Debug
+
+Use the debugger agent. Analyze each failure group and prove shared root causes
+before modifying code.
+
+### Step 3: Plan
+
+Use the planner agent. Prioritize shared root causes first and record
+dependencies between fixes.
+
+### Step 4: Implement
+
+Implement fixes in dependency order and keep changes cause-aligned.
+
+### Step 5: Retest
+
+Use the tester agent. Start with the narrow failing test, then broaden across
+the blast radius. If tests still fail, return to Step 2.
+
+### Step 6: Review
+
+Use the code-reviewer agent and retain fresh test evidence.
+
+## Common Commands
+
+```bash
+npm test
+bun test
+pytest
+go test ./...
+```
+
+## Tips
+
+- Run one failing test first for faster iteration
+- Compare assertions with intended behavior
+- Verify fixtures and mocks represent real contracts
+- Change a test only when evidence proves the test is wrong

package/skills/fix/references/workflow-types.md

@@ -0,0 +1,33 @@
+# Type Error Fix Workflow
+
+Quick workflow for TypeScript/type errors.
+
+## Commands
+```bash
+bun run typecheck
+tsc --noEmit
+npx tsc --noEmit
+```
+
+## Rules
+- Fix ALL type errors, don't stop at first
+- **NEVER use `any` just to pass** - find proper types
+- Repeat until zero errors
+
+## Common Fixes
+- Missing type imports
+- Incorrect property access
+- Null/undefined handling
+- Generic type parameters
+- Union type narrowing
+
+## Workflow
+1. Run typecheck command
+2. Fix errors one by one
+3. Re-run typecheck
+4. Repeat until clean
+
+## Tips
+- Group related errors (same root cause)
+- Check `@types/*` packages for library types
+- Use `unknown` + type guards instead of `any`