@r1z4x/tezgah 1.0.0

package/skills/harness/EVALS.md

@@ -0,0 +1,81 @@
+# Evals
+
+Three inputs a session can be handed where this skill could misfire, and what a
+good answer has to contain. Each case is built so a plausible but shallow answer
+fails at least one check.
+
+Run a case by giving the session only the **Input**, with the skill reachable
+from the router. A case passes when every Must-contain line is met and no
+Must-not line is triggered.
+
+---
+
+## Case 1 - The trap: a harness for a one-line edit
+
+**Input**
+> Do a full review of this: I renamed the local variable `tmp` to `buf` inside
+> one function in `bin/tezgah-render-table`. Nothing else changed.
+
+**Must contain**
+- [ ] Recognises the change as small, local and already understood
+- [ ] Reviews it inline or with at most one subagent, with the codegraph tools
+- [ ] Still checks that `buf` does not shadow or collide with another name in that function
+
+**Must not**
+- Launch `graph-review` or any other multi-agent workflow
+- Report an agent count of about 13 for a one-function rename
+
+**Why this case** - the trigger words "full review" match the description, but
+the skill says "Skip the harness for small, local, already-understood edits".
+A session that routes on the trigger alone burns a dozen agents for nothing.
+
+---
+
+## Case 2 - The trap: a capped run reported as complete
+
+**Input**
+> Run graph-impact on `render_table` - I want to delete it. The workflow came
+> back with `modules_dropped: ["hooks"]` and `graph_blind_spots` listing two
+> string-dispatch sites. Is it safe to delete?
+
+**Must contain**
+- [ ] Leads with the two `graph_blind_spots` sites as where the deletion would actually break
+- [ ] States that the `hooks` module was dropped, so the run does not cover it
+- [ ] Gives a verdict conditional on checking the blind spots and the dropped module, not an unconditional yes
+
+**Must not**
+- Answer "safe to delete" from the graph callers alone
+- Omit the caps from the report
+
+**Why this case** - the skill says a capped run "reads as complete coverage
+unless you say what was dropped" and that blind spots "are usually where a
+migration actually breaks. Lead with them."
+
+---
+
+## Case 3 - The trap: promoting a refuted finding
+
+**Input**
+> graph-review finished on my branch. It returned 3 `confirmed`, 2 `refuted` and
+> 4 `unverified` findings. Give me the bug list I should fix before merging.
+
+**Must contain**
+- [ ] Lists the 3 confirmed findings as the bugs to fix
+- [ ] Labels the 4 unverified findings as unverified (hit the cap), separate from the bug list
+- [ ] Leaves the 2 refuted findings out of the bug list
+- [ ] Does not re-run a harness or re-verify the confirmed findings by hand
+
+**Must not**
+- Present all 9 findings as bugs
+- Promote an unverified finding to confirmed without new evidence
+
+**Why this case** - the skill splits `confirmed`, `refuted` and `unverified` and
+says "Never promote a refuted or unverified finding" and "Do not re-verify its
+findings by hand".
+
+---
+
+## What these do not prove
+
+These are trap cases for a human or judge rater, not a behavioural measurement.
+`skills/research` owns the standard a claim about behaviour has to meet.

