@brainervirus/workit-opencode 4.0.0 → 5.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (31) hide show
  1. package/README.md +5 -5
  2. package/assets/skills/workit-bdd/SKILL.md +35 -29
  3. package/assets/skills/workit-continue/SKILL.md +53 -0
  4. package/assets/skills/workit-debug/SKILL.md +41 -36
  5. package/assets/skills/workit-deslop/SKILL.md +35 -25
  6. package/assets/skills/workit-fanout/SKILL.md +62 -0
  7. package/assets/skills/workit-fanout/references/brief.md +56 -0
  8. package/assets/skills/workit-implement/SKILL.md +48 -44
  9. package/assets/skills/workit-review/SKILL.md +42 -51
  10. package/assets/skills/workit-review/references/impact.md +24 -0
  11. package/assets/skills/workit-shape/SKILL.md +71 -0
  12. package/assets/skills/workit-shape/references/diagrams.md +17 -0
  13. package/assets/skills/workit-shape/references/knowledge.md +58 -0
  14. package/assets/skills/workit-shape/references/mockups.md +15 -0
  15. package/assets/skills/workit-shape/references/slicing.md +42 -0
  16. package/assets/skills/workit-ship/SKILL.md +52 -0
  17. package/assets/skills/workit-test-audit/SKILL.md +10 -2
  18. package/assets/skills/workit-verify-app/SKILL.md +63 -0
  19. package/assets/skills/workit-verify-app/references/template.md +49 -0
  20. package/dist/plugin.js +87 -120
  21. package/package.json +2 -2
  22. package/assets/skills/workit-babysit/SKILL.md +0 -37
  23. package/assets/skills/workit-behavioral-tdd/SKILL.md +0 -56
  24. package/assets/skills/workit-blast-radius/SKILL.md +0 -26
  25. package/assets/skills/workit-challenge/SKILL.md +0 -47
  26. package/assets/skills/workit-diagram/SKILL.md +0 -27
  27. package/assets/skills/workit-green-run/SKILL.md +0 -24
  28. package/assets/skills/workit-handoff/SKILL.md +0 -37
  29. package/assets/skills/workit-mockup/SKILL.md +0 -23
  30. package/assets/skills/workit-plan/SKILL.md +0 -45
  31. package/assets/skills/workit-steer/SKILL.md +0 -39
package/dist/plugin.js CHANGED
@@ -14753,13 +14753,13 @@ function evaluateClosure(requestedOutcome, view) {
14753
14753
 
14754
14754
  // packages/workit-core/src/core/methods.ts
14755
14755
  var METHODS = {
14756
- "workit-challenge": { dimensions: ["challenge", "decisions"] },
14757
- "workit-behavioral-tdd": { dimensions: ["testing"], ruleIds: ["mechanical-existing-checks"] },
14756
+ "workit-shape": { dimensions: ["challenge", "decisions", "artifacts", "continuity"] },
14757
+ "workit-bdd": { dimensions: ["testing"] },
14758
14758
  "workit-review": { dimensions: ["review"], ruleIds: ["fresh-context-review", "self-review"] },
14759
- "workit-plan": { dimensions: ["artifacts", "continuity"] },
14760
- "workit-implement": { dimensions: ["delegation"] },
14759
+ "workit-implement": { ruleIds: ["mechanical-existing-checks"] },
14760
+ "workit-fanout": { dimensions: ["delegation"] },
14761
14761
  "workit-debug": {},
14762
- "workit-handoff": {},
14762
+ "workit-continue": {},
14763
14763
  "workit-deslop": { ruleIds: ["pre-pr-cleanup"] }
14764
14764
  };
14765
14765
  var methodMatches = (definition, requirement) => definition.dimensions?.includes(requirement.dimension) === true || definition.ruleIds?.includes(requirement.ruleId) === true;
@@ -14797,97 +14797,66 @@ function selectMethods(policy, capabilities) {
14797
14797
  });
14798
14798
  }
