@brainervirus/workit-codex 7.5.2 → 7.6.0

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "workit",
-  "version": "7.5.2",
+  "version": "7.6.0",
   "description": "Adaptive engineering workflow rails for Codex",
   "author": {
     "name": "BrainerVirus"

package/dist/workit-hook.js

@@ -133,6 +133,7 @@ Skills: load the skill, never act from memory of it (slash aliases /wk-<name>).
 - fan out, parallelize, parallel agents, swarm: workit-fanout
 - verify the app, smoke test, prove it works: workit-verify-app
 - retro (user-invoked; offer it): workit-retro
+- architecture, deepen modules (user-invoked; offer it): workit-architecture
 `.trim();
 
 // packages/workit-core/src/core/task-contract.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brainervirus/workit-codex",
-  "version": "7.5.2",
+  "version": "7.6.0",
   "private": false,
   "description": "Workit Codex CLI/desktop plugin — shared MCP transport, hooks, and sixteen method skills",
   "keywords": [
@@ -38,8 +38,8 @@
     "build": "bun scripts/build.ts"
   },
   "dependencies": {
-    "@brainervirus/workit-core": "^7.5.2",
-    "@brainervirus/workit-mcp": "^7.5.2"
+    "@brainervirus/workit-core": "^7.6.0",
+    "@brainervirus/workit-mcp": "^7.6.0"
   },
   "engines": {
     "node": ">=24"

package/skills/workit-architecture/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: workit-architecture
+description: Rank cited deepening refactors from churn and ledger friction; never applied unapproved. Use for architecture.
+disable-model-invocation: true
+---
+
+# Architecture: deepen the modules that cause friction
+
+User-invoked: offer it, never start it yourself. It proposes and grills; it
+never refactors without the user's approval. Use the words in
+`references/vocabulary.md` exactly and the domain words in `GLOSSARY.md`.
+
+## Deepening
+
+1. **Scope by YAGNI.** A direction the user names wins. Otherwise find hot
+   spots: churn (`git log --since=6.months --name-only --format=`, counted per
+   file, skipping lockfiles, version-bump manifests, generated files, docs and
+   `chore(release)` commits), friction in `workit ledger list --last 200`
+   (failed checks and verdicts, rulings, `retro:` decisions) and
+   `workit test-audit <paths> --json`. State the window and paths in one line.
+2. **Settled decisions stand.** Read `GLOSSARY.md`, `CODING_STANDARDS.md` and
+   ADRs when present. Never re-litigate an ADR without new evidence.
+3. **Explore organically.** A read-only explorer (Claude Code: Explore; or
+   you) walks the hot spots under the limits in `references/vocabulary.md`
+   and returns cited friction. Run the deletion test on every suspect.
+4. **Report 3-5 ranked candidates, then stop and wait for approval.** Each:
+   - files and modules;
+   - the friction, with **2 or more cited occurrences** (commit, ledger row,
+     PR, test-audit finding); a one-off is not a candidate;
+   - an interface sketch: what callers see, what moves behind the seam;
+   - what gets simpler and what becomes testable through that interface;
+   - **merge danger**: one-way or two-way door, plus blast radius (callers,
+     packages, public surface).
+   The text list is primary; offer an HTML report only if the host renders one.
+5. **Grill the chosen one**: numbered questions, each with a recommended
+   answer; challenge a weak premise with evidence first. Settle the interface,
+   the seam, the tests to replace and the migration order; a module named for
+   a new concept gets its glossary entry (read the `workit-shape` skill's SKILL.md and follow it).
+6. **Hand off on approval.** Several slices go into a plan for
+   `workit fanout plan <plan.json>`, with scopes and dependencies
+   (read the `workit-fanout` skill's SKILL.md and follow it). One slice goes to a build (read the `workit-implement` skill's SKILL.md and follow it). Record the
+   choice with `workit ledger decision "architecture: <id>" --why "<why>"`;
+   offer an ADR for a lasting rejection so the next run does not repeat it.
+
+## Instruction files
+
+Restructure AGENTS.md or CLAUDE.md in three escalating passes, **each its own
+commit in one PR**, so the user can drop the later ones: remove no-ops;
+progressive disclosure into topic files; coding rules to `CODING_STANDARDS.md`
+and mechanical rules to checks. No commit adds a `workit knowledge lint`
+finding. Never scaffold an empty file (`references/instruction-files.md`).
+
+## Test sweep
+
+Run `workit test-audit <paths> --json` over the suite or one hot spot and
+report findings by module, worst first. On approval, the bad tests are
+replaced (read the `workit-test-audit` skill's SKILL.md and follow it).
+
+## Example
+
+Bad: "The CLI is messy, so I split router.ts in five." Uncited, unapproved.
+
+Good: "1. Check runner (check.ts, evidence.ts), 3 occurrences: commits a1b2c3
+and d4e5f6 edit both for one fix; ledger row 41 is a `check` red on a hidden
+timeout. Sketch: `runCheck(spec)` returns evidence, the timeout behind it, so
+timeouts test without a shell. Two-way door, 2 callers in one package."
+
+## Check
+
+```sh
+workit knowledge lint   # no new finding after each instruction-files commit
+```

package/skills/workit-architecture/agents/openai.yaml

@@ -0,0 +1,3 @@
+# Codex: user-invoked only (the counterpart of disable-model-invocation).
+policy:
+  allow_implicit_invocation: false

package/skills/workit-architecture/references/instruction-files.md

@@ -0,0 +1,52 @@
+# Instruction-files mode (AGENTS.md, CLAUDE.md)
+
+Instruction files are paid for in every session that reads them. Restructure
+them in three escalating passes. Each pass is its own commit in one PR, in
+this order, so the user can keep pass 1 and drop pass 3. Run
+`workit knowledge lint` before pass 1 and after every commit: no commit adds
+a finding, and the lint exits 0 after the last pass, or the report lists the
+findings that remain and why.
+
+After each commit, run `workit check test`. A sentence a test pins stays,
+unless the user approves changing that test. Commit each pass with
+`workit git commit -m "<type>: <pass>" -- <paths>`, then open the PR
+(read the `workit-ship` skill's SKILL.md and follow it).
+
+Before pass 1, report the current byte counts and the plan for each pass, then
+wait for approval. A pass with nothing to do is skipped and said so, not
+padded.
+
+## Pass 1: remove no-ops
+
+Delete lines that would change no behavior if removed: "be thorough", "write
+clean code", "follow best practices", restated defaults of the host, notes
+about one past session, `path:line` references, and rules whose mistake a type,
+lint or check now prevents. Nothing moves in this pass; it only deletes.
+
+## Pass 2: progressive disclosure
+
+Keep the root file to what every session needs: commands, workflow, and
+"Read before <task>: <file>" pointers. Move topic detail (testing, release,
+hosts, architecture) into topic files under an existing docs folder, one file
+per topic, each opened by when to read it. Move text verbatim first; rewording
+belongs in pass 1 or a later change. Every pointer from AGENTS.md or
+CLAUDE.md must resolve (the lint's `broken-link` rule). The lint does not read
+topic files: check their own links and content by hand.
+
+## Pass 3: standards and checks
+
+- A judgment rule a reviewer must weigh goes to `CODING_STANDARDS.md`; the
+  root file keeps one pointer to it.
+- A mechanical rule (a forbidden import, a naming pattern, a file that must
+  exist) becomes a check instead of prose: a lint rule, a test, or a
+  configured `workit check <name>`. Show the check failing on a planted
+  violation, then delete the sentence.
+- No rule lives in two files (`duplicate-rule`).
+
+## Never
+
+- Create a file without its first real entry in the same commit. The lint
+  flags a scaffolded `CODING_STANDARDS.md` or `GLOSSARY.md` (`scaffold-file`);
+  for a topic file, that check is yours.
+- Squash the passes into one commit, or mix a behavior change into them.
+- Grow the root file past the lint's byte budget (`agents-budget`).

package/skills/workit-architecture/references/vocabulary.md

@@ -0,0 +1,53 @@
+# Deepening vocabulary
+
+Use these words exactly in every candidate. Do not drift into "component",
+"service", "API" or "boundary".
+
+| Term | Meaning |
+| --- | --- |
+| Module | Anything with an interface and an implementation: a function, a file, a package, a slice across tiers |
+| Interface | Everything a caller must know: types, invariants, ordering, error modes, configuration, cost |
+| Depth | Behavior a caller or test reaches per unit of interface learned. Deep: much behind little. Shallow: the interface is nearly as complex as the implementation |
+| Seam | Where behavior can change without editing that place; where an interface lives |
+| Adapter | A concrete thing that fills a seam (production, in-memory, fake) |
+| Leverage | What callers gain from depth: one implementation pays back across many call sites and tests |
+| Locality | What maintainers gain: change, bugs and verification concentrate in one place |
+
+## Tests to run on a suspect
+
+- **Deletion test.** Imagine deleting the module. Complexity vanishes: it was
+  a pass-through, so inline it. Complexity reappears across callers: it earns
+  its keep. A deepening concentrates complexity; it does not just move it.
+- **Interface is the test surface.** Tests that must reach past the interface
+  mean the module has the wrong shape.
+- **One adapter is a hypothetical seam; two are a real one.** Do not add a
+  port unless something varies across it (production and test count).
+
+## What the explorer looks for
+
+- One concept that needs a hop through many small modules to understand.
+- Shallow modules: wide interface, thin implementation.
+- Pure helpers extracted only for tests while the bugs live in how they are
+  called (no locality).
+- Coupled modules leaking through their seams: one fix edits both (churn shows
+  them changing together).
+- Code that is untested, or hard to test through its current interface.
+
+The explorer is read-only (on Claude Code, the Explore agent). It reads code,
+git history, `workit ledger list` and `workit test-audit` output only: never
+session transcripts and never another workspace. It copies no secret, token
+or personal data into its findings. It returns only cited findings (file,
+commit, ledger row), never a refactor.
+
+## Dependency categories (how the deeper module is tested)
+
+1. In-process (pure, in-memory): merge and test through the new interface.
+2. Local stand-in exists (temp dir, in-memory store): test with the stand-in;
+   the seam stays internal.
+3. Owned but remote (your own service): a port at the seam, an in-memory
+   adapter in tests.
+4. Third party: an injected port, a fake adapter in tests.
+
+Replace, do not layer. An old test on a shallow module is deleted only after
+naming the break it catches and showing that a test at the deeper interface
+fails on that planted break (read the `workit-test-audit` skill's SKILL.md and follow it). Until then it stays.