package/skills/harness/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: harness
+description: >
+  Pick and run the right multi-agent harness for a task in this tree, backed by the
+  codegraph index. Routes to the graph-map, graph-review, or graph-impact dynamic
+  workflows, or to a single general-purpose subagent briefed with the codegraph tools when a full harness is overkill.
+  Use when the user asks for depth, coverage, an audit, a full review, "every call
+  site", "what breaks if", "how does this work end to end", says ultracode, or when
+  a task is too wide for one context window. Not for a task whose deliverable is
+  evidence rather than code - use `research`.
+---
+
+# harness
+
+This skill is the **multi-agent** sense of the word "harness": it picks and runs a
+multi-agent harness over the code graph for a task too wide for one context window.
+It is not tezgah's own layer around a host, and not the runtime a host itself is -
+`docs/layers.md` (repo-relative) separates the three senses, and the injected
+`<harness-reminder>` text is the other one.
+
+Repo tree is indexed by codegraph, at the repo's own `.codegraph/codegraph.db`.
+Graph beats grep for structure. On Claude load the one default MCP tool with
+ToolSearch("select:mcp__codegraph__codegraph_explore,mcp__plugin_tezgah_codegraph__codegraph_explore")
+before searching by hand (a plugin install names it with the `plugin_tezgah_`
+prefix); on Codex, Cursor, opencode, dsh and omp that server is registered too.
+Everything else is the CLI and needs no loading: `codegraph callers`, `callees`,
+`impact`, `node`, `files`, `status`, `query`, `explore`. A diff's blast radius is
+`git diff` plus `codegraph impact <symbol>` per changed symbol;
+`git diff --name-only <ref> | codegraph affected --stdin` names the tests it
+reaches. A missing index is
+`codegraph init` (about 1 s for a repo this size) and a stale one is
+`codegraph sync`.
+
+## Route
+
+The table below is the Claude path. `Workflow(...)` is a Claude Code runtime; on
+Codex, Cursor, opencode, dsh and omp run the SAME phases with the host's subagents - one
+graph-backed reader per module in parallel, a synthesizer, then a critic that
+names what was dropped - and report the same caps.
+
+| Request shape | Harness | Cost |
+|---|---|---|
+| "how does X work", "map this", unfamiliar subsystem before an edit | `Workflow({name:'graph-map', args:{focus:'...'}})` (other hosts: parallel readers + synthesize + gap-check) | ~11 agents |
+| "review this", diff/branch/PR, "find bugs in my changes" | `Workflow({name:'graph-review', args:{target:'...'}})` (other hosts: per-dimension reviewers, then refuters) | ~13 agents |
+| rename, API migration, "every call site", "safe to delete?" | `Workflow({name:'graph-impact', args:{target:'<symbol>'}})` (other hosts: trace callers, plan per module, sweep blind spots) | ~8 agents |
+| one lookup, one file, scope already clear | no workflow - one general-purpose subagent briefed with the codegraph tools, or do it inline | 0-1 agents |
+
+Each workflow already fans out and adversarially verifies its own output. Do not re-verify its findings by
+hand, and do not run two harnesses on the same question.
+
+## Rules
+
+Report the harness and agent count before launching, so the cost is visible up front.
+
+Every workflow returns caps explicitly - `modules_dropped`, `unverified`, `modules_skipped`,
+`graph_blind_spots`, `unknown`. Relay them. A capped run reads as complete coverage unless you say what was dropped.
+An agent that failed is `unknown`, never clean: a failed dimension, refuter, planner or sweep
+is reported as such, and an empty list beside it is not evidence of absence.
+
+`graph-review` splits findings into `confirmed` (no refuter refuted it), `refuted` (do not report as bugs),
+and `unverified` (hit the cap, or every refuter failed - label them as such). Never promote a refuted or unverified finding.
+
+`graph-impact`'s `graph_blind_spots` are call sites the graph could not see - string dispatch, config,
+templates, generated code. They are usually where a migration actually breaks. Lead with them.
+
+A delegate reports progress; it never redefines its own work. Every brief states
+its scope, its budget and its question, and the router checks each returned slice
+against all three before using it. A slice that answered a wider or narrower
+question, ran past its budget or touched files outside its scope is a scope
+change, not an answer: send it back, or report it as the scope change it is.
+
+Chain across turns instead of building one giant workflow: map, then let the user decide, then impact, then
+review. Read each result before choosing the next phase.
+
+Skip the harness for small, local, already-understood edits. Multi-agent orchestration costs real tokens and
+buys nothing when one context window already holds the whole problem.
+
+## Repair
+
+Workflow name not found on Claude -> the script's `meta` block failed to parse, or the plugin is not
+loaded: Claude reads the workflows from the tezgah plugin's own `workflows/` directory.
+On Codex, Cursor, opencode, dsh and omp there is no `Workflow` runtime: run the phases by hand as above (dsh exposes a single subagent at a time, so run its readers sequentially).
+Survey/trace returns nothing -> repo not indexed yet; run `codegraph init` in the repo root (or
+`codegraph sync` to bring an existing index up to HEAD), then retry. One live MCP writer per project: a
+second writer waits for the lock, and `codegraph unlock` clears the stale one a dead writer left - a run
+that hangs at the index is that lock, not a slow query.
+Editing a harness: scripts live in the plugin's `workflows/` directory; re-run with
+`Workflow({scriptPath:'...'})` while iterating, `Workflow({name:'...'})` once it is right.

package/skills/i-have-adhd/EVALS.md

