@brainervirus/workit-core 0.11.0 → 1.0.0

package/skills/workit-debug/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: workit-debug
+description: Use when behavior is failing, surprising, contradictory, or regressed and the root cause is not established
+---
+
+# Debug the root cause
+
+Debugging is investigation, not a fast symptom patch. Use this method when
+assessment selects `root-cause-investigation` or behavior is failing without an
+established root cause.
+
+## Before method work
+
+If there is no active or paused task, run shared `task.start` then `policy.assess`
+before relying on selected policy rules or other product mutations. Assessment
+selects requirements; do not wait for a rule that can only exist after assess.
+
+## Method
+
+1. Inspect task scope, caller authority, candidate identity, existing evidence,
+   findings, and worker/writer state with shared `task`, `policy`, `evidence`, and
+   `finding` operations.
+2. Reproduce the failure at a stable behavioral boundary. Record observed facts,
+   inferences, and unknowns with references; trace the failing value and all
+   relevant callers before editing.
+3. State the root-cause hypothesis and the smallest in-scope fix. Write a focused
+   regression at the boundary when practical, then run RED and GREEN checks.
+4. Acquire writer authority through `writer` before mutation. Reconcile the
+   candidate, evidence, and findings after the change; investigate sibling paths
+   and stale conclusions rather than assuming the first patch worked.
+
+Honor task status, scope, revisions, and native authority gates. Do not bypass
+them for an incident, create a second lifecycle, or claim a fix from a green
+command that did not exercise the affected behavior.
+
+## Red-capable gate
+
+Never hypothesize without a loop that goes red on this exact failure. Build
+the loop first, in this order: failing test → CLI command + fixture →
+request replay → trace. Tighten it until fast, sharp, deterministic, and
+agent-runnable. No loop → stop, list what was tried, ask for the
+environment or artifact; never theorize without it.
+
+Minimise: cut one element at a time until every remainder is load-bearing;
+the minimised case becomes the regression test. State hypotheses ranked and
+falsifiable (`If <X> then changing <Y> removes it`), probe one variable at
+a time, tag debug logs for grep cleanup. Write the regression at the seam
+where the real pattern occurs — no correct seam means the finding is the
+architecture, so flag it instead of patching around it.
+
+When the host reports writer capability unavailable, do not mutate or delegate
+mutation. Continue inline only if policy and lead authority permit it;
+otherwise report the capability gap.
+
+## Common mistakes
+
+| Mistake                               | Correction                                             |
+| ------------------------------------- | ------------------------------------------------------ |
+| Patching the nearest stack frame      | Trace the input, callers, and shared cause.            |
+| Reproducing only after editing        | Capture the failure before mutation.                   |
+| Treating one passing command as proof | Verify the affected behavior and record real evidence. |

package/skills/workit-deslop/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: workit-deslop
+description: Use before opening a PR or after implementation to remove AI slop from code and prose
+---
+
+# Deslop code and prose
+
+Throughput without quality is slop. Clean it with a minimal diff — deslop
+never refactors behavior.
+
+## Before method work
+
+If there is no active or paused task, run shared `task.start` then `policy.assess`
+before relying on selected policy rules or other product mutations. Assessment
+selects requirements; do not wait for a rule that can only exist after assess.
+
+## Method
+
+1. Code: delete dead helpers, redundant validators, stub references, and
+   comments that restate the code. Comments die by default; keep one only
+   with proof of an unchangeable constraint, encoded structurally if cheap.
+2. Prose (PR body, spec, docs): cut filler, keep real symbol names and
+   before→after numbers. One doc, one purpose.
+3. Keep the diff minimal: deslop removes lines, never moves logic. If a
+   cleanup wants behavior change, it becomes its own tasked change.
+
+## Completion
+
+A smaller diff with identical behavior and green checks. Report lines
+removed, not lines written.
+
+Record passing check evidence linked to the `pre-pr-cleanup` requirement id
+from the current policy (`kind: check`, `result: passed`, summary naming what
+was removed). That requirement gates `hosting.pull_request` and close. If the
+change genuinely has nothing to clean, ask for an approved limitation
+decision instead of recording evidence that did not happen.