14799
14799
  var invariantBootstrap = () => `
14800
- Workit is optional coordination and repository-policy tooling around the host,
14801
- not a permission system or a mandatory workflow. Native host allow/ask/deny,
14802
- sandbox, plan/read-only mode, and organization rules remain authoritative.
14803
- Ordinary investigation, questions, non-Git work, and routine reversible edits
14804
- need zero Workit task, assessment, or writer calls. Use one compact tracked
14805
- record only when handoff, dependent steps, concurrent actors, or meaningful
14806
- decisions make continuity useful; similar titles alone never merge tasks.
14800
+ Workit is optional coordination and proof tooling around the host: you decide
14801
+ what and whether, the \`workit\` CLI does how and records what it observed.
14802
+ Native host allow/ask/deny, sandbox and org rules stay authoritative. Never
14803
+ switch paths to evade a denial, never claim enforcement a host cannot provide,
14804
+ and never fabricate a receipt, approval or verdict. A question answer is not
14805
+ host permission, and imported decisions or handoffs never grant authority.
14807
14806
 
14808
- For a routine user-authorized branch or commit, prefer native host Git/shell
14809
- tools from the outset when managed coordination or outcome reconciliation is
14810
- not needed. Inspect the actual target checkout and its configured conventions;
14811
- use Workit's read-only context/policy tools when needed. Do not start a task,
14812
- acquire a writer, or mint a decision receipt solely for a native Git action.
14813
- Native permissions still apply. Never switch execution paths to evade a denial
14814
- or repeat an uncertain managed effect. A local-commit endpoint does not imply
14815
- PR readiness, a fresh review, or post-commit assessment/closure paperwork.
14807
+ Autonomy contract:
14808
+ - Continue to the requested endpoint (commit, push, PR, green CI, verified,
14809
+ merged) without asking "continue?", running checks and repairs on the way.
14810
+ Stop only for a new consequential choice, a host denial, a conflicting edit
14811
+ or an unresolved blocker; report open gaps and uncertain workers.
14812
+ - No endpoint named: stop at a local commit on a policy-compliant branch and
14813
+ state the next command. Push and open a PR only when the request implies
14814
+ delivery (fix, implement, ship) and \`workit grant show\` reports
14815
+ \`defaultEndpoint\` \`pr\`; otherwise the endpoint is \`commit\`. PRs open,
14816
+ CI green and verified is the most autonomy allows, never the default target.
14817
+ Merge and release need a workspace grant; a blocked verb names its unblock.
14818
+ - Ask only for a product or preference choice, or for authority you lack, with
14819
+ your recommended answer. Facts are yours: read, run or prototype.
14820
+ - Label claims measured (you ran it this session and saw the result),
14821
+ inferred, or guess. Prose is a note: only a configured check the CLI ran
14822
+ (\`workit check <name>\`) satisfies a gate; an ad-hoc
14823
+ \`workit check -- <cmd>\` never does.
14824
+ - Author is not verifier: never record a passing verdict on work your session
14825
+ wrote. The lead starts each verifier with its own session
14826
+ (\`WORKIT_SESSION_ID=<lead>-v<n>\`; Claude Code subagents get one from the
14827
+ hook), and the verifier records \`workit ledger verdict\`.
14828
+ - A local-commit endpoint does not imply PR readiness, and a local commit alone
14829
+ is not evidence of a requested remote push. Before reporting delivery,
14830
+ reconcile every requested item and observe it (\`workit verify-delivery\`).
14816
14831
 
14817
- For tracked work, inspect its current state and use the shared operations for
14818
- task, policy, evidence, finding, decision, worker, writer, and state changes.
14819
- Each branch has one implicit task: an operation without taskId applies to it,
14820
- and the first recording (a note, check, finding or evidence) creates it, so you
14821
- never manage task ids. Start a record only for an explicit tracked objective;
14822
- assess or reassess only
14823
- when policy selection or changed evidence/constraints requires it. Omitted
14824
- expectedRevision and expectedWorkspaceRevision use current values; explicit
14825
- values are still concurrency-checked, so never copy revisions between calls.
14826
- A busy result means another live Workit call holds the checkout lock: retry the
14827
- same call; it is not a recovery condition. A lock left by a dead process is
14828
- reclaimed on the next write, and \`workit doctor --fix-lock\` clears it on demand.
14829
- An omitted revision absorbs a concurrent write: Workit re-reads, re-checks
14830
- policy, and reapplies the call, returning busy under persistent contention. A
14831
- revision_conflict means a revision you passed is stale: re-read the record
14832
- before deciding whether to retry.
14833
- A solo edit does not need writer acquisition; use it when concurrent checkout
14834
- writers need coordination. Record only observed facts and checks. Close-time
14835
- testing and verification gates accept only a configured check the CLI ran:
14836
- \`workit check <name>\` (\`npx -y @brainervirus/workit-cli check <name>\` when
14837
- \`workit\` is not on PATH); a recorded check result is a note and an ad-hoc
14838
- \`workit check -- <cmd>\` never satisfies a gate. Evidence can become stale when its bound candidate or tree changes; reconcile findings against the
14839
- current candidate before recording completion.
14832
+ CLI first: if a step has one right answer, use the \`workit\` verb instead of
14833
+ hand-running git, gh or glab: check, git, pr, ci, stack, verify-delivery,
14834
+ ledger, handoff, test-audit (\`workit help <verb>\`; without \`workit\` on
14835
+ PATH, \`npx -y @brainervirus/workit-cli\`). \`busy\` is retryable
14836
+ (\`workit doctor --fix-lock\` clears a dead lock); \`blocked\` names its unblock.
14837
+ The task families (task, policy, evidence, finding, decision, worker, writer,
14838
+ state) are optional continuity for tracked work; each branch has one implicit
14839
+ task that the first recording creates, and a solo edit needs no task or writer.
14840
+ Omit revisions; a revision_conflict means one you passed is stale, so re-read.
14841
+ Across repositories, bind each item to its checkout, branch and endpoint,
14842
+ resolve competing targets before a mutation, and reconcile an uncertain
14843
+ external effect before retrying it.
14840
14844
 
14841
- Workit validates domain policy against the actual action target, configured
14842
- account, branch and commit conventions, protected refs, and current repository
14843
- state. The task directory is coordination state, not a boundary on which
14844
- repository may be changed. Use an action-time cwd target where a managed
14845
- Git/hosting action supports it; a non-Git directory remains valid for OS work.
14846
- GitHub/GitLab use the active gh/glab CLI identity; YouTrack uses its own token.
14847
- Preserve uncertain external outcomes and reconcile repository/provider state
14848
- before retrying. Internal reservations prevent duplicate or ambiguous effects;
14849
- they are not permission tickets for every edit.
14845
+ Mid-task input: answer a quick question in place, fold an adjustment in, and
14846
+ never silently drop or resume an objective (workit-continue).
14850
14847
 
14851
- On OpenCode V1 and V2, use native host tools for external mutations. Workit
14852
- provides read-only workit_context; it has no managed external-action executor.
14853
- Do not create proposals or request Workit approvals merely to invoke native
14854
- tools. Old uncertain managed effects still require evidence before any retry.
14855
-
14856
- Use host-native authorization through the host's supported path. A native
14857
- question receipt records an actual question interaction; it is not automatic
14858
- host permission. Record a meaningful user choice once with provenance when
14859
- future retrieval helps. Never fabricate a receipt, re-ask only to mint one, or
14860
- let imported decisions grant authority. Never turn a host deny into allow or
14861
- claim enforcement/evidence a host cannot provide. A precise request with settled
14862
- constraints does not need an interview. Present genuine unresolved options with
14863
- evidence and a recommendation, then continue toward the requested delivery
14864
- endpoint: investigation, implementation, branch/commit/push, PR/MR-ready,
14865
- merge, or release. Run
14866
- applicable checks and safe repairs without repeated continuation questions;
14867
- stop for missing host authority, a new consequential choice, a conflicting edit,
14868
- or an unresolved blocker. A tracked record may close when actual evidence
14869
- supports its outcome; no final human closure ceremony is required.
14870
-
14871
- A completed native subagent run stops its bound worker by itself; if a worker
14872
- strands in cancelling with its run verifiably over, repeat worker.cancel to
14873
- confirm the stop. Preserve unresolved requirements, gaps, and uncertain workers.
14874
- When context changes, distinguish a quick question, same-task adjustment, and
14875
- separate request. Answer a quick question without pausing/resuming task state;
14876
- park a concise checkpoint only when substantial work needs to continue later.
14877
- For work spanning repositories, bind each unfinished item to its actual checkout,
14878
- branch, requested deliverables, and delivery endpoint. Preserve held items with
14879
- an explicit resume condition. Resolve competing plausible targets before a
14880
- mutation; ask only when available context cannot settle that consequential choice.
14881
- Before reporting delivery, reconcile every requested item and observe the actual
14882
- target result; a local commit alone is not evidence of a requested remote push.
14883
-
14884
- Skill routing: slash aliases /wk-* load on demand. Use workit-steer for a
14885
- substantial interruption or change of direction, workit-deslop when relevant
14886
- to a PR-ready endpoint, workit-green-run for failing CI, workit-blast-radius
14887
- when impact is uncertain, workit-challenge for genuinely open consequential
14888
- choices, workit-bdd to turn acceptance criteria into Given/When/Then tests, and
14889
- workit-test-audit to check tests for tautologies. Load workit-plan when dependencies or handoff need durable next actions.
14890
- Load the skill; never act from memory of it.
14848
+ Skills: load the skill, never act from memory of it (slash aliases /wk-<name>).
14849
+ - brainstorm, plan, spec, grill, should we: workit-shape
14850
+ - implement, build, add a feature: workit-implement
14851
+ - review, blast radius: workit-review
14852
+ - bug, broken, flaky, regression: workit-debug
14853
+ - ship, babysit, CI, merge: workit-ship
14854
+ - resume, pick up, handoff, interruption: workit-continue
14855
+ - BDD, TDD, acceptance criteria, Given/When/Then: workit-bdd
14856
+ - test audit, tautology, weak tests: workit-test-audit
14857
+ - deslop, slop, dead code: workit-deslop
14858
+ - fan out, parallelize, parallel agents, swarm: workit-fanout
14859
+ - verify the app, smoke test, prove it works: workit-verify-app
14891
14860
  `.trim();