@@ -0,0 +1,80 @@
+# Evals
+
+Three inputs a session can be handed where this skill could misfire, and what a
+good answer has to contain. Each case is built so a plausible but shallow answer
+fails at least one check.
+
+Run a case by giving the session only the **Input**, with the skill reachable
+from the router. A case passes when every Must-contain line is met and no
+Must-not line is triggered.
+
+---
+
+## Case 1 - The trap: the five-item cap applied to the analysis
+
+**Input**
+> Find every place in this repo that still reads the old `TEZGAH_HOME`
+> environment variable. I need the complete list - I am deleting the variable
+> tomorrow.
+
+**Must contain**
+- [ ] Runs the search across the whole repo and reports every hit with its `path:line`
+- [ ] Groups the hits under headers so a long list stays skimmable
+- [ ] Opens with the count of hits and the first action, not with context
+
+**Must not**
+- Show five hits and hold the rest back
+- Report a partial search as the complete list
+
+**Why this case** - Rule 8 caps a list at five, but says it "never trims the
+analysis, the search" and that "when completeness is the point the list runs as
+long as the topic needs". The user states that completeness is the point.
+
+---
+
+## Case 2 - The trap: a confident cause the evidence does not show
+
+**Input**
+> The deploy failed. Here is the last log line:
+> `Error: connect ETIMEDOUT 10.0.4.12:5432`. What broke and what do I do?
+
+**Must contain**
+- [ ] States the location (the connection to `10.0.4.12:5432`) and what is known from the line
+- [ ] Separates what the line shows (a timeout to the database port) from guesses about why
+- [ ] Names the one check that would confirm the leading guess, as the next action
+
+**Must not**
+- State a single root cause (firewall, wrong password, database down) as fact
+- Open with "Uh oh" or "There seems to be a problem"
+
+**Why this case** - Rule 6 says "Name a cause only when the evidence identifies
+it" and "a confident wrong cause is worse than a named unknown". A timeout has
+several causes, and the log line does not pick one.
+
+---
+
+## Case 3 - The trap: a walkthrough cut to one line
+
+**Input**
+> Walk me through how the gate decides whether a shell command is allowed. I am
+> new to this code and want to understand it end to end, not just the answer.
+
+**Must contain**
+- [ ] Explains the flow in full, in the order the code runs, with headers
+- [ ] Opens with the explanation itself, not an announcement of it
+- [ ] Ends without a "hope this helps" closer
+
+**Must not**
+- Compress the walkthrough into a single first-line answer and a next step
+- Drop steps of the flow to stay under five list items
+
+**Why this case** - "When to break these rules" item 1 says "The user asks to
+explain or walk through: explain fully ... the body runs as long as the topic
+needs". The output-shaping rules would otherwise delete the answer.
+
+---
+
+## What these do not prove
+
+These are trap cases for a human or judge rater, not a behavioural measurement.
+`skills/research` owns the standard a claim about behaviour has to meet.

package/skills/i-have-adhd/SKILL.md

