@brainervirus/workit-claude-code 2.6.0

package/.claude-plugin/plugin.json

@@ -0,0 +1,19 @@
+{
+  "name": "workit",
+  "displayName": "Workit",
+  "version": "2.6.0",
+  "description": "Workflow rails for agentic coding: task context on every session, branch policy on shell commands, and the workit method skills",
+  "author": {
+    "name": "BrainerVirus"
+  },
+  "homepage": "https://github.com/BrainerVirus/workit#readme",
+  "repository": "https://github.com/BrainerVirus/workit",
+  "license": "MIT",
+  "keywords": [
+    "agentic-coding",
+    "branch-policy",
+    "skills",
+    "task-management",
+    "workflow"
+  ]
+}

package/README.md

@@ -0,0 +1,46 @@
+# @brainervirus/workit-claude-code
+
+[![CI](https://github.com/BrainerVirus/workit/actions/workflows/ci.yml/badge.svg)](https://github.com/BrainerVirus/workit/actions/workflows/ci.yml)
+[![license: MIT](https://img.shields.io/badge/license-MIT-green.svg)](../../LICENSE)
+
+Workit plugin for Claude Code: task context on session start and per turn,
+branch policy on `git` shell commands, fourteen method skills (`/workit:<name>`),
+and `verifier`, `reviewer` and `implementer` agents.
+
+## Install
+
+Latest published (the repository root is the marketplace; its entry installs
+this npm package):
+
+```bash
+claude plugin marketplace add BrainerVirus/workit
+claude plugin install workit@workit
+claude plugin marketplace update workit && claude plugin update workit@workit   # update
+```
+
+Local pin to a checkout (hooks and `bin/workit` run the sources with Bun):
+
+```bash
+bun install
+bun packages/workit-claude-code/scripts/build.ts --skills-only
+claude --plugin-dir "$PWD/packages/workit-claude-code"
+# or, for every session:
+export CLAUDE_CODE_PLUGIN_DIRS="$HOME/path/to/workit/packages/workit-claude-code"
+```
+
+`WORKIT_CLAUDE_RUNTIME=source|dist` forces one runtime;
+`WORKIT_SHIM_TRACE=1 workit …` prints which `workit` entry ran.
+
+## Layout
+
+| Path | Purpose |
+| --- | --- |
+| `.claude-plugin/plugin.json` | Manifest (version synced at release) |
+| `hooks/hooks.json` | SessionStart (startup/resume/clear/compact/fork), UserPromptSubmit, PreToolUse (Bash/PowerShell `git *`), SubagentStart |
+| `bin/workit-hook.mjs` | Hook launcher: source with Bun in a checkout, `dist/workit-hook.js` when installed; fails open (`{}` + one stderr line) when neither can run |
+| `bin/workit` | `workit` on the Bash tool's PATH (same source/dist switch) |
+| `agents/` | `verifier`, `reviewer` (read-only), `implementer` (`isolation: worktree`) |
+| `skills/` | Generated by `scripts/build.ts` from `packages/workit-core/skills` (not committed) |
+| `evals/` | Opt-in `claude plugin eval` suite (nightly / `eval` label, not a PR gate) |
+
+Requires Node.js 24+ (installed plugin) or Bun (local pin).

package/agents/implementer.md

@@ -0,0 +1,26 @@
+---
+name: implementer
+description: Implements one scoped workit brief in an isolated git worktree and reports what changed and how it was verified. Use to delegate a well-defined slice (goal, scope, acceptance, verify, forbidden, report) so it can run in parallel with other work.
+isolation: worktree
+---
+
+You are a workit implementer working in your own git worktree.
+
+Refuse to start without a complete brief. It must state: goal, scope (files
+or areas you may touch), acceptance (observable outcomes), verify (exact
+commands), forbidden (what you must not touch or do), and report (what to
+hand back). If anything is missing, report which field is missing and stop.
+
+1. Your worktree starts on a branch name chosen by Claude Code, which may not
+   satisfy the repository's branch policy. Before any commit, create or switch
+   to a policy-compliant branch (`workit` CLI branch setup when available,
+   otherwise `git switch -c <type>/<slug>`). A hook denies protected or
+   non-compliant branch names; follow the unblock hint it prints.
+2. Stay inside the declared scope. Anything outside it goes in the report as
+   a follow-up, not into the diff.
+3. Make the change in small, reviewable commits with conventional messages.
+4. Run every verify command from the brief and keep the real exit codes.
+5. Report: branch and head SHA, files changed, each verify command with its
+   exit code, acceptance items met or not, and any deviation from the brief.
+
+Never push, open a PR, or merge unless the brief explicitly asks for it.

package/agents/reviewer.md

@@ -0,0 +1,23 @@
+---
+name: reviewer
+description: Fresh-context code reviewer for a workit candidate. Reads the real diff and checks for correctness, regressions, security, and scope creep, then records findings with a severity and a ruling. Use for independent review of a branch or PR.
+tools: Read, Grep, Glob, Bash
+disallowedTools: Write, Edit, NotebookEdit
+---
+
+You are the workit reviewer. Review the real candidate, not the author's
+description of it.
+
+1. Identify the candidate: `git rev-parse HEAD`, the base branch, and
+   `git diff <base>...HEAD`. For a PR, read its status and unresolved threads
+   with `gh`/`glab` (or `workit pr status` when the CLI offers it).
+2. Read the task brief: goal, scope, forbidden areas, acceptance.
+3. Examine the diff for correctness, regression risk, security or data
+   consequences, missing tests, and changes outside the declared scope.
+   Confirm claims by reading code and check output; never infer evidence.
+4. Report each finding as: file:line, severity (blocker / major / minor /
+   nit), what is wrong, and the concrete fix. End with a ruling: approve,
+   approve with nits, or request changes.
+
+Stay read-only: you may run read and test commands, never commits, pushes,
+merges, or edits.

package/agents/verifier.md

@@ -0,0 +1,26 @@
+---
+name: verifier
+description: Independently verifies a workit candidate (a branch, commit, or PR) by running its real checks and reporting a pass/fail verdict with evidence. Use after an implementer finishes and before a merge, never on work this session authored.
+tools: Read, Grep, Glob, Bash
+disallowedTools: Write, Edit, NotebookEdit
+---
+
+You are the workit verifier. You did not write the candidate, and you must not
+change it: you only observe and report.
+
+1. Pin the candidate first: `git rev-parse HEAD` and `git status --short`. A
+   dirty tree or a moving HEAD is itself a finding.
+2. Read the task brief (goal, scope, acceptance, verify commands). If the
+   repository has a `verify-<app>` script or skill, run it; otherwise run the
+   verify commands from the brief exactly as written. Never substitute an
+   easier command.
+3. Run each check through the workit CLI when it is available (`workit
+   --help` lists the verbs), so the result is CLI-observed rather than
+   claimed. Capture the exit code and the failing output tail.
+4. Check every acceptance item against observed behavior, not against the
+   author's summary.
+5. Report: candidate SHA, each check with its exit code, each acceptance item
+   as met / not met / not verifiable, and an overall verdict (pass or fail).
+   When the CLI offers a verdict verb, record the verdict with it.
+
+Do not fix anything you find. A failing check is a verdict, not a task.

package/assets/templates/execution-contract.md

@@ -0,0 +1,40 @@
+Load resolved method skills through the host skill loader when policy selects them. Implement the existing plan; do not re-plan.
+
+**Spec:** <SPEC_PATH>
+**Plan:** <PLAN_PATH>
+**Branch:** <BRANCH>
+
+## Hard gates
+
+- Inspect task state before acting. On OpenCode, Cursor, Codex, and Pi use the eight shared `workit_*` families (`workit_task`, `workit_policy`, `workit_evidence`, `workit_finding`, `workit_decision`, `workit_worker`, `workit_writer`, `workit_state`). On the CLI host use `workit <family> <action>` with the same actions (hyphenated on the CLI).
+- Never use a worktree. Branch changes are in-place through the approved `git.branch_setup` external action (CLI: `workit action git.branch_setup --payload …`).
+- Task metadata lives under `.workit/`; never edit it directly. Record progress, evidence, findings, decisions, and worker state only through the shared operations.
+- Helpers cannot widen scope, record binding decisions, close or pause the task, assign further helpers, or resolve blockers for the lead.
+- On Cursor, pass the active workspace as `workspace_root` on every repository-scoped call.
+
+## Setup
+
+1. If there is no active or paused task, call `workit_task` with `action: "start"` then `workit_policy` with `action: "assess"` (CLI: `workit task start …` then `workit policy assess …`).
+2. Load `workit-plan`, list tasks with `workit_task` `action: "list"`, and mirror visible todo state to the host UI.
+3. When policy requires a feature branch, resolve it with read-only `context.read` and apply `git.branch_setup` only after native approval.
+
+## Remaining-task loop
+
+For each bounded plan task:
+
+1. Mark the item in progress in the host todo UI and record boundary progress with `workit_task` `action: "progress"`.
+2. Route by policy: assign bounded workers with `workit_worker` `action: "assign"` when delegation is available; otherwise implement inline. Acquire product-write ownership with `workit_writer` `action: "acquire"` before repository mutations; release it when done.
+3. Record checks and artifacts with `workit_evidence` `action: "record"`. Record review concerns with `workit_finding` `action: "record"`; resolve or defer them with `finding.resolve`. Blocking findings may trigger at most **two** fix+re-review rounds per task; advisory taste/YAGNI items still use `finding.record` and never pause the loop by direct file edit.
+4. Never advance while a foreign writer is active or blocking findings remain open for the current candidate.
+
+## Final gate
+
+Run repository verification (CLI: `workit doctor`; hosts: approved project verify when policy requires it). **Mandatory:** close the lead task with `workit_task` `action: "close"` (CLI: `workit task close --payload … [--confirm]`) once requirements are satisfied and verification passes — never finish while the task is still `active` or `paused`.
+
+## Task order
+
+<TASK_LIST>
+
+## Quality gate
+
+- Specs/plans follow `templates/spec-template.md` / `templates/plan-template.md`.

package/assets/templates/headers.md

@@ -0,0 +1,3 @@
+## Adjunto capturas
+
+## Archivos adjuntos

package/assets/templates/hygiene/.editorconfig

@@ -0,0 +1,8 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+indent_style = space
+indent_size = 2

package/assets/templates/hygiene/.gitattributes

@@ -0,0 +1,3 @@
+* text=auto
+*.md text
+*.bat text eol=crlf

package/assets/templates/hygiene/CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+
+### Changed
+
+### Fixed

package/assets/templates/hygiene/CONTRIBUTING.md

@@ -0,0 +1,3 @@
+# Contributing
+
+<!-- How to report issues, propose changes, and the review process. -->

package/assets/templates/hygiene/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) <YEAR> <HOLDER>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/assets/templates/hygiene/README.md

@@ -0,0 +1,3 @@
+# <PROJECT>
+
+<!-- Describe the project: what it does, how to run it, how to contribute. -->

package/assets/templates/issue-update.md

@@ -0,0 +1,5 @@
+# Update
+{{projectSection}}
+{{userNotesSection}}
+{{progressSection}}
+{{gitCommitsSection}}

package/assets/templates/plan-template.md

@@ -0,0 +1,27 @@
+# <Feature> Implementation Plan
+
+> **For agentic workers:** Load `workit-implement` when policy selects implementation. Use bounded `workit_worker` delegation when the host supports it; otherwise execute inline within writer scope. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Spec:** `docs/<slug>/spec.md`
+**Branch:** `feature/<slug>`
+
+**Goal:** <one sentence>
+
+## Global Constraints
+
+- Each task lands exactly one contiguous non-empty commit range (`base..head`): fix rounds append commits to that range and never rewrite/amend an active review range; record the real base..head shas in task progress.
+- The final task closes the lead Workit task with `workit_task` `action: "close"` (CLI: `workit task close --payload … [--confirm]`) once requirements are satisfied and repository verification passes — never finish while the task is still `active` or `paused`.
+- <project-wide requirements, one line each>
+
+---
+
+### Task N: <Component>
+
+- [ ] **Step 1: <action>**
+
+<!-- per-task criteria: how this task is verified -->
+**Criteria:** <verifiable check>
+
+| Status | Task |
+| --- | --- |
+| pending | N: <Component> |

package/assets/templates/spec-template.md

@@ -0,0 +1,63 @@
+# Spec: <feature>
+
+**Branch:** `feature/<slug>`
+
+**Change:** ADDED|MODIFIED|REMOVED — <one-sentence intent>. (Small work with
+no durable agreement: `Spec: none (<reason>)`, no file.)
+
+## Context
+
+<!-- Why does this exist? What problem does it solve? 1-3 sentences. -->
+
+## Goals
+
+- <!-- measurable, one per bullet -->
+
+## Non-goals
+
+- <!-- explicitly out of scope -->
+
+## Architecture
+
+<!-- May be `N/A (<reason>)` when the change has no flows or architecture. -->
+<!-- Otherwise REQUIRED: render a mermaid diagram (workit-diagram skill). -->
+```mermaid
+flowchart TD
+  A[Start] --> B[Step]
+```
+
+<!-- REQUIRED if this spec touches UI: render an ASCII wireframe (workit-mockup skill). -->
+```text
+┌──────────────┐
+│ Header       │
+└──────────────┘
+```
+
+## Data flow / contracts
+
+<!-- REQUIRED when there is a glossary, scope comparison, or contracts: use markdown tables. -->
+| Term | Meaning |
+| --- | --- |
+| <term> | <meaning> |
+
+## Acceptance criteria
+
+<!-- REQUIRED: enumerable, each verifiable. Numbered CA-01, CA-02, ... -->
+<!-- Requirements use SHALL/MUST (one per bullet, observable, no HOW); each
+     carries at least one GIVEN/WHEN/THEN, including the most-regretted edge. -->
+- CA-01 …
+
+## Review checklist
+
+<!-- Before implementation: intent matches; nothing extra; each requirement
+     testable with an exercising scenario; most-cared case covered;
+     tasks trace to requirements; you would sign if built exactly as written. -->
+- [ ] …
+
+## Decisions
+
+- D-01 …
+
+## Future work
+
+- …

package/assets/templates/workit-contract.md

@@ -0,0 +1,12 @@
+# Workit contract
+
+Workit keeps one accountable lead and one shared task state. Inspect current
+task state before acting; use only the shared operations for task, policy,
+evidence, finding, decision, worker, writer, and state changes. Authority is
+bounded by the requested scope, current revision, caller/session provenance, and
+observed capabilities. Never claim host enforcement or evidence that the host
+cannot provide. Preserve unresolved requirements, gaps, and uncertain workers.
+
+Focused methods are loaded only when the resolved policy requires them. A method
+must call the shared operations and must not create a second lifecycle, approval
+chain, or task-state representation.

package/bin/workit

@@ -0,0 +1,24 @@
+#!/bin/sh
+# `workit` on the Claude Code Bash tool's PATH (Claude adds a plugin's bin/).
+# Local pin: run the CLI from the monorepo sources with bun. Installed
+# package: run the bundled dist/workit.js with node.
+# WORKIT_CLAUDE_RUNTIME=source|dist forces one; WORKIT_SHIM_TRACE=1 prints
+# the resolved entry on stderr.
+set -e
+here=$(dirname "$0")
+root=$(cd "$here/.." && pwd)
+main="$root/../workit-cli/src/main.ts"
+entry=""
+if [ "${WORKIT_CLAUDE_RUNTIME:-}" != "dist" ] && [ -f "$root/../workit-core/src/core.ts" ] && [ -f "$main" ]; then
+  entry="$main"
+fi
+if [ "${WORKIT_CLAUDE_RUNTIME:-}" = "source" ] && [ -z "$entry" ]; then
+  echo "workit: WORKIT_CLAUDE_RUNTIME=source but no monorepo CLI source next to $root" >&2
+  exit 1
+fi
+if [ -n "$entry" ]; then
+  [ "${WORKIT_SHIM_TRACE:-}" = "1" ] && echo "workit-shim: source $entry" >&2
+  exec bun "$entry" "$@"
+fi
+[ "${WORKIT_SHIM_TRACE:-}" = "1" ] && echo "workit-shim: dist $root/dist/workit.js" >&2
+exec node "$root/dist/workit.js" "$@"

package/bin/workit-hook.mjs

@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+// Claude Code hook launcher (hooks/hooks.json runs `node <this file>`, exec
+// form, so no shell is involved on any OS). Two layouts:
+//   - local pin (`claude --plugin-dir <checkout>/packages/workit-claude-code`):
+//     the monorepo sources sit next to this package, so the TypeScript entry
+//     runs from source with bun: edits apply without a rebuild;
+//   - installed package (npm/marketplace): dist/workit-hook.js is imported.
+// WORKIT_CLAUDE_RUNTIME=source|dist forces one.
+// Fail-open: when the runtime cannot start (no bun for the pin, a missing or
+// unloadable dist/), the launcher answers `{}` with exit 0 and one
+// `[workit] Claude Code hook unavailable: …` line on stderr. Claude then
+// proceeds as if no Workit hook were installed (no context, no branch
+// policy): a broken hook must never brick the host.
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const source = path.join(root, "src", "run.ts");
+const dist = path.join(root, "dist", "workit-hook.js");
+const mode = process.env.WORKIT_CLAUDE_RUNTIME;
+const fromSource =
+  mode === "source" ||
+  (mode !== "dist" &&
+    existsSync(source) &&
+    existsSync(path.join(root, "..", "workit-core", "src", "hooks", "index.ts")));
+
+const failOpen = (reason) => {
+  process.stderr.write(`[workit] Claude Code hook unavailable: ${reason}\n`);
+  process.stdout.write("{}\n");
+};
+
+if (fromSource) {
+  const run = spawnSync(process.env.WORKIT_BUN ?? "bun", [source], {
+    stdio: "inherit",
+    windowsHide: true,
+  });
+  if (run.error) failOpen(`bun is required for the local pin (${run.error.message})`);
+  else process.exitCode = run.status ?? 0;
+} else if (existsSync(dist)) {
+  let runClaudeHook;
+  try {
+    ({ runClaudeHook } = await import(pathToFileURL(dist).href));
+  } catch (error) {
+    failOpen(`cannot load ${dist} (${error instanceof Error ? error.message : String(error)})`);
+  }
+  if (runClaudeHook) process.exitCode = await runClaudeHook(process.stdin, process.stdout);
+} else {
+  failOpen(`${dist} is missing; run \`bun scripts/build.ts\` in ${root}`);
+}