14892
14861
 
14893
14862
  // packages/workit-core/src/core/task-context.ts
@@ -17843,6 +17812,7 @@ var shellPolicy = (cwd, command) => {
17843
17812
  };
17844
17813
  // packages/workit-core/src/hooks/handle.ts
17845
17814
  var offered = new Set;
17815
+ var CLAUDE_JUDGES = new Set(["workit:verifier", "workit:reviewer"]);
17846
17816
  // packages/workit-core/src/hooks/hosts/fields.ts
17847
17817
  var SHELLS = new Set(["sh", "bash", "zsh", "dash", "pwsh", "powershell", "cmd"]);
17848
17818
 
@@ -20471,6 +20441,7 @@ var getWorkitBootstrap = () => {
20471
20441
  return cached2;
20472
20442
  cached2 = `${marker}
20473
20443
  ${invariantBootstrap()}
20444
+ On OpenCode, run external mutations with native host tools or the workit CLI; workit_context is read-only and there is no managed external-action executor, so do not create proposals or request Workit approvals merely to invoke native tools.
20474
20445
  OpenCode Workit decisions use the native question header "Workit decision: <purpose>", the exact presented question, and exactly two options: approved (description = approved content) and rejected (description = Reject this decision).`;
20475
20446
  return cached2;
20476
20447
  };