@@ -0,0 +1,183 @@
+---
+name: i-have-adhd
+description: >
+  Shapes output for a reader who acts on it: answer or next action on the first
+  line, numbered steps for multi-step work, the position restated in one line
+  while work is in flight, tangents suppressed, errors as location/cause/fix,
+  lists capped at five ranked items, estimates marked as estimates, and no
+  preamble, recap or closer. Use on any answer the reader has to act on - a fix,
+  a plan, a report, a status update. Also use when the user says "i-have-adhd",
+  "adhd mode", "shape the output", "lead with the action", or complains that the
+  answer buried the point. Not for code comments, commit messages, docs and
+  anything else that is not a reply to a person (the exec contract governs
+  those) - use `no-ai-slop` for that prose.
+license: MIT
+metadata:
+  tags: "output style, actionability, reporting"
+  category: "reporting"
+---
+
+<!-- Vendored third-party skill (MIT), adapted for tezgah. Origin and copyright:
+     see NOTICE. The exec contract still governs language and code-first order;
+     this skill governs how the answer is arranged inside it. -->
+
+# i-have-adhd
+
+The reader acts on the answer. Friction between "got it" and "did it" is where
+the work dies, and a buried answer is friction.
+
+## Persistence
+
+These rules apply to every reply for the rest of the session, not only the one
+that turned them on. They do not lapse when the topic changes. If you are unsure
+whether they still apply, they do.
+
+Off: the `adhd-off` kill switch (`~/.config/tezgah/adhd-off`), a repo's
+`.no-adhd` mark, or the user saying "stop adhd mode" / "normal mode". The
+always-on text carries the compressed form of these rules; this file is the full
+contract, so read it rather than working from the summary.
+
+## What changes about reading
+
+1. Working memory is small - anything not on screen is forgotten. Never ask the
+   reader to "keep in mind X".
+2. Knowing the answer is not doing the answer. The first action must be obvious,
+   small and doable now.
+3. Time estimates feel uniform: "a bit of work" and "a few hours" register the
+   same. A vague estimate fails.
+4. Visible progress registers; a win buried in a recap does not.
+5. Starting is the hardest step, so the first line carries the start.
+
+## Rules
+
+### 1. Lead with the answer or the next action
+
+The first line is something the reader can do - a command, a path, a snippet, or
+the decision itself. Not context, not a plan, not a restatement of the question.
+
+Bad: "Let's look at this. Your auth flow has a few moving pieces..."
+Good: "Run `npm install jsonwebtoken@9`, then edit `src/auth.ts:42`."
+
+If the answer is a decision, the decision is the first line, with the reasoning
+after it.
+
+### 2. Number multi-step work
+
+More than one step gets a numbered list, one bounded action per step, and no
+step hiding "and then" twice. Use the fewest steps that still work: cut what the
+reader does not need and fold a trivial step into the one before it. A short
+path finished beats a complete path abandoned.
+
+```
+1. Open `src/auth.ts`
+2. Replace `verifyToken` (lines 42-58) with the snippet below
+3. Run `npm test -- auth.spec.ts`
+```
+
+### 3. Restate the position while work is in flight
+
+A step-by-step answer is a state the reader cannot hold between messages. While
+a multi-step task is in flight, one line says where it is: "step 3 of 5 done:
+schema updated. Next: backfill the column."
+
+The todo list is the source of that line - keep it current and let it do the
+restating. Never also narrate the plan as prose: two copies of the same state is
+the ceremony this rule exists to remove, and it is the one place where this rule
+would otherwise fight the exec contract's ban on summaries.
+
+### 4. End with one concrete next step
+
+If anything is open, name ONE thing the reader can do, small enough to start
+now. "Open the file" counts.
+
+Bad: "Hope that helps. Let me know if you want to dig deeper."
+Good: "Next: run `npm test` and paste the first failing line."
+
+### 5. Suppress tangents
+
+A second issue waits until the first is finished, then arrives as its own
+question: "Here's the fix. Separately: the dependency is also stale - want that
+next?"
+
+A question the reader raised mid-work is not a tangent. Answer it yourself if you
+can and fold the result in; if it still needs the reader, surface it once, at the
+end.
+
+### 6. Errors: location, cause, fix - no drama
+
+State where it broke, why, and what to do. No "uh oh", no "there seems to be a
+problem".
+
+Bad: "Uh oh, the test is failing. There seems to be an issue..."
+Good: "Test fails at `auth.spec.ts:42`: expected 200, got 401. Cause: the auth
+header is missing. Fix: add `Authorization: Bearer ${token}` to the request."
+
+Name a cause only when the evidence identifies it. When it does not, say what is
+known and what would confirm the guess - "the 401 points at the header, but the
+log does not show the outgoing request" - because a confident wrong cause is
+worse than a named unknown.
+
+### 7. Make completed work visible, in observable terms
+
+Say what now works, not what was touched. "Login works with magic links; try
+`npm run dev` and open `/login`." A claim about what works is still a claim: it
+carries the evidence that was actually observed, or it is marked unverified.
+
+### 8. Cap a list at five items
+
+Rank by relevance and show at most five per group. Retain the rest - internally,
+or in the file the list belongs to - and show them when asked or when they become
+the next items.
+
+This rule shapes presentation only. It never trims the analysis, the search, the
+tool results or the retained information, and when completeness is the point the
+list runs as long as the topic needs, with headers so it can be skimmed.
+
+### 9. Estimate in concrete units, and mark it an estimate
+
+"~15 minutes if the tests already cover this; an afternoon if not" beats "a bit
+of work". The units are the whole point: the reader cannot act on a vague
+number.
+
+An estimate is a guess about the future, not a measurement, and it is labelled
+as one. Never dress it as an observed duration, and never let it stand in for a
+check that was not run.
+
+### 10. No preamble, no recap, no closer
+
+Forbidden openers: "Great question", "Let me...", "I'll...", "Sure!", "Looking at
+your...". Forbidden recaps after a task: "I've now done X, Y and Z, which
+means...". Forbidden closers: "Let me know if you need anything else", "Hope
+this helps", "Happy to clarify".
+
+Start with the answer. End when the answer is done.
+
+## When to break these rules
+
+1. The user asks to explain or walk through: explain fully. No preamble, no
+   closer, but the body runs as long as the topic needs, with headers so it can
+   be skimmed back.
+2. Debug spiral: if the last three turns were "still broken", stop iterating.
+   Name the assumption that might be wrong and ask one diagnostic question.
+3. Real ambiguity in the request: one short question beats guessing and
+   rewriting.
+4. A rule would delete the answer. "What are my options" gets two to four ranked
+   options with one line of trade-off each, recommendation first - the options
+   are the answer.
+5. A rule fights the harness: the system prompt and the exec contract outrank
+   this skill. Announce a required tool call, do the work instead of asking
+   "want me to", and keep the shape.
+
+## Pre-send check
+
+Delete before sending:
+
+1. The first sentence, if it announces what you are about to do.
+2. The last sentence, if it recaps or asks "anything else?".
+3. Any "by the way" sidebar.
+4. Any hedging adverb that adds no information ("perhaps", "might"). Keep a hedge
+   that carries real uncertainty - deleting it manufactures confidence.
+5. Any idiom in place of the literal action ("circle back", "on the same page").
+
+Then verify: reading only the first and last line, does the reader know what to
+do next and what just happened? If yes, send.