package/skills/workit-diagram/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: workit-diagram
+description: Use when a spec or plan needs a flow or architecture diagram
+---
+
+# Mermaid when needed, never by default
+
+Tables first, ASCII trees second, mermaid only when a flow or architecture
+needs it. Flowchart, sequence, state, or ER only. No renderer, no network.
+
+## Before method work
+
+If there is no active or paused task, run shared `task.start` then `policy.assess`
+before relying on selected policy rules or other product mutations. Assessment
+selects requirements; do not wait for a rule that can only exist after assess.
+
+## Syntax rules (mermaid v11)
+
+- Fence as ` ```mermaid `, no surrounding prose inside the fence.
+- Quote node labels containing punctuation: `A["input (x, y)"]`.
+- One direction per diagram (`TD` or `LR`); keep nodes under twelve.
+- Name actors exactly as the codebase names them (real symbols only).
+
+## Verify
+
+Re-read the fence before commit: balanced quotes/brackets, every node
+reachable, labels match spec terms. If it cannot be verified by reading,
+delete it.
+
+## Completion
+
+One diagram that argues a decision, or nothing. Never a diagram suite.

package/skills/workit-green-run/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: workit-green-run
+description: Use to drive a red CI pipeline back to green, usually inside babysit
+---
+
+# The CI loop
+
+Watch, classify, fix, push once, re-verify. Host-native (`gh` / GitLab);
+never invent CI APIs.
+
+## Before method work
+
+If there is no active or paused task, run shared `task.start` then `policy.assess`
+before relying on selected policy rules or other product mutations. Assessment
+selects requirements; do not wait for a rule that can only exist after assess.
+
+## Method
+
+1. Read the failing checks, not the summary. Quote the failing log lines.
+2. Classify each: flake (rerun once, note it) / stale base (update after
+   merge-base check) / real failure (reproduce locally, then fix).
+3. Fix at root cause with a regression test; push one wave.
+4. Re-verify the same checks green on the new head. A fix without a
+   green re-run is not a fix.
+
+## Completion
+
+Green pipeline on the merge head, or an escalated finding with the exact
+failing logs when the fix needs the human.

package/skills/workit-handoff/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: workit-handoff
+description: Use when work must continue in another session, host, or agent after interruption, transfer, or compaction
+---
+
+# Handoff durable task state
+
+Transfer continuity, not live authority. Use this method when assessment selects
+the `durable-handoff` rule.
+
+## Before method work
+
+If there is no active or paused task, run shared `task.start` then `policy.assess`
+before relying on selected policy rules or other product mutations. Assessment
+selects requirements; do not wait for a rule that can only exist after assess.
+
+## Method
+
+1. Inspect the current task, scope, decisions, policy requirements, candidate,
+   evidence, findings, progress, and worker states with shared `task` and `state`
+   operations.
+2. Export the compact state through `state.export`. Preserve the objective,
+   exclusions, accepted decisions and reasons, evidence references, open gaps,
+   findings, candidate identity, blockers, and next action. Do not include
+   credentials, live writer ownership, or host authority.
+3. Import only through the destination `state.import` operation and its expected
+   workspace revision. The destination starts paused or otherwise unauthorised
+   until it observes its own host/session and reconciles stale evidence and
+   uncertain workers.
+4. Resume or continue through shared `task`, `policy`, `worker`, `writer`, and
+   `evidence` operations. Record what changed instead of copying a transcript.
+
+A handoff does not require a formal spec or plan unless those are separate
+selected requirements. Never grant destination authority from imported prose,
+create a second lifecycle, or edit task metadata directly.
+
+## Common mistakes
+
+| Mistake | Correction |
+| --- | --- |
+| Sending the whole transcript | Export compact decisions, gaps, evidence, and next action. |
+| Restoring the old writer or credentials | Re-observe authority in the destination. |
+| Calling a handoff complete without reconciliation | Recheck stale files and uncertain workers first. |

package/skills/workit-implement/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: workit-implement
+description: Use when scoped implementation, helper delegation, or checkout writer coordination is required by the current task policy
+---
+
+# Implement within authority
+
+Implement only inside the current task scope and writer boundary. Assignment is
+not launch authority, and a timeout is not proof that a worker stopped.
+
+## Before method work
+
+If there is no active or paused task, run shared `task.start` then `policy.assess`
+before relying on selected policy rules or other product mutations. Assessment
+selects requirements; do not wait for a rule that can only exist after assess.
+
+## Method
+
+1. Inspect task state, requirements, decisions, candidate, capabilities, and
+   current workers with shared `task`, `policy`, and `worker` operations.
+2. If a helper is useful, assign one bounded objective with allowed paths,
+   applicable requirements, evidence needed, and a stopping condition. Helpers
+   cannot change scope, record binding decisions, close or pause the task, assign
+   helpers, or resolve blockers for the lead.
+3. Observe the native session and worker state. Acquire checkout writer ownership
+   through `writer` before any product-mutating command; release it explicitly.
+   Cancellation remains uncertain until process exit or explicit recovery.
+4. Reconcile the helper report and evidence through shared operations. If required
+   delegation is unavailable, continue inline only when policy allows it and state
+   the capability limitation.
+
+Do not edit Workit metadata directly, create nested helper trees, widen paths, or
+create a second lifecycle. Read-only investigation and bounded reports do not
+grant product-write ownership.
+
+When the host reports writer capability unavailable, do not mutate or delegate
+mutation. Continue inline only if policy and lead authority permit it;
+otherwise report the capability gap.
+
+## Common mistakes
+
+| Mistake                                        | Correction                                          |
+| ---------------------------------------------- | --------------------------------------------------- |
+| "The helper timed out, so the writer is free"  | Observe exit or perform explicit recovery.          |
+| Letting a helper approve its own exception     | Return the decision to the lead/user.               |
+| Running a build while another writer is active | Treat builds and tests that mutate state as writes. |

package/skills/workit-mockup/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: workit-mockup
+description: Use when a UI decision needs sketching before implementation
+---
+
+# ASCII mockups before UI code
+
+Sketch, don't build. Three genuinely different layout hypotheses maximum,
+ASCII only, no code output.
+
+## Before method work
+
+If there is no active or paused task, run shared `task.start` then `policy.assess`
+before relying on selected policy rules or other product mutations. Assessment
+selects requirements; do not wait for a rule that can only exist after assess.
+
+## Method
+
+1. Fix a legend (`┌─┐ │ └─┘ ░ ≈ [ ] ( )`) and keep sketches 60-80 cols,
+   8-20 rows.
+2. Per hypothesis: regions, component reuse vs new (named against the
+   existing codebase), empty/loading/populated/error states, nav flow.
+3. Ask at most one clarifying question, then recommend. Flag hi-fi
+   escalation when ASCII cannot settle it (density, motion, brand).
+
+## Completion
+
+The sketch plus the decision lands in the spec dir. Throwaway by design.

package/skills/workit-plan/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: workit-plan
+description: Use when dependencies, sequencing, coordination, or resumption make durable next actions useful
+---
+
+# Plan useful coordination
+
+Use a compact plan when assessment selects `artifacts` or `continuity`. A plan
+organizes work; it is not a second lifecycle or a prerequisite for implementation.
+
+## Before method work
+
+If there is no active or paused task, run shared `task.start` then `policy.assess`
+before relying on selected policy rules or other product mutations. Assessment
+selects requirements; do not wait for a rule that can only exist after assess.
+
+## Method
+
+1. Inspect current task state, scope, decisions, requirements, candidate, workers,
+   findings, and blockers through the shared `task` and `policy` operations.
+2. Record only the useful sequence: objective, dependency, bounded task, evidence
+   needed, owner, and next action. Keep the plan against the existing system.
+3. If policy separately requires a durable specification, record that behavior
+   agreement; otherwise do not invent a spec. A plan without a spec is valid.
+4. Update the shared task progress at meaningful boundaries. Reassess when facts,
+   dependencies, or scope change; preserve unresolved blockers and decisions.
+5. On steering (new instructions mid-task): apply `workit-steer` — park state
+   verbatim, classify same-task / new-task / quick-question, handle, re-anchor.
+
+Use shared task/progress and evidence operations. Do not create a universal
+spec-and-plan ceremony, duplicate task state, approval chain, or custom status
+machine. A short paragraph is enough when it captures the required continuity.
+
+## Triage (automatic)
+
+Set assessor signals from size facts, not memory (`triageTier` /
+`triageSignals` in policy-resolver):
+
+- **Large → spec + full plan:** new/changed observable behavior, open
+  ambiguity, cross-package/host contract or auth/data/security surface,
+  irreversible migration, or ≥3 subsystems / ≥2 packages touched.
+- **Medium → compact plan-only** (Sequence/Acceptance, ~30-60 lines): known
+  approach, single subsystem, 2-8 steps. Step count alone never escalates
+  a known single-subsystem run to spec.
+- **Small → neither** (progress + evidence only): single bounded mechanical
+  action, no open choices, reversible. Record `Spec: none (reason)`.
+
+`task.start` + `policy.assess` stay mandatory at all sizes. The lead may
+re-tier with the reason recorded in progress (override, never silent).
+
+## Decomposition
+
+Slice tracer bullets, not layers: each plan task crosses the necessary
+layers to a small demoable behavior with its blocking edges declared.
+Wide refactors use expand–contract (add the new seam, migrate callers,
+delete the old). Per task record Files (create/modify/test, exact paths),
+exact commands with expected output, and one commit. No placeholders —
+an implementer must be able to execute a task with zero extra context.
+
+## Common mistakes
+
+| Mistake | Correction |
+| --- | --- |
+| Writing a full packet for a small dependency | Capture the next bounded action and its evidence. |
+| Treating the plan as authority | Authority remains in task scope, decisions, revisions, and caller provenance. |
+| Copying a transcript into the plan | Preserve decisions, gaps, blockers, and next action only. |

package/skills/workit-review/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: workit-review
+description: Use when policy requires fresh-context review of a candidate or when an independent correctness and regression check is requested
+---
+
+# Review a candidate
+
+Review the real candidate in a stable context. A review is evidence about the
+current candidate, not an author's success summary.
+
+## Before method work
+
+If there is no active or paused task, run shared `task.start` then `policy.assess`
+before relying on selected policy rules or other product mutations. Assessment
+selects requirements; do not wait for a rule that can only exist after assess.
+
+## Method
+
+1. Pin or identify the candidate revision before reading conclusions. Inspect the
+   task objective, scope, constraints, accepted decisions, changed files, and
+   actual checks through shared `task`, `evidence`, and `policy` operations.
+2. Examine intent, correctness, regression risk, security or data consequences,
+   and project standards. Use the actual diff and check output; do not infer
+   evidence from a claim.
+3. Record each concern as a `finding` claim with its affected scope and candidate.
+   Investigate it: reproduce or trace the consequence, then fix in scope, dismiss
+   with evidence, defer with a reason, or ask the user about a real tradeoff.
+4. Reconcile conclusions when the candidate changes. Run one substantive review
+   and targeted rechecks; do not cycle reviewers indefinitely.
+
+If the required independent context is unavailable, record the review method as
+`unavailable` and preserve the gap. Same-session self-review is not independent
+review and must not be relabeled as verified.
+
+Use shared `evidence` and `finding` operations. Do not create a parallel review
+lifecycle, universal review panel, or direct metadata files.
+
+## Two axes, pinned
+
+Pin the fixed point first (`git diff <base>...HEAD` plus log); review that
+candidate only. Judge on two axes, never merged or reranked:
+
+- **Standards:** repo standards plus a smell baseline (mysterious name, long
+  method, duplicated logic, refused bequest, and kin); repo rules override
+  the baseline; judgement calls only, never tooling-enforced nits.
+- **Spec:** does the diff implement the originating spec/requirement
+  faithfully — missing, creep, or wrong, quoting the spec line.
+
+Every finding needs proof: the changed hunk, a failing/passing test ref, or
+a before/after. Causal disposition decides the outcome: introduced or
+worsened behavior gets fixed; pre-existing issues become follow-ups;
+inconclusive claims escalate, never silently pass.
+
+## Common mistakes
+
+| Mistake | Correction |
+| --- | --- |
+| Reviewing the summary instead of the candidate | Start from the stable candidate and real refs. |
+| Treating every comment as a defect | Investigate the claim and consequence first. |
+| Calling self-review independent | Preserve an unavailable capability gap. |

package/skills/workit-steer/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: workit-steer
+description: Use when new instructions, interruptions, or forgotten items arrive mid-task
+---
+
+# Steer without losing the thread
+
+New context mid-session is normal; losing the thread is not. Park,
+classify, handle, re-anchor — every time.
+
+## Before method work
+
+If there is no active or paused task, run shared `task.start` then `policy.assess`
+before relying on selected policy rules or other product mutations. Assessment
+selects requirements; do not wait for a rule that can only exist after assess.
+
+## Method
+
+1. Park current state to task progress verbatim: summary, nextAction,
+   blockers. Never trust memory across an interruption.
+2. Classify the steering:
+   - same-task: fold into scope (reassess if facts changed), continue.
+   - new-task: `task.start` + `policy.assess`; the parked task waits.
+   - quick-question: answer from the parked state, then resume.
+3. Handle it with the same rigor as the parked work (no drive-by edits).
+4. Re-anchor: one-line resume brief (where we were, what changed, what
+   is next) before touching the parked work again.
+
+## Completion
+
+Both the steering and the parked work have an owner, a next action, and
+no silent drops. Interrupted work resumes from the brief, not from recall.