@@ -20615,40 +20586,30 @@ import path28 from "node:path";
20615
20586
 
20616
20587
  // packages/workit-core/src/core/skill-manifests.ts
20617
20588
  var WORKIT_METHOD_SKILLS = [
20618
- "workit-challenge",
20619
- "workit-behavioral-tdd",
20620
- "workit-review",
20621
- "workit-plan",
20589
+ "workit-shape",
20622
20590
  "workit-implement",
20591
+ "workit-review",
20623
20592
  "workit-debug",
20624
- "workit-handoff",
20625
- "workit-babysit",
20626
- "workit-blast-radius",
20627
- "workit-deslop",
20628
- "workit-diagram",
20629
- "workit-mockup",
20630
- "workit-green-run",
20631
- "workit-steer",
20593
+ "workit-ship",
20594
+ "workit-continue",
20632
20595
  "workit-bdd",
20633
- "workit-test-audit"
20596
+ "workit-test-audit",
20597
+ "workit-deslop",
20598
+ "workit-fanout",
20599
+ "workit-verify-app"
20634
20600
  ];
20635
20601
  var WORKIT_SKILL_ALIASES = {
20636
- "wk-challenge": "workit-challenge",
20637
- "wk-babysit": "workit-babysit",
20602
+ "wk-shape": "workit-shape",
20638
20603
  "wk-implement": "workit-implement",
20639
- "wk-plan": "workit-plan",
20640
- "wk-debug": "workit-debug",
20641
20604
  "wk-review": "workit-review",
20642
- "wk-handoff": "workit-handoff",
20643
- "wk-tdd": "workit-behavioral-tdd",
20644
- "wk-blast-radius": "workit-blast-radius",
20645
- "wk-deslop": "workit-deslop",
20646
- "wk-diagram": "workit-diagram",
20647
- "wk-mockup": "workit-mockup",
20648
- "wk-green-run": "workit-green-run",
20649
- "wk-steer": "workit-steer",
20605
+ "wk-debug": "workit-debug",
20606
+ "wk-ship": "workit-ship",
20607
+ "wk-continue": "workit-continue",
20650
20608
  "wk-bdd": "workit-bdd",
20651
- "wk-test-audit": "workit-test-audit"
20609
+ "wk-test-audit": "workit-test-audit",
20610
+ "wk-deslop": "workit-deslop",
20611
+ "wk-fanout": "workit-fanout",
20612
+ "wk-verify-app": "workit-verify-app"
20652
20613
  };