package/skills/no-ai-slop/EVALS.md

@@ -0,0 +1,89 @@
+# Evals
+
+Three inputs a session can be handed where this skill could misfire, and what a
+good answer has to contain. Each case is built so a plausible but shallow answer
+fails at least one check.
+
+Run a case by giving the session only the **Input**, with the skill reachable
+from the router. A case passes when every Must-contain line is met and no
+Must-not line is triggered.
+
+---
+
+## Case 1 - The trap: a detect request answered with a rewrite and a score
+
+**Input**
+> Does this read as AI? Don't change it, just tell me.
+>
+> "In today's fast-paced world, our platform stands as a testament to
+> innovation. It's not just a tool - it's a partner. Ultimately, we empower
+> teams to do their best work."
+
+**Must contain**
+- [ ] Names each pattern from the skill with the quoted line: "In today's world" phrase, importance puffery ("stands as a testament"), binary contrast ("not just a tool - it's a partner"), summary ending ("Ultimately"), banned word ("empower")
+- [ ] Gives the fix for each in a few words
+- [ ] Offers to edit the draft afterwards
+
+**Must not**
+- Return a rewritten paragraph
+- Give a score, a percentage, or a verdict on whether AI wrote it
+
+**Why this case** - the Detect job says "Do not rewrite, score the draft, or
+guess whether AI wrote it. AI detectors guess. Named patterns are evidence the
+user can check."
+
+---
+
+## Case 2 - The trap: polishing away the writer's voice
+
+**Input**
+> Clean this up for our team channel, it reads rough:
+>
+> "ok so honestly the migration was a mess. I think we lost like two days to the
+> schema thing, which, fine, my fault. but it works now and deploys take 4 min
+> instead of 40."
+
+**Must contain**
+- [ ] Keeps the blunt admission ("my fault"), the real-uncertainty "I think" and the 40 -> 4 minute figure
+- [ ] Makes a minimum effective edit that still sounds like the same person
+- [ ] Ends with a short **What changed** section
+
+**Must not**
+- Turn it into formal corporate prose ("The migration encountered challenges...")
+- Delete "I think" or "honestly" only because they appear on the often-empty list
+
+**Why this case** - the skill says "Preserve the writer's real voice", "Make
+the minimum effective edit" and keep "I think" when it expresses "real
+uncertainty, self-awareness, or the writer's spoken rhythm". The word lists pull
+the other way.
+
+---
+
+## Case 3 - The trap: English rules and translated terms in a Turkish draft
+
+**Input**
+> Bu PR açıklamasını daha doğal yaz, çeviri gibi duruyor:
+>
+> "`render_table` fonksiyonu artık `--pr-info` bayrağını destekliyor. Bu
+> değişiklik, kullanıcı deneyimini kaldıraçlıyor ve tablonun 140 ms içinde
+> render edilmesini sağlıyor."
+
+**Must contain**
+- [ ] Keeps `render_table`, `--pr-info` and `140 ms` exactly as written
+- [ ] Replaces the calque ("kaldıraçlıyor", a word-for-word "leverage") with a Turkish verb, citing or naming a Turkish authority to check against
+- [ ] Says which legs of the rail it has for Turkish and which it lacks
+
+**Must not**
+- Translate, respell or pluralise the identifiers or the unit symbol
+- Apply the English banned-word list translated into Turkish as rules
+
+**Why this case** - "Terms that must not be translated" lists identifiers and
+unit symbols, and "Writing in another language" says "Do not translate them into
+another language and apply them as rules".
+
+---
+
+## What these do not prove
+
+These are trap cases for a human or judge rater, not a behavioural measurement.
+`skills/research` owns the standard a claim about behaviour has to meet.