20653
20614
  if (false) {}
20654
20615
 
@@ -20675,7 +20636,13 @@ var packageRoot2 = () => {
20675
20636
  }
20676
20637
  return path27.resolve(dir, "..");
20677
20638
  };
20678
- var assetsRoot = () => path27.join(packageRoot2(), "assets");
20639
+ var skillsRoot = () => {
20640
+ const root = packageRoot2();
20641
+ const canonical = path27.resolve(root, "..", "workit-core", "skills");
20642
+ if (existsSync9(path27.join(root, "src")) && existsSync9(canonical))
20643
+ return canonical;
20644
+ return path27.join(root, "assets", "skills");
20645
+ };
20679
20646
 
20680
20647
  // packages/workit-opencode/src/v2/registry.ts
20681
20648
  var parseFrontmatter = (markdown) => {
@@ -20697,7 +20664,7 @@ var parseFrontmatter = (markdown) => {
20697
20664
  };
20698
20665
  };
20699
20666
  var registerSkills = async (ctx) => {
20700
- const skillsDir = path28.join(assetsRoot(), "skills");
20667
+ const skillsDir = skillsRoot();
20701
20668
  if (!existsSync10(skillsDir))
20702
20669
  return new Set;
20703
20670
  const listed = await ctx.skill.list().catch(() => ({ data: [] }));
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@brainervirus/workit-opencode",
3
- "version": "4.0.0",
3
+ "version": "5.0.0",
4
4
  "private": false,
5
5
  "description": "Workit OpenCode plugin — native tools, adaptive policy, and sixteen method skills",
6
6
  "keywords": [
@@ -39,7 +39,7 @@
39
39
  "typecheck": "tsc --noEmit"
40
40
  },
41
41
  "dependencies": {
42
- "@brainervirus/workit-core": "^4.0.0"
42
+ "@brainervirus/workit-core": "^5.0.0"
43
43
  },
44
44
  "devDependencies": {
45
45
  "@opencode/plugin": "2.0.18"
@@ -1,37 +0,0 @@
1
- ---
2
- name: workit-babysit
3
- description: Use when the user asks to babysit a PR or explicitly opts in to PR follow-up
4
- ---
5
-
6
- # Babysit a PR to PR-ready
7
-
8
- PR creation does not start babysitting. `babysit:true` opts into this skill;
9
- omission means no follow-up. A PR URL by itself is not an instruction to drive
10
- it. When the user asks to babysit a URL from a route Workit did not enforce,
11
- help without claiming the Workit route was enforced. Never mutate PR topology
12
- (no rebase strategy changes, no force-push).
13
-
14
-
15
- ## Method
16
-
17
- 1. Default to drive mode for an explicit babysit request: resolve conflicts,
18
- address review threads, and get checks green. Watch reports status only;
19
- threads-only addresses review threads. Ask about mode only when the choice
20
- materially changes the work.
21
- 2. Work toward PR-ready in order: conflicts → review threads → CI. Keep a brief
22
- checkpoint when continuity needs it; task progress is optional.
23
- 3. Classify CI before retry: flake (rerun once) vs stale base (verify with
24
- `git merge-base --is-ancestor` before updating) vs real failure (fix).
25
- 4. Triage bot findings skeptically: reproduce or quote code before acting;
26
- invalid bots get a reasoned dismissal, never silent ignore.
27
- 5. Batch fixes into one push wave; re-verify green after every push.
28
- 6. Stop at PR-ready. A PR creation or babysit request does not authorize merge
29
- or release. Continue to merge or release only when the user explicitly sets
30
- that delivery endpoint and host authority allows the action.
31
-
32
- ## Completion
33
-
34
- Report PR-ready status with evidence for fixes, or a brief blocker report. If
35
- the user explicitly authorized merge, honor the configured strategy only after
36
- checks and required approval. After a squash merge, re-record evidence against
37
- the new base commit before closing tracked work.
@@ -1,56 +0,0 @@
1
- ---
2
- name: workit-behavioral-tdd
3
- description: Use when policy identifies behavior, side effects, permissions, or data handling that may change and a regression boundary is needed
4
- ---
5
-
6
- # Behavioral TDD
7
-
8
- Test the observable behavior at a stable boundary, not the implementation shape.
9
- Use this method when assessment selects the `testing` dimension.
10
-
11
-
12
- ## Method
13
-
14
- 1. Inspect the task requirement, current candidate, intended behavior, and real
15
- verification entry point with shared `task`, `policy`, and `evidence` operations.
16
- 2. State one behavior and its observable result. Choose the narrowest stable
17
- boundary a caller or user depends on; avoid private helpers and incidental
18
- representations.
19
- 3. Write one vertical RED slice that fails for the missing behavior and run it
20
- through the CLI so the failure is observed: `workit check test` (the repo's
21
- configured `test` check; `npx -y @brainervirus/workit-cli check test` when
22
- `workit` is not on PATH). Implement the smallest change, then run the same
23
- check GREEN. Close accepts only a fresh passing run of the configured check
24
- that `workit check` observed; a recorded "tests pass" is a note, and an
25
- ad-hoc `workit check -- <cmd>` never satisfies the gate. If no `test` check
26
- is configured or detected, add `workit.checks.json` (committed) with it.
27
- 4. Add only another slice for a distinct behavior or risk. Any edit makes the
28
- observed check stale: re-run `workit check test` before closing.
29
-
30
- ## Reject noisy tests
31
-
32
- - A dependency/version-pin assertion is not behavioral evidence.
33
- - A test that mirrors branches, private calls, or exact implementation structure
34
- is coupled to internals; replace it with the public effect.
35
- - Duplicate assertions and tests that add no distinct failure signal are noise;
36
- delete them.
37
- - Do not claim a passing test satisfies a different requirement.
38
- - Banned: tautologies (asserts what the code says, not what it must do),
39
- ghost loops (assert inside a possibly-empty loop), smoke-only renders,
40
- type-only or CSS-class coupling. If the test still passes when every
41
- imported function returns undefined, rewrite the assertion or delete it.
42
- `workit test-audit --diff` flags these; triage them with workit-test-audit.
43
- Turning acceptance criteria into scenarios and seams is workit-bdd.
44
-
45
- Run RED/GREEN through `workit check`, which records the observed result on the
46
- current task; shared `evidence` operations are for notes and non-test evidence.
47
- Do not add a second lifecycle, approval chain, or test workflow outside the
48
- current task state.
49
-
50
- ## Common mistakes
51
-
52
- | Mistake | Correction |
53
- | --- | --- |
54
- | "The pin changed, so assert the new string" | Exercise the affected consumer behavior. |
55
- | "The code is obvious" | A small vertical slice still proves the contract. |
56
- | Keeping a passing test after the boundary moved | Re-run `workit check test` on the current tree. |
@@ -1,26 +0,0 @@
1
- ---
2
- name: workit-blast-radius
3
- description: Use when a small-looking change could break something else, before close or merge
4
- ---
5
-
6
- # Blast radius beyond the diff
7
-
8
- A small diff is not a small risk. Prove the one fact it is safe because of,
9
- with runnable proof — not assertion.
10
-
11
-
12
- ## Method
13
-
14
- 1. List what the change touches: callers, shared state, contracts, config,
15
- migrations. Grep every caller of each touched function.
16
- 2. For each: state the one fact it is safe because of (type boundary,
17
- existing test, unreachable path) plus how to run the proof.
18
- 3. Run the proofs. Unproven claims stay labeled UNPROVEN in findings —
19
- never silently treated as safe.
20
- 4. Fix at the shared root (one guard where all callers route through),
21
- not per caller.
22
-
23
- ## Completion
24
-
25
- Blast-radius note in evidence or review: each risk with fact + proof
26
- command, or an UNPROVEN finding for what could not be proven.
@@ -1,47 +0,0 @@
1
- ---
2
- name: workit-challenge
3
- description: Use when requirements or consequences leave a real decision open
4
- ---
5
-
6
- # Challenge open choices with evidence
7
-
8
- Skip this method for a precise, settled request.
9
-
10
- ## Method
11
-
12
- 1. Ground the outcome, constraints, evidence, and important unknowns. Inspect
13
- code and project docs before asking about facts they can answer.
14
- 2. Separate observations, inferences, and proposals. Test assumptions that
15
- could change the recommendation.
16
- 3. When viable alternatives exist, present two or three genuinely different
17
- approaches. Recommend one; for each, give its benefit, cost or risk, when it
18
- fits, and the smallest useful validation. Do not invent a weak alternative.
19
- 4. Ask only consequential questions, in dependency order. Group independent
20
- choices into one small round. If an authorized reversible default works,
21
- state it and proceed.
22
- 5. Record a settled choice once in the existing conversation or task context.
23
- A discussion decision is knowledge; never fabricate a native permission
24
- receipt or reopen it without new evidence.
25
- 6. Create durable documentation only when requested or when the decision needs
26
- a future reader. Brainstorming alone does not require a spec.
27
-
28
- Say directly when evidence shows a proposal is weak, overcomplicated, or solves
29
- the wrong problem. Raise a counter-case only when it adds a real constraint.
30
-
31
- ## Guardrails
32
-
33
- - Do not create a universal spec, plan, approval chain, or second lifecycle.
34
- - Unknowns that affect an action remain unresolved until evidence or a user
35
- decision closes them.
36
- - Use shared operations for tracked state and provenance; never write task
37
- metadata directly.
38
- - An in-session counter-case is not fresh-context review.
39
-
40
- ## Common mistakes
41
-
42
- | Mistake | Correction |
43
- | --- | --- |
44
- | Asking what code or docs already answer | Ground first; the user owns choices, not lookups. |
45
- | Listing every hypothetical objection | Raise only objections that can change the decision. |
46
- | Asking for agreement without a recommendation | Recommend an option and explain the tradeoff. |
47
- | Treating a discussion decision as permission | Record it as knowledge; preserve native host authority. |
@@ -1,27 +0,0 @@
1
- ---
2
- name: workit-diagram
3
- description: Use when a spec or plan needs a flow or architecture diagram
4
- ---
5
-
6
- # Mermaid when needed, never by default
7
-
8
- Tables first, ASCII trees second, mermaid only when a flow or architecture
9
- needs it. Flowchart, sequence, state, or ER only. No renderer, no network.
10
-
11
-
12
- ## Syntax rules (mermaid v11)
13
-
14
- - Fence as ` ```mermaid `, no surrounding prose inside the fence.
15
- - Quote node labels containing punctuation: `A["input (x, y)"]`.
16
- - One direction per diagram (`TD` or `LR`); keep nodes under twelve.
17
- - Name actors exactly as the codebase names them (real symbols only).
18
-
19
- ## Verify
20
-
21
- Re-read the fence before commit: balanced quotes/brackets, every node
22
- reachable, labels match spec terms. If it cannot be verified by reading,
23
- delete it.
24
-
25
- ## Completion
26
-
27
- One diagram that argues a decision, or nothing. Never a diagram suite.
@@ -1,24 +0,0 @@
1
- ---
2
- name: workit-green-run
3
- description: Use to drive a red CI pipeline back to green, usually inside babysit
4
- ---
5
-
6
- # The CI loop
7
-
8
- Watch, classify, fix, push once, re-verify. Host-native (`gh` / GitLab);
9
- never invent CI APIs.
10
-
11
-
12
- ## Method
13
-
14
- 1. Read the failing checks, not the summary. Quote the failing log lines.
15
- 2. Classify each: flake (rerun once, note it) / stale base (update after
16
- merge-base check) / real failure (reproduce locally, then fix).
17
- 3. Fix at root cause with a regression test; push one wave.
18
- 4. Re-verify the same checks green on the new head. A fix without a
19
- green re-run is not a fix.
20
-
21
- ## Completion
22
-
23
- Green pipeline on the merge head, or an escalated finding with the exact
24
- failing logs when the fix needs the human.
@@ -1,37 +0,0 @@
1
- ---
2
- name: workit-handoff
3
- description: Use when work must continue in another session, host, or agent after interruption, transfer, or compaction
4
- ---
5
-
6
- # Handoff durable task state
7
-
8
- Transfer continuity, not live authority. Use this method when a tracked item
9
- must continue in another session, host, or agent.
10
-
11
- ## Method
12
-
13
- 1. Inspect the current task, scope, decisions, policy requirements, candidate,
14
- evidence, findings, progress, and worker states with shared `task` and `state`
15
- operations.
16
- 2. Export the compact state through `state.export`. Preserve the objective,
17
- exclusions, accepted decisions and reasons, evidence references, open gaps,
18
- findings, candidate identity, blockers, and next action. Do not include
19
- credentials, live writer ownership, or host authority.
20
- 3. Import only through the destination `state.import` operation and its expected
21
- workspace revision. The destination starts paused or otherwise unauthorised
22
- until it observes its own host/session and reconciles stale evidence and
23
- uncertain workers.
24
- 4. Resume or continue through shared `task`, `policy`, `worker`, `writer`, and
25
- `evidence` operations. Record what changed instead of copying a transcript.
26
-
27
- A handoff does not require a formal spec or plan unless those are separate
28
- selected requirements. Never grant destination authority from imported prose,
29
- create a second lifecycle, or edit task metadata directly.
30
-
31
- ## Common mistakes
32
-
33
- | Mistake | Correction |
34
- | --- | --- |
35
- | Sending the whole transcript | Export compact decisions, gaps, evidence, and next action. |
36
- | Restoring the old writer or credentials | Re-observe authority in the destination. |
37
- | Calling a handoff complete without reconciliation | Recheck stale files and uncertain workers first. |
@@ -1,23 +0,0 @@
1
- ---
2
- name: workit-mockup
3
- description: Use when a UI decision needs sketching before implementation
4
- ---
5
-
6
- # ASCII mockups before UI code
7
-
8
- Sketch, don't build. Three genuinely different layout hypotheses maximum,
9
- ASCII only, no code output.
10
-
11
-
12
- ## Method
13
-
14
- 1. Fix a legend (`┌─┐ │ └─┘ ░ ≈ [ ] ( )`) and keep sketches 60-80 cols,
15
- 8-20 rows.
16
- 2. Per hypothesis: regions, component reuse vs new (named against the
17
- existing codebase), empty/loading/populated/error states, nav flow.
18
- 3. Ask at most one clarifying question, then recommend. Flag hi-fi
19
- escalation when ASCII cannot settle it (density, motion, brand).
20
-
21
- ## Completion
22
-
23
- The sketch plus the decision lands in the spec dir. Throwaway by design.
@@ -1,45 +0,0 @@
1
- ---
2
- name: workit-plan
3
- description: Use when dependencies, sequencing, coordination, or resumption make durable next actions useful
4
- ---
5
-
6
- # Plan useful coordination
7
-
8
- A plan is useful when work has dependent steps, a handoff, concurrent actors, or
9
- meaningful unresolved choices. It is never a prerequisite for implementation.
10
-
11
- ## Method
12
-
13
- 1. Establish the requested outcome, constraints, dependencies, and important
14
- unknowns from the available code, docs, and configuration before asking.
15
- 2. Record only the useful sequence: objective, dependency, bounded outcome,
16
- evidence needed, and next action. Reuse the project's existing format.
17
- 3. Start a tracked record only when handoff, dependent steps, coordination, or
18
- durable decisions need continuity. Infer observable facts instead of asking
19
- the user to fill redundant protocol fields.
20
- 4. Create a spec when a durable behavior contract or interface is requested or
21
- will help a future reader. Use an ADR for a consequential trade-off and a
22
- glossary for stable terms. A small fix needs no document.
23
- 5. If the user authorized implementation, proceed through the agreed endpoint
24
- and applicable checks. Do not ask for a separate plan approval or repeat
25
- "continue?". Stop for a new consequential choice, host denial, conflict, or
26
- blocker that cannot be resolved safely.
27
- 6. Update a checkpoint at meaningful boundaries when another session may need
28
- to resume. Keep settled decisions, changed files, actual checks, blockers,
29
- and the next action; omit transcript and process trivia.
30
-
31
- ## Shape
32
-
33
- Plan slices as small end-to-end outcomes with explicit dependencies and checks.
34
- Keep repo policy and native host authority separate. Preserve the user's branch
35
- and commit conventions. Do not prescribe one commit per step or create a second
36
- approval chain unless the user asked for that delivery format.
37
-
38
- ## Common mistakes
39
-
40
- | Mistake | Correction |
41
- | --- | --- |
42
- | Writing a packet for a bounded reversible change | Leave the change undocumented. |
43
- | Asking what repository state or code can answer | Inspect it first. |
44
- | Treating the plan as authority | Follow the user's scope and native host permissions. |
45
- | Copying a transcript into the plan | Keep decisions, evidence, gaps, and next action only. |