Deprecate inactive skills

deprecated/design-skill/GLOSSARY.md

@@ -0,0 +1,304 @@
+# Glossary — Structural Predictability
+
+The disclosed domain model for [`design-skill`](SKILL.md).
+Every term below is a lever on **Predictability**.
+
+The terms are grouped by axis: **Invocation** (how a skill is reached), **Information Hierarchy** (how its content is arranged), **Steering** (how the agent's runtime behaviour is shaped), and **Pruning** (how it is kept lean).
+Each **failure mode** lives beside the lever that cures it, tagged _failure mode_.
+
+**Bold terms** in any definition are themselves defined in this glossary.
+Find them by their heading.
+
+## Predictability
+
+The degree to which a skill makes the agent behave the same _way_ on every run — the same process, not the same output.
+A brainstorming skill should _predictably_ diverge because its tokens vary while its behaviour does not.
+The root virtue every other term serves — cost and maintainability are symptoms of it, not rivals.
+
+_Avoid_: consistency, reliability, robustness, output-determinism
+
+## Invocation
+
+How a skill is reached — and the two loads you pay for the choice.
+
+### Model-Invoked
+
+A skill exposed to the model's available-skills index so the agent can discover and load it autonomously.
+The human can still invoke it directly, so model-invocation always includes user reach.
+It pays permanent **context load** in exchange for discoverability.
+A model-invoked skill whose content is all **reference** can provide shared reference to other discoverable skills.
+Pick model-invocation only when the agent must reach the skill on its own.
+
+_Avoid_: ability, tool, capability
+
+### User-Invoked
+
+A skill hidden from autonomous model discovery and reached deliberately by the human through the target harness's invocation mechanism.
+It trades agent discoverability for zero **context load**.
+Agent Skills still require a **description**, so use a documented harness control such as `disable-model-invocation` rather than deleting required metadata.
+If the target harness cannot hide a skill from model discovery, report that user-only invocation is unsupported rather than inventing a mechanism.
+
+_Avoid_: procedure, workflow, command
+
+### Description
+
+Required Agent Skills metadata stating what the skill does and when it applies.
+For a **model-invoked** skill, it is the top-level **context pointer** kept in the model's available-skills index and the source of that skill's **context load**.
+For a **user-invoked** skill, it remains valid metadata but the harness keeps it out of the model's index.
+
+_Avoid_: frontmatter, summary
+
+### Context Pointer
+
+A reference held in the agent's context that names some out-of-context material and encodes the condition for reaching it.
+The **description** is the top-level context pointer from the context window to the skill.
+Pointers to disclosed files are the same object one level down.
+Its wording, not the target, decides _when_ the agent reaches — and _how reliably_.
+A must-have target behind a weakly worded pointer is a variance bug: fix the wording first, and inline the material only if sharpening fails.
+
+_Avoid_: link, reference, import
+
+### Context Load
+
+The cost a **model-invoked** skill imposes on the agent's context window through its indexed **description**, spending both tokens and attention.
+A **user-invoked** skill escapes this load because the harness does not expose its description to the model.
+Context load is the brake on splitting behavior into more model-invoked skills.
+
+_Avoid_: token cost, context bloat
+
+### Cognitive Load
+
+The cost a **user-invoked** skill imposes on the human — what they must hold in their head: which skills exist and when to reach for each (the human is the index).
+What **model-invocation** removes by being agent-discoverable, and the brake on splitting into more user-invoked skills.
+It is not a cost to minimise.
+It is the price of human agency and the reason some skills stay user-invoked.
+Spend it where human judgement matters.
+Remove it where it does not.
+
+_Avoid_: human index, burden, overhead
+
+### Router Skill
+
+A **user-invoked** skill whose job is to name other user-invoked skills and explain when the human should reach for each one.
+It gives the human one entry point to remember instead of many.
+It can only direct the human toward skills hidden from model discovery, not make those skills autonomously discoverable.
+It is the cure for **cognitive load** when user-invoked skills multiply.
+
+_Avoid_: dispatcher, menu, registry, index, router procedure
+
+### Granularity
+
+How finely you divide skills.
+Finer division spends one of the two loads.
+More **model-invoked** skills spend **context load** as more descriptions crowd the window and compete for attention.
+More **user-invoked** skills spend **cognitive load** by giving the human more to remember and reach for.
+Two cuts guide the division.
+By **invocation**, split off a model-invoked skill where you have a distinct **leading word** to trigger it — a trigger word you actually use in your prompts.
+By **sequence**, split a run of **steps** only when the hand-off creates a real context boundary that hides a step's **post-completion steps**.
+Beware the reverse.
+Merging sequences exposes each step's post-completion steps to what follows, inviting premature completion.
+
+_Avoid_: chunking, modularity
+
+## Information Hierarchy
+
+How a skill's content is arranged, and how far down the ladder each piece sits.
+
+### Information Hierarchy
+
+A skill's content ranked by how immediately the agent needs it — a single ladder, produced by two cuts: in-file or behind a pointer, and step or reference.
+The rungs:
+
+- **Steps** — in-file, primary
+- **Reference**, in-file — secondary
+- **Reference**, disclosed — behind a **context pointer**
+
+A skill with no **steps** uses just the bottom two rungs — often a legitimately flat peer-set (e.g. every rule of a review on one rung), which is a fine arrangement, not a smell.
+The hierarchy is independent of invocation: a skill can be model- or user-invoked whether it is all steps, all reference, or both.
+When a skill has steps, in-file reference that should be disclosed buries them and turns attending to them into a coin-flip — a variance lever, not just a legibility one.
+Keep the top of the ladder legible.
+Push down it whatever you can.
+
+_Avoid_: structure, organization, layout
+
+### Steps
+
+The ordered actions the agent performs — when a skill has them, the primary tier of its content, and the part that earns its place in SKILL.md.
+Not every skill has steps: a skill can be all steps (`test-driven-development`), all **reference** (a review), or both, independent of invocation.
+Every step ends on a **completion criterion**, clear or vague.
+
+_Avoid_: workflow, instructions, choreography
+
+### Reference
+
+Material the agent refers to on demand — definitions, facts, parameters, examples, conditional instructions.
+When a skill has **steps**, reference is secondary to them.
+When a skill has none, reference is the entire content.
+Reference can also live outside any skill entirely under **External Reference**.
+Reached via **context pointers**, and the prime candidate for **progressive disclosure**.
+
+_Avoid_: supporting material, docs, background
+
+### External Reference
+
+**Reference** that lives outside the skill system as a plain, non-invocable file with no **description** or **steps**.
+Any skill can point at it.
+It is the home for shared reference that need not fire on its own and can be used by skills hidden from one another's discovery surface.
+
+_Avoid_: doc, resource, knowledge base
+
+### Progressive Disclosure
+
+Moving **reference** down the ladder — out of SKILL.md and behind a **context pointer** — so the top stays legible.
+It is not primarily a token optimisation.
+It is how the **information hierarchy** is protected.
+Licensed by **branching**: disclose what only some branches need, inline what every path needs, and if a pointer fires unreliably on must-have material, sharpen its wording, and pull it back inline only if that fails.
+
+_Avoid_: lazy loading, chunking
+
+### Co-location
+
+Keeping the material an agent needs at once in one place — a concept's definition, rules, and caveats under a single heading, not scattered across the file — so reading one part brings its neighbours with it.
+The within-file companion to the **Information Hierarchy**.
+The hierarchy ranks _how far down_ a piece sits, while co-location decides _what sits beside it_ once there.
+There is no formula for the right format of a body of **reference**.
+The test is that a skill should read like documentation written for the agent, and grouped material reads that way where scattered material does not.
+Distinct from **Duplication**: that repeats one meaning in two places, where scattering fragments a single meaning across many.
+
+_Avoid_: grouping, clustering, cohesion
+
+### Sprawl
+
+_Failure mode._ A skill that is simply too long — too many lines in SKILL.md — independent of whether they are stale or repeated.
+Even an all-live, all-unique skill can sprawl.
+It costs readability (the agent wades through more before it can act, and attention thins across the excess), maintainability (every extra line is one more to keep **relevant**), and tokens.
+The cure is the **information hierarchy**: push **reference** down behind **context pointers**, and split by **branch** or sequence so each path carries only what it needs.
+Distinct from **sediment** (length from stale accumulation) and **duplication** (length from repeated meaning) — sprawl is length itself, whatever its cause.
+
+_Avoid_: bloat, length, size, verbosity
+
+## Steering
+
+The levers that shape the agent's runtime behaviour toward **Predictability**.
+
+### Branch
+
+A distinct way a skill can be invoked — a case the skill handles — so different runs take different paths through it.
+A skill with many steps may carry many branches.
+A linear one has none.
+
+_Avoid_: path, case, fork
+
+### Leading Word
+
+A compact concept — also called a _Leitwort_ — already living in the model's pretraining, that the agent thinks with while running the skill.
+It encodes a behavioural principle in the fewest possible tokens by invoking priors the model already holds, such as _lesson_, _proximal zone of development_, _fog of war_, or _tracer bullets_.
+Repeated as a token, never as a sentence, it accumulates a distributed definition across the skill and anchors a whole region of behaviour.
+Coining your own works if you define it clearly, but a made-up word recruits no priors — you pay in definition tokens what a pretrained word gives free.
+Reach for an existing word first.
+
+A leading word serves **predictability** twice.
+In the body it anchors **execution** — the agent reaches for the same behaviour every time the concept appears, and inside flat reference it focuses attention on a class of thing to look for, recruiting the right checks each run.
+For a **model-invoked** skill, the **description** anchors **invocation**.
+When the same word lives in prompts, documentation, and code, the agent links that shared language to the skill and fires it more reliably.
+Word a model-invoked skill's description with the leading words actually used to request its behavior.
+
+_Avoid_: keyword, term, motif
+
+### Completion Criterion
+
+The condition that tells the agent a unit of work is done — the target it judges against.
+Two properties make it a lever, not just a quality.
+Its **clarity** asks whether the agent can tell done from not done.
+Clarity resists **premature completion** because a vague bound such as "understanding reached" lets the agent declare done and slip to the next step.
+This axis needs _steps_ to bite because premature completion is a between-steps failure.
+Its **demand** (how much it requires) sets **legwork** — "every modified model accounted for" forces thorough work where "produce a change list" does not — and this axis is _not_ step-bound: it can bind a body of flat reference too, which is how a skill with no steps still carries an exhaustiveness bar ("every rule applied").
+The strongest criteria are both checkable and exhaustive.
+
+_Avoid_: done condition, exit condition, stopping rule
+
+### Legwork
+
+The work an agent does behind the scenes within a single step — reading files, exploring the codebase, making changes, digging up what it needs rather than offloading to the user.
+It lives below the step structure: never written as its own step, latent in the wording, controlled by the agent rather than the skill.
+The within-step counterpart to **post-completion steps**' across-step pull.
+Raised by a strong **leading word** or a **completion criterion** that demands exhaustive work.
+The demand axis also applies to flat reference and drives a reference-only skill to cover every required check.
+Goes thin either when that demand is missing or when **premature completion** cuts the step short.
+
+_Avoid_: scope, effort, diligence, coverage
+
+### Post-Completion Steps
+
+The **steps** that follow the current step.
+Visible post-completion steps pull the agent forward into **premature completion**.
+The more it sees, the stronger the tug.
+The defence is to hide them by splitting the sequence of steps into two.
+
+_Avoid_: horizon, fog of war, lookahead
+
+### Premature Completion
+
+_Failure mode._ Ending the current step before it is genuinely done, because the agent's attention slips to being done rather than to the work.
+A between-steps failure: it needs **steps** to occur — a skill with no steps that quits early isn't premature completion but thin **legwork** under an unmet demand.
+It is a tug-of-war between visible **post-completion steps**, which pull forward, and the **completion criterion**'s clarity, which resists that pull.
+A sharp, checkable bar holds while a vague one gives way.
+Fuzziness is the necessary condition: a sharp bound resists the pull no matter how many later steps are visible, so a step that never rushes needs no defending.
+Two levers hold a step that does, but reach for them in order: **sharpen the bound first** — it is local and cheap.
+Only when the criterion is irreducibly fuzzy _and_ you actually observe the rush do you **hide the later steps**.
+Hiding works only across a real context boundary such as a user-invoked hand-off or a subagent dispatch.
+An inline model-invoked call leaves the later steps in context and clears nothing.
+One cause of thin legwork, but distinct from it: legwork can be thin even when a step runs to full completion.
+
+_Avoid_: premature closure, the rush, rushing, shortcutting
+
+## Pruning
+
+Keeping a skill lean — each remedy paired with the failure it cures.
+
+### Single Source of Truth
+
+The desired state where each meaning lives in exactly one authoritative place, so a change to the skill's behaviour is a change in one place.
+**Duplication** is its violation.
+
+_Avoid_: home, canonical location
+
+### Duplication
+
+_Failure mode._ The same meaning given more than one **single source of truth**.
+It costs maintenance (change one place, you must change the others), costs tokens, and inflates prominence — repeating a meaning weights it on the ladder past its real rank.
+The accidental inverse of a **leading word**, which raises attention on purpose by repeating a token, never the meaning.
+
+_Avoid_: repetition, redundancy
+
+### Relevance
+
+Whether an instruction still bears on what the skill does — the lens for what to keep.
+An instruction loses relevance either by never bearing on the task or by going stale as the behavior or world it describes changes.
+Shorter skills are easier to keep relevant because each instruction is cheaper to check.
+Distinct from **no-op**: relevance asks whether an instruction bears on the task, not whether it changes behavior.
+
+_Avoid_: load-bearing, staleness, freshness
+
+### Sediment
+
+_Failure mode._ Layers of old content that settle in a skill and are never cleared, because adding feels safe and removing feels risky — so stale and irrelevant lines accumulate and you must core down through them to find what is still live.
+This is the default fate of any skill without a pruning discipline.
+It is the slow erosion of **relevance**, as opposed to **duplication**'s repeated meaning.
+
+_Avoid_: accretion, bloat, cruft, rot
+
+### No-Op
+
+_Failure mode._ An instruction that changes nothing because the model already does it by default — you pay load to tell the agent what it would do anyway.
+The test asks whether an instruction changes behavior versus the default.
+An instruction can be perfectly **relevant** and still be a no-op.
+The same priors that make a **leading word** free make a no-op worthless.
+
+A leading word is a _technique_, while No-Op is a _verdict_ on an instruction.
+The two concepts cross.
+A leading word too weak to beat the default is a no-op (_be thorough_ when the agent is already thorough-ish), and the fix is a stronger word that passes the verdict (_relentless_), not a different technique.
+So the No-Op test — does it change behaviour versus the default? — is also how you grade whether a leading word is earning its repetitions.
+This is model-relative, not reader-relative: two people disagreeing over whether a line is a no-op disagree about the default, and settle it by running the skill, not by debate.
+
+_Avoid_: redundant instruction, restating the obvious, belaboring

deprecated/design-skill/SKILL.md

@@ -0,0 +1,144 @@
+---
+name: design-skill
+description: Draft a new Agent Skill, or audit and rewrite an existing one for structural predictability. Run deliberately as /skill:design-skill when designing or improving a skill, never automatically.
+disable-model-invocation: true
+---
+
+# design-skill
+
+Judge only structural **predictability** using the terms in [`GLOSSARY.md`](GLOSSARY.md).
+Do not expand the work into general prose, safety, or technical review.
+Read each relevant definition before applying it.
+
+## Select the branch
+
+Use **Draft a new skill** when the request describes a new capability or repeated process with no existing skill to modify.
+Use **Audit an existing skill** when the request names an existing skill to review, fix, or improve.
+
+Both branches end at **Verify**.
+
+## Draft a new skill
+
+### 1. Capture intent
+
+Extract every answer already settled by the conversation or target project before asking anything.
+Ask one question at a time only for missing decisions:
+
+- Is the skill a **procedure**, **reference**, or both?
+- Should it be model-invoked or user-invoked?
+  Walk the **context load** and **cognitive load** trade-off rather than defaulting.
+- What distinct **branches** take genuinely different paths?
+- Does project documentation already own any required material?
+  Point to that **external reference** instead of duplicating it.
+- What checkable **completion criterion** ends each step?
+- Does the project already use a **leading word** for the behavior?
+
+Done when every item is settled or the user explicitly asks for a draft to iterate on.
+
+### 2. Resolve the canonical source
+
+Read the target project's instructions and inspect its repository structure before choosing a destination.
+Prefer an existing Agent Skills source convention.
+For a project-specific skill, use the project's canonical project-local skill source.
+For a general skill, use the personal collection named by the user or project instructions.
+
+Do not edit generated, installed, vendored, or compatibility surfaces as source.
+When the discovered skill is a link or generated placement, trace it to its canonical source.
+If multiple plausible sources remain, ask which one owns the skill.
+
+Done when the destination is writable, authoritative, and inside the intended project or collection.
+
+### 3. Write the skill
+
+Use the Agent Skills standard as the baseline:
+
+- Put the skill in a directory containing `SKILL.md`.
+- Give the frontmatter a valid `name` and a specific `description`.
+- Use documented harness extensions only when the target environment supports them.
+- Keep paths relative to the skill directory.
+
+Follow the **information hierarchy**.
+Keep ordered **steps** in `SKILL.md`, keep reference needed by every branch nearby, and disclose branch-specific or extensive reference through precise pointers.
+Reuse authoritative project documentation rather than restating it.
+Every branch must have a complete path, every step must have a checkable completion criterion, and every sentence must pass the **no-op** test.
+
+Done when the skill conforms to the target project's conventions and every captured decision has one authoritative expression.
+
+## Audit an existing skill
+
+### 1. Locate and read it
+
+Read the target project's instructions and locate the named skill's canonical source.
+Trace generated or linked placements rather than editing them.
+Ask only when multiple plausible sources remain.
+Read `SKILL.md`, every disclosed file, and any project documentation it treats as authoritative.
+
+Done when the full design and every source-of-truth boundary are visible.
+
+### 2. Apply the predictability checklist
+
+Check every relevant definition in `GLOSSARY.md` and quote the exact offending passage for each finding:
+
+- **Premature completion**: does each step end on a checkable criterion demanding all required work?
+- **Duplication**: does any meaning have more than one source of truth?
+- **Sediment**: does any sentence no longer bear on the skill's behavior?
+- **Sprawl**: should reference be disclosed or a genuine branch be separated?
+- **No-op**: does each sentence change model behavior from the default?
+- **Invocation**: does the chosen invocation mode fit actual use and target-harness support?
+- **Leading word**: can repeated explanation collapse into established vocabulary?
+
+Judge sentence by sentence rather than line by line.
+A line may contain both a load-bearing sentence and a no-op sentence.
+
+Done when every glossary failure mode has been checked and every finding has quoted evidence.
+
+### 3. Rewrite it
+
+Rewrite the canonical source to address every finding.
+Preserve intentional behavior that passed the checklist.
+Follow target-project instructions for any change outside the skill directory.
+
+Done when every finding is fixed or explicitly retained with a structural reason.
+
+## Verify
+
+### 1. Run deterministic checks
+
+Run the target project's required checks and any available Agent Skills validator.
+At minimum, verify frontmatter, naming, relative references, disclosed-file existence, and invocation compatibility with the target harness.
+
+Done when every available deterministic check passes and every unavailable check is reported.
+
+### 2. Smoke-test behavior
+
+Derive one realistic task prompt from the skill's intended trigger phrasing.
+Launch a fresh context through an actual subagent tool or documented headless harness command, load the skill there, and run the prompt.
+The fresh context must attempt the target skill's task rather than design or audit that skill.
+Save the exact prompt and fresh-context output in temporary files outside the target project.
+Inspect that output for whether the agent followed the intended branch, hesitated, misread an instruction, or behaved unexpectedly.
+Do not count the current design run, a self-review, or deterministic validation as behavioral evidence.
+A smoke test does not require advance approval.
+
+Done when the final report names the fresh-context mechanism and both evidence paths, and the captured output shows no structural confusion.
+If no isolated execution mechanism exists, report that limitation instead.
+
+### 3. Offer stronger verification when available
+
+Detect whether the target project has an established behavioral test or benchmark convention for skills.
+Use existing persistent tests when present.
+Create a persistent test only when project instructions require one.
+
+Before running a stochastic, repeated, paid, or otherwise substantial benchmark, show the user the proposed scenario and obtain approval.
+If approval is declined, retain the smoke-test result as the weaker evidence level.
+
+Done when an approved benchmark passes, the user declines it, or no established benchmark exists.
+
+### 4. Re-audit and finish
+
+Re-read the final skill against every applicable `GLOSSARY.md` failure mode in light of verification.
+Fix every new finding and repeat affected checks after a substantial fix.
+Follow explicit user or project instructions for staging or other version-control actions.
+Otherwise leave changes unstaged and report every changed path.
+Never commit unless explicitly instructed.
+
+Done when no structural finding remains, required checks pass, behavioral confidence is stated accurately, and the applicable version-control policy was followed.

deprecated/grill/CONTEXT-FORMAT.md

@@ -0,0 +1,30 @@
+# Context Artifact Format
+
+## Structure
+
+```md
+# {Context Name}
+
+{One or two sentence description of what this context is and why it exists.}
+
+## Language
+
+**Order**:
+{A one or two sentence description of the term}
+_Avoid_: Purchase, transaction
+
+**Invoice**:
+A request for payment sent to a customer after delivery.
+_Avoid_: Bill, payment request
+
+**Customer**:
+A person or organization that places orders.
+_Avoid_: Client, buyer, account
+```
+
+## Rules
+
+- **Be opinionated.** When multiple words exist for the same concept, pick the best one and list the others under `_Avoid_`.
+- **Keep definitions tight.** One or two sentences max. Define what it IS, not what it does.
+- **Only include terms specific to this project's context.** General programming concepts (timeouts, error types, utility patterns) don't belong even if the project uses them extensively. Before adding a term, ask: is this a concept unique to this context, or a general programming concept? Only the former belongs.
+- **Group terms under subheadings** when natural clusters emerge. If all terms belong to a single cohesive area, a flat list is fine.

deprecated/grill/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: grill
+description: Interview the user relentlessly to stress-test a plan or design before building — one question at a time, each with options, a recommendation, and its rationale — walking the decision tree until every branch is decided. Folds in domain-model and ADR upkeep when the project has a context file. Model-invokable, including as a step inside other skills. Use when the user wants to pressure-test a plan, or uses any 'grill' trigger phrase.
+---
+
+# grill
+
+Interview the user relentlessly about every aspect of a plan or design.
+Keep going not until it feels like you understand each other, but until the decision tree is walked to exhaustion.
+
+Ask one question at a time, in plain text, and wait for the answer before the next.
+Never use an interactive question tool.
+While the interview is active, every assistant turn must end with exactly one of: the next numbered question, the final decision summary, or a plain statement that grill is paused because the user explicitly changed tasks.
+If the turn includes a correction, file edit, apology, or explanation, follow it with the next numbered question unless the user explicitly paused grill or changed tasks.
+Do not use dangling transition phrases such as “continuing” unless the continuation is actually present in the same message.
+Every question carries **options** — the concrete choices, each with its trade-offs — followed by your **recommendation**, the option you would pick and why.
+When the question turns on an existing document, artifact, or piece of code, open it with a **context quote**: blockquote the exact passage, so the user sees what you mean without hunting for it.
+
+Before asking, investigate.
+When code, docs, or the conversation already settle a question, resolve it yourself instead of spending a question on it.
+
+**Never begin implementation** — during the interview or after it — without an explicit instruction from the user.
+This holds even when another skill invoked grill: grill delivers its summary and stops, and a caller that receives that summary is not itself the instruction to build.
+
+## 1. Select the mode
+
+Resolve the artifact destination before looking for or creating artifacts.
+Default to `$(xdg-user-dir DOCUMENTS)/ai-artifacts/projects/<project>` when the AI artifacts vault is available, where `<project>` is the lowercase basename of the current working directory.
+If that vault is unavailable, fall back to `./docs` in the current project.
+Create the destination directory only when a write requires it.
+Read the destination's `AGENTS.md` before any artifact write.
+Inspect the destination directly for its context artifact, using the destination naming convention instead of assuming a filename.
+
+- **Domain Modeling Mode** — exactly one context artifact was found.
+  Run the interview and maintain the project's domain model as terms settle (see [Domain Modeling Mode](#domain-modeling-mode)).
+- **Free Mode** — no context artifact was found, and the plan raises no project-specific vocabulary worth pinning down.
+  Run the interview with no document side effects.
+- **Clarification** — no context artifact was found, but the plan introduces terms specific to this project that later work will need to use consistently — the kind of terms [`CONTEXT-FORMAT.md`](CONTEXT-FORMAT.md) admits, not general programming concepts.
+  Before interviewing, ask whether to create a glossary.
+  If yes, choose the context artifact filename from the destination's `AGENTS.md` and nearby artifact convention, allocate any required identifier, and continue in Domain Modeling Mode.
+  If no, continue in Free Mode.
+
+Stop and report the conflicting paths if more than one matching context artifact exists.
+Done when the interview is running in Domain Modeling Mode or Free Mode.
+
+## 2. Run the interview
+
+Walk the decision tree one branch at a time, resolving each decision's dependencies before moving to the next.
+Alongside the questions, challenge and stress-test:
+
+- When the user's language is vague or overloaded, propose a precise canonical term in its place.
+- Probe edge cases with concrete scenarios that force the boundaries between concepts to be made explicit.
+- When a stated behavior contradicts what the code actually does, surface the contradiction with both sides quoted.
+
+In Domain Modeling Mode, feed the settling terms and decisions into the glossary and ADRs below.
+
+Done when every branch carries an explicit decision and no dependency between decisions is left open.
+
+## 3. Close the interview
+
+Once the interview is done:
+
+1. Output a concise summary of every decision reached — and, in Domain Modeling Mode, every term crystallized.
+2. Stop and wait for the user's next instruction.
+
+Done when the summary is delivered and grill is waiting.
+
+## Domain Modeling Mode
+
+Active only when step 1 selected this mode.
+
+### Glossary
+
+As a term crystallizes, update the context artifact right then — do not batch these to the end.
+When a settling term clashes with one already in the glossary, call it out and reconcile to a single canonical word.
+Keep the artifact a glossary and nothing else: vocabulary and ubiquitous language, no implementation detail.
+Write it in the format of [`CONTEXT-FORMAT.md`](CONTEXT-FORMAT.md).
+
+### ADRs
+
+Offer to record an architectural decision only when all three hold:
+
+1. **Hard to reverse** — changing your mind later carries real cost.
+2. **Surprising without context** — a future reader will wonder why it was done this way.
+3. **The result of a real trade-off** — there were genuine alternatives and you picked one for specific reasons.
+
+If any of the three is missing, skip it.
+A recorded decision lives directly in the resolved artifact destination.
+Choose its filename from the destination's `AGENTS.md` and nearby artifact convention, allocating an identifier only when that convention requires one.
+It can be a single paragraph:
+
+> # {Short title of the decision}
+>
+> {1-3 sentences: the context, what was decided, and why.}

deprecated/implement/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: implement
+description: Implement scoped work using the local implementation workflow, following task artifact protocol when an implementation task artifact is part of the selected work.
+disable-model-invocation: true
+---
+
+# implement
+
+Implement scoped work and hand off working code.
+This skill defines execution protocol rather than deciding what work the agent is allowed to implement.
+When selected work has an implementation task artifact, follow the task artifact lifecycle.
+When selected work has no task artifact, implement normally and use the same review, commit, and handoff discipline without creating a tracking artifact.
+
+This skill delegates to other skills by name.
+Before satisfying a delegated skill step, explicitly load that skill's `SKILL.md` with `read` unless the harness has already injected that skill's full content into the current context.
+Do not satisfy a delegated skill step by imitating its title from memory.
+
+## 1. Establish the selected work
+
+Identify the work to implement from the user's request and current context.
+Use an implementation task artifact, issue, spec, direct request, branch context, or other clear source when that is what the agent has selected.
+Do not require a task artifact and do not create one just to satisfy this skill.
+Old `.claude/tasks` files may be ordinary context, but their lifecycle semantics are not part of this workflow.
+
+When the selected work has an implementation task artifact, re-read it before claiming.
+Verify that blockers are satisfied by artifact metadata and that no other session has claimed it.
+Claim it before changing code by setting `status: claimed`, `claimed-by` to the current session identifier, and `claimed-at` to the current timestamp.
+Use `PI_SESSION_ID` when available.
+
+Done when the selected work is clear, and any implementation task artifact is freshly read and claimed when applicable.
+
+## 2. Verify the execution checkout
+
+Assume the current checkout is the assigned execution checkout.
+Do not create, lease, clean up, or switch worktrees.
+Report the checkout path and branch when useful for handoff.
+
+Check the working tree before changing code.
+Stop on unrelated or ambiguous uncommitted changes.
+Continue only when dirty state is clearly already part of the selected work.
+Never auto-stash.
+
+For source-changing implementation work that will be committed, work on a non-default branch unless repository context explicitly directs otherwise.
+If an appropriate non-default branch is already prepared, continue there.
+If you are on the default branch, fast-forward the default branch first and create a task branch.
+Stop if the default branch cannot fast-forward cleanly.
+Follow repository, user, or orchestrator branch naming conventions.
+If no convention is discoverable and you must create a branch, choose a clear short descriptive name and report it.
+
+Check declared implementation blockers where they exist.
+Stop when prerequisite implementation work is not reachable from the current base, and report the likely unmerged prerequisite.
+Do not automatically branch from, merge, or cherry-pick sibling task work.
+Follow an explicit integration-branch or wide-refactor plan only when the selected work names that exception.
+
+Done when the checkout, branch, dirty state, and reachable prerequisites are safe for the selected implementation work.
+
+## 3. Implement the work
+
+Use `test-driven-development` as a strong default when behavior can usefully be specified and tested before implementation.
+Load `test-driven-development` before deciding whether it applies.
+Skip it only when the work is mechanical, documentation-only, exploratory, or when test-first would not add value.
+When skipping it, state the reason before implementation.
+Skipping test-driven development is an agent judgment, not an omission.
+
+Build the selected work in the assigned checkout.
+Run focused verification while working and run broader verification when the repository or change calls for it.
+Treat working code and tests as the implementation artifact.
+Do not create a separate process report for test-driven development.
+Record only durable outcomes such as tests added or changed, verification run, and deviations worth noting.
+
+Stage created and modified files intentionally.
+Do not use broad staging that sweeps unrelated files into the change.
+
+Done when the selected work is implemented as working code and locally verified to the level the change warrants.
+
+## 4. Review the final intended handoff state
+
+Load and run `review` before reporting final handoff or resolving an implementation task artifact.
+Choose review timing by judgment.
+Review may happen before commit, after commit, or both.
+The review must cover the final intended handoff state, including a local uncommitted handoff when no commit is made.
+Do not report final handoff until review has run or you have explained why review could not cover that state.
+
+Fix blocking review findings unless the agent or user explicitly accepts them.
+When code changes are made in response to review, rerun `review` on the relevant change set.
+Record accepted blocking findings in the final handoff or task artifact result when they affect a future reader's decision to trust or continue the work.
+Handle non-blocking findings by judgment.
+Fix them when cheap or high-value, and otherwise report or record only when useful.
+
+Done when review has covered the final intended handoff state and blocking findings are fixed or explicitly accepted.
+
+## 5. Commit and hand off
+
+Follow the repository's commit and PR conventions.
+Discover those conventions from repository instructions or recent history rather than assuming them.
+Commit only the selected work.
+Use one commit when that is the natural shape, but follow the repository's convention when it expects a different history shape.
+
+Push and open a PR when the repository and selected workflow call for that handoff.
+If there is no remote or no supported forge workflow, stop after the local handoff point and report what remains for a human.
+Keep PR and handoff text focused on what was built, verification, review disposition, and any deviations that matter.
+
+Done when the implementation has a concrete handoff state: committed locally, pushed, opened as a PR, or stopped with the exact remaining human action reported.
+
+## 6. Record task artifact results when present
+
+When the selected work has an implementation task artifact, re-read it before recording results.
+Record durable coordination facts only.
+The `status` field is the lifecycle authority.
+Acceptance criteria checkboxes may be updated as useful detail with `[x]` for satisfied criteria and `[-]` for deliberately dropped criteria when practical.
+Checkbox state is not the source of truth.
+
+Keep Implementation Notes concise.
+Capture only what future agents or humans need: deviations, dropped or changed scope, verification, branch, commit, PR, or why the task remains unresolved.
+Use judgment for partial or ambiguous outcomes, but keep lifecycle recording honest.
+Do not imply completion when the work is not complete.
+
+When resolving an implementation task artifact, set `status: done`.
+Put detailed implementation records in the task, commit, PR, and working code.
+
+Done when any implementation task artifact agrees with the implementation's actual lifecycle state.

deprecated/prototype/LOGIC.md

@@ -0,0 +1,100 @@
+# Logic Prototype
+
+A tiny interactive terminal app that lets the user drive a state model by hand. Use this when the question is about **business logic, state transitions, or data shape** — the kind of thing that looks reasonable on paper but only feels wrong once you push it through real cases.
+
+## When this is the right shape
+
+- "I'm not sure if this state machine handles the edge case where X then Y."
+- "Does this data model actually let me represent the case where..."
+- "I want to feel out what the API should look like before writing it."
+- Anything where the user wants to **press buttons and watch state change**.
+
+If the question is "what should this look like" — wrong branch. Use [UI.md](UI.md).
+
+## Process
+
+### 1. State the question
+
+Before writing code, write down what state model and what question you're prototyping.
+Use one paragraph in the prototype's README or a comment at the top of the file.
+A logic prototype that answers the wrong question is pure waste, so make the question explicit enough to check later whether the user is watching now or returning to it AFK.
+
+Done when the prototype states one concrete logic question and the model being tested.
+
+### 2. Pick the language
+
+Use whatever the host project uses. If the project has no obvious runtime (e.g. a docs repo), ask.
+
+Match the project's existing conventions for tooling.
+Don't add a new package manager or runtime just for the prototype.
+
+Done when the prototype has a runnable host-project language and toolchain without introducing a new runtime convention.
+
+### 3. Isolate the logic in a portable module
+
+Put the actual logic — the bit that's answering the question — behind a small, pure interface that could be lifted out and dropped into the real codebase later. The TUI around it is throwaway; the logic module shouldn't be.
+
+The right shape depends on the question:
+
+- **A pure reducer** — `(state, action) => state`. Good when actions are discrete events and state is a single value.
+- **A state machine** — explicit states and transitions. Good when "which actions are even legal right now" is part of the question.
+- **A small set of pure functions** over a plain data type. Good when there's no implicit current state — just transformations.
+- **A class or module with a clear method surface** when the logic genuinely owns ongoing internal state.
+
+Pick whichever shape best fits the question being asked, *not* whichever is easiest to wire to a TUI. Keep it pure: no I/O, no terminal code, no `console.log` for control flow. The TUI imports it and calls into it; nothing flows the other direction.
+
+This is what makes the prototype useful past its own lifetime.
+When the question is answered, the validated reducer, machine, or function set can be lifted into the real module on its own.
+
+Done when all tested logic lives behind one portable, pure interface and the TUI depends on it in only one direction.
+
+### 4. Build the smallest TUI that exposes the state
+
+Build it as a **lightweight TUI** — on every tick, clear the screen (`console.clear()` / `print("\033[2J\033[H")` / equivalent) and re-render the whole frame. The user should always see one stable view, not an ever-growing scrollback.
+
+Each frame has two parts, in this order:
+
+1. **Current state**, pretty-printed and diff-friendly (one field per line, or formatted JSON). Use **bold** for field names or section headers and **dim** for less important context (timestamps, IDs, derived values). Native ANSI escape codes are fine — `\x1b[1m` bold, `\x1b[2m` dim, `\x1b[0m` reset. No need to pull in a styling library unless one is already in the project.
+2. **Keyboard shortcuts**, listed at the bottom: `[a] add user  [d] delete user  [t] tick clock  [q] quit`. Bold the key, dim the description, or vice-versa — whatever reads cleanly.
+
+Behaviour:
+
+1. **Initialise state** — a single in-memory object/struct. Render the first frame on start.
+2. **Read one keystroke (or one line)** at a time, dispatch to a handler that mutates state.
+3. **Re-render** the full frame after every action — don't append, replace.
+4. **Loop until quit.**
+
+The whole frame should fit on one screen.
+
+Done when every available action re-renders a complete one-screen view of the current state and shortcuts.
+
+### 5. Make it runnable in one command
+
+Add a script to the project's existing task runner (`package.json` scripts, `Makefile`, `justfile`, `pyproject.toml`). The user should run `pnpm run <prototype-name>` or equivalent — never need to remember a path.
+
+If the host project has no task runner, put the command at the top of the prototype's README.
+
+Done when a fresh user can launch the prototype with one documented command.
+
+### 6. Evaluate it
+
+In HITL mode, give the user the run command.
+They drive it themselves.
+The interesting moments are when they say "wait, that shouldn't be possible" or "huh, I assumed X would be different" because those expose bugs in the idea.
+Add actions when the feedback needs them.
+
+In AFK mode, run the command yourself and drive the hard cases that answer the stated question.
+Record the observations that support the verdict.
+
+Done when the evaluator can exercise the model and the prototype exposes every state transition needed to reach a verdict.
+
+## Production mapping
+
+When the shared [SKILL](SKILL.md) permits production work, lift the validated reducer, machine, or function set into the real module.
+Keep the TUI shell on the throwaway branch.
+
+## Anti-patterns
+
+- **Don't generalise.** No "what if we wanted to support X later." The prototype answers one question.
+- **Don't blur the logic and the TUI together.** If the reducer / state machine references `console.log`, prompts, or terminal escape codes, it's no longer portable. Keep the TUI as a thin shell over a pure module.
+- **Don't ship the TUI shell into production.** The shell is optimised for being driven by hand from a terminal. The logic module behind it is the bit worth keeping.

deprecated/prototype/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: prototype
+description: Build a throwaway prototype to answer a design question. Use when the user wants to sanity-check whether a state model or logic feels right, or explore what a UI should look like.
+---
+
+# Prototype
+
+A prototype is **throwaway code that answers one question**.
+The question decides the branch.
+The interaction mode decides who reaches the verdict.
+Use AFK mode when the question has objective observable criteria the agent can test end to end.
+Use HITL mode when the verdict depends on human judgment, taste, or UX feel.
+
+## 1. Pick a branch
+
+Identify the question from the user's prompt and surrounding code.
+Ask when it remains genuinely ambiguous and the user is reachable.
+
+- **Does this logic or state model feel right?**
+  Follow [`LOGIC.md`](LOGIC.md) to build a tiny interactive terminal app that pushes the model through hard-to-reason-about cases.
+- **What should this look like?**
+  Follow [`UI.md`](UI.md) to build several radically different UI variants on one route with a URL-controlled switcher.
+
+When the user is unavailable, default to Logic for a backend module and UI for a page or component, then state the assumption in the prototype.
+
+Done when exactly one branch and one design question govern the prototype.
+
+## Common rules
+
+- **Throwaway from day one.**
+  Locate the code close to where it would be used, but name it so nobody mistakes it for production.
+  Follow the project's routing and source-layout conventions rather than inventing a new top-level structure.
+- **One command to run.**
+  Use the project's existing task runner so the user does not need to remember a path or setup sequence.
+- **No persistence by default.**
+  Keep state in memory unless persistence is the question being tested.
+  Use an unmistakably disposable database or local file when that question requires one.
+- **Skip polish.**
+  Add no tests, production-grade error handling, speculative abstractions, or unrelated cleanup.
+- **Surface state.**
+  Show the full relevant state after every Logic action or UI variant switch.
+
+## 2. Build and reach a verdict
+
+Follow the selected branch through its evaluation step.
+In HITL mode, hand the prototype to the user and iterate in response to their feedback.
+In AFK mode, run the prototype yourself and evaluate the objective observations against the question.
+Do not treat a runnable prototype as the result.
+The result is the verdict that answers the design question.
+
+Done when the verdict is explicit, or when the prototype establishes that it did not resolve the question.
+
+## 3. Capture the primary source
+
+Commit the complete prototype to a throwaway branch outside main.
+The branch is the primary source.
+
+Resolve the artifact destination before naming the file.
+When the caller provides a destination directory, use it exactly.
+Otherwise, default to `$(xdg-user-dir DOCUMENTS)/ai-artifacts/projects/<project>` when the AI artifacts vault is available, where `<project>` is the lowercase basename of the current working directory.
+If that vault is unavailable, fall back to `./docs` in the current project.
+Create the destination directory only when needed.
+
+Before choosing a filename, read the destination's `AGENTS.md`.
+Use the naming convention declared there, or infer it from nearby artifacts when the file delegates naming to local context.
+Do not assume a counter, numeric prefix, slug shape, or artifact-type suffix unless the destination convention requires it.
+If no convention can be determined, choose the least surprising lowercase descriptive Markdown filename and state that the destination did not define a naming convention.
+
+When the caller provides an existing artifact path, use it exactly, do not allocate a filename, and complete that artifact in place.
+Otherwise, allocate any identifier required by the destination convention and include `parent` only when an earlier artifact directly caused the prototype.
+
+The Prototype artifact links the throwaway branch and preserves the question, run instructions, verdict, and branch-appropriate evidence.
+When the resolved file is an existing artifact, preserve its workflow metadata and complete the result in that file.
+
+The branch-appropriate evidence is:
+
+- UI evidence uses screenshots.
+- Logic evidence uses useful code snippets and, where needed, a short interaction transcript.
+
+Done when the complete prototype is committed outside main and exactly one Prototype artifact preserves the result according to the destination convention.
+
+## 4. Fold in the decision when permitted
+
+A planning-only caller stops after the verdict and leaves production code unchanged.
+Otherwise, fold the validated decision into production only when the caller permits implementation.
+Follow the selected branch's **Production mapping** and keep all other throwaway code out of main.
+
+Done when production is unchanged for a planning-only run, or contains only the permitted validated decision for an implementation run.

deprecated/prototype/UI.md

@@ -0,0 +1,124 @@
+# UI Prototype
+
+Generate **several radically different UI variations** on a single route, switchable from a floating bottom bar. The user flips between variants in the browser, picks one (or steals bits from each), then throws the rest away.
+
+If the question is about logic/state rather than what something looks like — wrong branch. Use [LOGIC.md](LOGIC.md).
+
+## When this is the right shape
+
+- "What should this page look like?"
+- "I want to see a few options for this dashboard before committing."
+- "Try a different layout for the settings screen."
+- Any time the user would otherwise spend a day picking between three vague mockups in their head.
+
+## Two sub-shapes — strongly prefer sub-shape A
+
+A UI prototype is much easier to judge when it's **butting up against the rest of the app** — real header, real sidebar, real data, real density. A throwaway route on its own is a vacuum: every variant looks fine in isolation. Default to sub-shape A whenever there's a plausible existing page to host the variants. Only reach for sub-shape B if the prototype genuinely has no nearby home.
+
+### Sub-shape A — adjustment to an existing page (preferred)
+
+The route already exists. Variants are rendered **on the same route**, gated by a `?variant=` URL search param. The existing data fetching, params, and auth all stay — only the rendering swaps. This is the default; pick it unless there's a specific reason not to.
+
+If the prototype is for something that doesn't yet have a page but *would naturally live inside one* (a new section of the dashboard, a new card on the settings screen, a new step in an existing flow) — that's still sub-shape A. Mount the variants inside the host page.
+
+### Sub-shape B — a new page (last resort)
+
+Only use this when the thing being prototyped genuinely has no existing page to live inside — e.g. an entirely new top-level surface, or a flow that can't be embedded anywhere sensible.
+
+Create a **throwaway route** following whatever routing convention the project already uses — don't invent a new top-level structure. Name it so it's obviously a prototype (e.g. include the word `prototype` in the path or filename). Same `?variant=` pattern.
+
+Before committing to sub-shape B, sanity-check: is there really no existing page this could be embedded in? An empty route hides design problems that a populated one would expose.
+
+In both sub-shapes the floating bottom bar is identical.
+
+## Process
+
+### 1. State the question and pick N
+
+Default to **3 variants**. More than 5 stops being radically different and starts being noise — cap there.
+
+Write down the plan in one line, in the prototype's location or a top-of-file comment:
+
+> "Three variants of the settings page, switchable via `?variant=`, on the existing `/settings` route."
+
+This works whether the user is here to push back or not.
+
+Done when the prototype states one concrete UI question, its host route, and a variant count from three through five.
+
+### 2. Generate radically different variants
+
+Draft each variant. Hold each one to:
+
+- The page's purpose and the data it has access to.
+- The project's component library / styling system (TailwindCSS, shadcn, MUI, plain CSS, whatever).
+- A clear exported component name, e.g. `VariantA`, `VariantB`, `VariantC`.
+
+Variants must be **structurally different** — different layout, different information hierarchy, different primary affordance, not just different colours. Three slightly-tweaked card grids isn't a UI prototype, it's wallpaper. If two drafts come out too similar, redo one with explicit "do not use a card grid" guidance.
+
+Done when every variant materially differs in layout, information hierarchy, and primary affordance while using the project's existing design system.
+
+### 3. Wire them together
+
+Create a single switcher component on the route:
+
+```tsx
+// pseudo-code — adapt to the project's framework
+const variant = searchParams.get('variant') ?? 'A';
+return (
+  <>
+    {variant === 'A' && <VariantA {...data} />}
+    {variant === 'B' && <VariantB {...data} />}
+    {variant === 'C' && <VariantC {...data} />}
+    <PrototypeSwitcher variants={['A','B','C']} current={variant} />
+  </>
+);
+```
+
+For sub-shape A (existing page): keep all the existing data fetching above the switcher; only the rendered subtree changes per variant.
+
+For sub-shape B (new page): the throwaway route under `/prototype/<name>` mounts the same switcher.
+
+Done when one route renders every variant from the URL parameter without duplicating data loading.
+
+### 4. Build the floating switcher
+
+A small fixed-position bar at the bottom-centre of the screen with three pieces:
+
+- **Left arrow** — cycles to the previous variant (wraps around).
+- **Variant label** — shows the current variant key and, if the variant exports a name, that name too. e.g. `B — Sidebar layout`.
+- **Right arrow** — cycles forward (wraps around).
+
+Behaviour:
+
+- Clicking an arrow updates the URL search param (use the framework's router — `router.replace` on Next, `navigate` on React Router, etc) so the variant is shareable and reload-stable.
+- Keyboard: `←` and `→` arrow keys also cycle. Don't intercept arrow keys when an `<input>`, `<textarea>`, or `[contenteditable]` is focused.
+- Visually distinct from the page (e.g. high-contrast pill, subtle shadow) so it's obviously not part of the design being evaluated.
+- Hidden in production builds — gate on `process.env.NODE_ENV !== 'production'` or an equivalent check, so a stray prototype merge can't ship the bar to users.
+
+Put the switcher in a single shared component so both sub-shapes can reuse it. Locate it wherever shared UI lives in the project.
+
+Done when mouse and keyboard controls cycle through every shareable variant without intercepting text-editing keys, and the switcher cannot render in production.
+
+### 5. Evaluate it
+
+In HITL mode, surface the URL and the `?variant=` keys.
+The user flips through the variants and may combine elements rather than choosing one unchanged.
+
+In AFK mode, open the URL yourself, compare every variant against the stated objective criteria, and record the observations that support the verdict.
+Use HITL instead when the decision depends on taste, product judgment, or UX feel.
+
+Done when the evaluator can compare every variant in its host context and the prototype exposes enough contrast to reach a verdict.
+
+## Production mapping
+
+When the shared [SKILL](SKILL.md) permits production work, keep the full variant set on the throwaway branch and apply the verdict as follows:
+
+- **Sub-shape A** — fold the winner into the existing page and drop the losing variants and switcher from main.
+- **Sub-shape B** — promote the winner to a real route and drop the throwaway route and switcher from main.
+
+## Anti-patterns
+
+- **Variants that differ only in colour or copy.** That's a tweak, not a prototype. Real variants disagree about structure.
+- **Sharing too much code between variants.** A shared `<Header>` is fine; a shared `<Layout>` defeats the point. Each variant should be free to throw out the layout.
+- **Wiring variants to real mutations.** Read-only prototypes are fine. If a variant needs to mutate, point it at a stub — the question is "what should this look like", not "does the backend work".
+- **Promoting the prototype directly to production.** The variant code was written under prototype constraints (no tests, minimal error handling). Rewrite it properly when you fold it in.

deprecated/research/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: research
+description: Investigate a question against high-trust primary sources and capture the cited findings as a Research artifact. Use when a topic needs documentation, API, specification, source-code, or other reading legwork.
+---
+
+# Research
+
+Investigate one question and preserve the findings in one cited Research artifact.
+Run in the current process.
+Isolation and concurrency belong to the caller.
+
+## 1. Resolve the artifact
+
+Resolve the artifact destination before naming the file.
+When the caller provides a destination directory, use it exactly.
+Otherwise, default to `$(xdg-user-dir DOCUMENTS)/ai-artifacts/projects/<project>` when the AI artifacts vault is available, where `<project>` is the lowercase basename of the current working directory.
+If that vault is unavailable, fall back to `./docs` in the current project.
+Create the destination directory only when needed.
+
+Before choosing a filename, read the destination's `AGENTS.md`.
+Use the naming convention declared there, or infer it from nearby artifacts when the file delegates naming to local context.
+Do not assume a counter, numeric prefix, slug shape, or artifact-type suffix unless the destination convention requires it.
+If no convention can be determined, choose the least surprising lowercase descriptive Markdown filename and state that the destination did not define a naming convention.
+
+When the caller provides an existing ticket artifact path, use it exactly, do not allocate a filename, and complete that artifact in place.
+Otherwise, allocate any identifier required by the destination convention and include `parent` only when an earlier artifact directly caused the research.
+
+Done when one authoritative Research artifact path and its metadata are settled according to the destination convention.
+
+## 2. Investigate the question
+
+Use primary sources such as official documentation, specifications, source code, and first-party APIs rather than relying on secondary accounts.
+Follow every substantive claim back to the primary source that owns it.
+Use secondary material only to discover primary sources.
+When no primary source establishes a needed claim, record that limitation instead of presenting the claim as settled.
+
+Done when the question is answered as far as primary evidence permits and every substantive claim has an owning source or an explicit evidence gap.
+
+## 3. Write the Research artifact
+
+Write the findings to the resolved Markdown file and follow the destination's artifact conventions.
+When the resolved file is an existing ticket artifact, preserve its workflow metadata and complete the result in that file.
+Keep the question, findings, limitations, and citations sufficient for a future reader to evaluate the result without reconstructing the research session.
+Do not create a source dump or research log.
+
+Done when exactly one Research artifact exists at the resolved path and every substantive claim in it cites its source.
+
+## 4. Return the result
+
+Report the artifact path and a concise statement of what the research established or could not establish.
+
+Done when the caller can locate the artifact and understand whether the question was resolved.

deprecated/review/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: review
+description: Produce a structured, report-only review of a context-selected change set across risk, standards, intent, evidence, and documentation.
+---
+
+# review
+
+Review a change set selected from context and produce a structured review report.
+This skill is standalone and context-driven.
+It does not know about implementation lifecycle, task claiming, task resolution, PR creation, or task result recording.
+It must not edit code.
+
+Reviewer prompts live under [`reviewers/`](reviewers/).
+Load the relevant reviewer files before running independent dimension reviews.
+
+## 1. Select and capture the change set
+
+Select the relevant change set from current context.
+The change set may be uncommitted changes, branch changes, a PR, explicit files, or another clear source.
+State what change set you selected before reviewing.
+Ask or stop only when scope ambiguity would make the review untrustworthy.
+
+Capture enough material for reviewers to inspect the selected change set.
+This may include a diff, changed-file list, commit list, PR details, relevant intent source, available verification evidence, and repository instructions or standards sources.
+Do not overprescribe mode selection or intent-source taxonomy.
+Use agent judgment when the selected change set and intent source are clear enough to review.
+
+Done when the chosen change set is explicit and reviewers have enough input to judge it.
+
+## 2. Run dimension reviews
+
+Run independent dimension reviewers through whatever real context boundary the current harness provides.
+A separate agent, worker, subprocess, or documented headless session is sufficient when each reviewer can inspect its dimension without seeing the parent review's intermediate conclusions.
+Use one reviewer per dimension when practical.
+If no real context boundary is available, stop before reviewing and report that independent review cannot be completed in the current runtime.
+Do not replace independent reviewers with in-process role switches.
+
+Use these reviewer files:
+
+- [`reviewers/risk.md`](reviewers/risk.md)
+- [`reviewers/standards.md`](reviewers/standards.md)
+- [`reviewers/intent.md`](reviewers/intent.md)
+- [`reviewers/evidence.md`](reviewers/evidence.md)
+- [`reviewers/documentation.md`](reviewers/documentation.md)
+
+Each reviewer should follow its own purpose, boundary, rubric, and output expectations.
+The shared base finding shape is flexible:
+
+```markdown
+- **Severity**: error | warning | info
+  **Blocking**: yes | no
+  **Location**: <file, line, command, artifact, or none>
+  **Finding**: <specific issue>
+  **Why it matters**: <impact>
+  **Suggested fix**: <concrete next action, or none>
+```
+
+Reviewers may add dimension-specific fields where useful.
+Reviewers classify findings as blocking or non-blocking.
+The caller or user decides final disposition.
+
+Done when each applicable dimension has returned findings or a clear statement that the dimension does not apply.
+
+## 3. Run targeted checks when useful
+
+Run targeted checks when they are needed to assess a dimension.
+Prefer focused commands that clarify evidence, risk, or standards conformance.
+Do not turn review into a full external validation pipeline.
+If a full suite or expensive check is clearly needed, explain why before relying on it.
+
+Record commands and artifacts that materially influenced the review.
+Do not present unrun checks as evidence.
+
+Done when the review has enough evidence for its findings and limitations are stated honestly.
+
+## 4. Aggregate the structured review report
+
+Produce a structured review report, not a gate artifact and not a pass/fail verdict.
+Keep sections separate so one dimension does not mask another.
+Deduplicate exact duplicates only.
+Mention when separate dimensions independently flag the same issue.
+
+Use this report shape unless the selected change set calls for a small adaptation:
+
+```markdown
+## Reviewed change set
+
+<what was reviewed and how it was captured>
+
+## Risk
+
+<risk reviewer section>
+
+## Standards
+
+<standards reviewer section>
+
+## Intent
+
+<intent reviewer section>
+
+## Evidence
+
+<evidence reviewer section>
+
+## Documentation
+
+<documentation reviewer section>
+
+## Summary
+
+- Blocking findings: <count>
+- Non-blocking findings: <count>
+- Targeted checks run: <commands or none>
+- Evidence limitations: <limitations or none>
+```
+
+Do not invent a pass/fail verdict.
+Use blocking findings present or absent as the review's actionable summary.
+
+Done when the report states the reviewed change set, preserves every applicable dimension, and summarizes blocking status and evidence limitations.

deprecated/review/reviewers/documentation.md

@@ -0,0 +1,30 @@
+# Documentation reviewer
+
+Review only documentation consequences of the selected change set.
+Do not make Risk, Standards, Intent, or Evidence findings unless the issue directly affects documentation correctness.
+
+Look for user-facing, operator-facing, contributor-facing, and agent-facing documentation that should change because behavior, interfaces, commands, options, workflows, or constraints changed.
+Also look for stale documentation introduced or left behind by the change.
+Do not demand new documentation surfaces for every change.
+Prefer updating the existing owner of the fact when one is discoverable.
+
+Documentation findings may be non-blocking when the change is internal and no durable reader would be misled.
+They may be blocking when users, operators, future contributors, or agents would reasonably make a wrong decision from stale or missing documentation.
+
+## Output format
+
+```markdown
+## Documentation
+
+### Findings
+
+Use `No findings.` when this reviewer has no findings.
+
+- **Severity**: <error|warning|info>
+  **Blocking**: <yes|no>
+  **Documentation owner**: <file, artifact, or none known>
+  **Location**: <file, line, command, artifact, or none>
+  **Finding**: <specific issue>
+  **Why it matters**: <reader impact>
+  **Suggested fix**: <concrete next action, or none>
+```

deprecated/review/reviewers/evidence.md

@@ -0,0 +1,38 @@
+# Evidence reviewer
+
+Review only whether the selected change set has convincing evidence.
+Do not make Risk, Standards, Intent, or Documentation findings unless the issue directly affects evidentiary value.
+
+Check tests, commands, artifacts, manual checks, and any evidence the change provides.
+You may recommend or run targeted checks when the orchestrating review context allows it.
+Do not present unrun checks as evidence.
+
+Reject source-grep pseudo-tests as proof of behavior.
+A test whose only evidence is matching implementation source text, tokens, lines, syntax, prompt phrases, regexes, AST shapes, or incidental snapshots does not prove behavior.
+Prefer evidence that demonstrates observable behavior, state, output, side effects, failure modes, or semantic meaning through a public or executable interface.
+
+For declarative artifacts, prefer invoking the real consumer or parsing into a typed or normalized semantic model.
+Reading file contents is legitimate when the file itself is the owned output or serialized contract under test.
+
+## Output format
+
+```markdown
+## Evidence
+
+Evidence checked:
+
+- <command, test, artifact, or none>
+
+### Findings
+
+Use `No findings.` when this reviewer has no findings.
+
+- **Severity**: <error|warning|info>
+  **Blocking**: <yes|no>
+  **Evidence checked**: <command, test, artifact, or none>
+  **Evidence gap**: <what remains unproven, or none>
+  **Location**: <file, line, command, artifact, or none>
+  **Finding**: <specific issue>
+  **Why it matters**: <trust or verification impact>
+  **Suggested fix**: <concrete next action, or none>
+```

deprecated/review/reviewers/intent.md

@@ -0,0 +1,33 @@
+# Intent reviewer
+
+Review only whether the selected change set satisfies the apparent intent.
+Do not make Risk, Standards, Evidence, or Documentation findings unless the issue directly changes intent fidelity.
+
+Use the clearest available intent source from context.
+Possible sources include an implementation task artifact, issue, spec, direct request, PR description, branch context, commit messages, or conversation context.
+Do not invent requirements.
+When intent is inferred rather than explicit, say so and treat it with appropriate caution.
+
+Look for missing requested behavior, partial implementation, behavior outside the selected scope, and implementations that appear to satisfy wording while violating the underlying request.
+Do not require remote branch, PR, or CI outcomes when another workflow step owns those outcomes.
+
+## Output format
+
+```markdown
+## Intent
+
+Intent source: <source or none>
+Intent confidence: <explicit|inferred|unavailable>
+
+### Findings
+
+Use `No findings.` when this reviewer has no findings.
+
+- **Severity**: <error|warning|info>
+  **Blocking**: <yes|no>
+  **Intent source**: <task, spec, issue, request, branch context, or none>
+  **Location**: <file, line, command, artifact, or none>
+  **Finding**: <specific issue>
+  **Why it matters**: <intent or correctness impact>
+  **Suggested fix**: <concrete next action, or none>
+```

deprecated/review/reviewers/risk.md

@@ -0,0 +1,46 @@
+# Risk reviewer
+
+Review only risk.
+Do not make Standards, Intent, Evidence, or Documentation findings unless the issue directly changes the risk assessment.
+
+Assess how much attention the selected change set warrants before handoff.
+Use the worst-factor-wins rubric from the old local review workflow.
+Rate each factor Low, Medium, or High with a concise reason:
+
+- Blast radius.
+- Reversibility.
+- Test coverage.
+- Sensitive domain.
+- Size and complexity.
+- Runtime criticality.
+
+Overall risk is the highest factor.
+Risk alone need not block.
+Missing evidence for a risky change may be blocking when a future reader should not trust the handoff without more proof.
+
+## Output format
+
+```markdown
+## Risk
+
+**Overall: <LOW|MEDIUM|HIGH>**
+
+- Blast radius: <rating> — <reason>
+- Reversibility: <rating> — <reason>
+- Test coverage: <rating> — <reason>
+- Sensitive domain: <rating> — <reason>
+- Size and complexity: <rating> — <reason>
+- Runtime criticality: <rating> — <reason>
+
+### Findings
+
+Use `No findings.` when this reviewer has no findings.
+
+- **Severity**: <error|warning|info>
+  **Blocking**: <yes|no>
+  **Risk factor**: <factor or none>
+  **Location**: <file, line, command, artifact, or none>
+  **Finding**: <specific issue>
+  **Why it matters**: <risk impact>
+  **Suggested fix**: <concrete next action, or none>
+```

deprecated/review/reviewers/standards.md

@@ -0,0 +1,43 @@
+# Standards reviewer
+
+Review only repository standards and maintainability.
+Do not make Risk, Intent, Evidence, or Documentation findings unless the issue directly affects standards conformance.
+
+Use repository instructions and discovered standards sources such as `AGENTS.md`, `CONTRIBUTING.md`, coding standards, or nearby conventions.
+When documented standards conflict with generic advice, the repository standard wins.
+
+Also apply this smell baseline when tooling or project standards do not already cover the issue:
+
+- Mysterious Name.
+- Duplicated Code.
+- Feature Envy.
+- Data Clumps.
+- Primitive Obsession.
+- Repeated Switches.
+- Shotgun Surgery.
+- Divergent Change.
+- Speculative Generality.
+- Message Chains.
+- Middle Man.
+- Refused Bequest.
+
+Treat smell findings as judgment calls, not automatic hard violations.
+Skip anything deterministic tooling already enforces unless the current review evidence shows the tool is not being run.
+
+## Output format
+
+```markdown
+## Standards
+
+### Findings
+
+Use `No findings.` when this reviewer has no findings.
+
+- **Severity**: <error|warning|info>
+  **Blocking**: <yes|no>
+  **Standard source**: <file and rule, smell baseline, or convention>
+  **Location**: <file, line, command, artifact, or none>
+  **Finding**: <specific issue>
+  **Why it matters**: <maintainability or standards impact>
+  **Suggested fix**: <concrete next action, or none>
+```

deprecated/slice/SKILL.md

@@ -0,0 +1,167 @@
+---
+name: slice
+description: Turn a settled plan, spec, conversation, or artifact into AI-artifacts implementation tasks for tracer-bullet slices. Run deliberately as /skill:slice when the user asks to slice work.
+disable-model-invocation: true
+---
+
+# slice
+
+Turn settled source material into implementation-ready task artifacts.
+Use this when the user asks to slice a plan, spec, conversation, or artifact into agent-grabbable implementation work.
+Do not use this to resolve planning fog.
+If the source contains unresolved decisions, report them instead of inventing implementation slices.
+
+`slice` writes AI-artifacts `task/implementation` artifacts for implementation slices.
+It does not write legacy `.claude/tasks/` files.
+
+## 1. Gather source material
+
+Work from the current conversation first.
+If the caller passes paths, artifact links, issue references, or URLs, read the referenced body and relevant comments or nearby artifact context before slicing.
+When source material names an artifact, use that artifact as the default provenance parent.
+When no source artifact exists, use `parent: null` unless the destination's artifact rules require a parent.
+
+Explore the codebase when the current implementation state is not already understood.
+Use the project's established vocabulary and respect relevant ADRs, context artifacts, and repository instructions.
+Look for prefactoring that makes the change easier before slicing the behavior.
+
+Done when the source, project context, and default parent artifact are known.
+
+## 2. Resolve the artifact destination
+
+Resolve the destination before naming files.
+Use an explicitly supplied destination directory exactly.
+Otherwise, default to `$(xdg-user-dir DOCUMENTS)/ai-artifacts/projects/<project>` when the AI-artifacts vault is available, where `<project>` is the lowercase basename of the current working directory.
+If that vault is unavailable, fall back to `./docs` in the current project.
+Create the destination directory only when a new artifact requires it.
+Read the destination's `AGENTS.md` before any artifact write.
+
+Follow the destination's filename, identifier, slug, frontmatter, and wikilink conventions.
+The default implementation task artifact type is `implementation-task`.
+The minimum implementation task contract is:
+
+```markdown
+---
+status: open
+parent: "[[<source-artifact>]]"
+blocked-by: []
+claimed-by: null
+claimed-at: null
+tags:
+  - task/implementation
+---
+
+# <task name>
+
+## Question
+
+<one precise implementation action sized to one agent session>
+```
+
+Use `parent: null` when no earlier artifact directly caused the task.
+Do not create claims.
+Tasks start open and unclaimed.
+
+Done when the destination and artifact conventions are known.
+
+## 3. Draft slices
+
+Break the work into tracer-bullet slices.
+Each normal slice must deliver a narrow complete path through every layer the change requires.
+Do not create horizontal layer-only slices.
+Reject any proposed slice whose title or delivered behavior is only parsing, only schema, only API, only UI, only tests, or only documentation when those layers are part of one user-visible change.
+For a small feature, one slice is usually correct because parsing, behavior, tests, and documentation belong in the same coherent commit.
+A completed slice must be demoable or verifiable on its own.
+A slice should make sense as one coherent commit.
+Put prefactoring slices before behavior slices that depend on them.
+
+Record blocking edges while drafting.
+Use blockers only for work that genuinely gates the slice.
+A slice with no blockers can start immediately.
+Use `parent` for provenance and `blocked-by` for prerequisites.
+
+Use the wide-refactor exception when a single mechanical change has a blast radius that prevents any vertical slice from landing green.
+Sequence that work as expand, migration batches, and contract.
+The expand slice adds the new form beside the old so nothing breaks.
+Each migration batch is sized by blast radius and is blocked by the expand slice.
+The contract slice removes the old form and is blocked by every migration batch.
+When migration batches cannot stay green alone, keep the sequence but state the integration-branch constraint and add a final integrate-and-verify slice.
+
+Done when every currently implementable slice has a title, blockers, delivered behavior, acceptance criteria, and any needed handoff notes.
+
+## 4. Confirm implementability
+
+Use implementation tasks when an agent can complete and verify the slice without live human input.
+When execution or validation depends on the user before implementation can proceed, report the human dependency instead of writing an agent-grabbable task.
+Examples include subjective UI judgment, physical device checks, unavailable credentials, external account approval, or behavior only the human can confirm.
+Do not block a task merely because it is important or risky.
+Make any required human involvement explicit in the proposed breakdown.
+
+If slicing reveals a precise unresolved planning question, do not disguise it as an implementation task.
+Report it and stop, unless the caller asks for follow-up research, prototyping, or grilling.
+
+Done when each proposed slice is implementable by an agent or its human dependency is explicit.
+
+## 5. Review before writing
+
+Present the proposed breakdown and wait for approval unless the caller explicitly asks for noninteractive output.
+For each slice show exactly this review shape:
+
+```markdown
+1. **Title**: <proposed task title>
+   **Blocked by**: <proposed blockers, or None>
+   **What it delivers**: <end-to-end behavior or implementation result>
+   **Acceptance criteria**:
+   - <observable completion check>
+```
+
+Ask the user whether the granularity feels right, whether the blocking edges are correct, and whether any slices should be merged or split.
+Iterate until the breakdown is approved.
+
+In explicitly noninteractive mode, write the best breakdown and record any assumptions in `## Implementation Notes`.
+
+Done when the proposed slices are approved or noninteractive assumptions are explicit.
+
+## 6. Write task artifacts
+
+Allocate filenames and identifiers according to the destination convention.
+Create one implementation task artifact per approved slice.
+Use the destination's wikilink style when referring to artifacts.
+Never refer to a task by a bare identifier, filename, or slug in user-facing text.
+
+Each task body should use this shape:
+
+```markdown
+# <task name>
+
+## Question
+
+<one precise implementation action sized to one agent session>
+
+## What to build
+
+<concise end-to-end behavior or implementation result, not a layer-by-layer checklist>
+
+## Acceptance criteria
+
+- [ ] <observable criterion>
+
+## Implementation Notes
+
+<concise handoff guidance when useful>
+```
+
+Keep `## Implementation Notes` empty when no guidance earns its place.
+Later implementing agents may append execution notes, verification results, and reasons for deliberately dropped criteria.
+Avoid brittle file paths and code snippets unless a prototype or prior decision snippet encodes the decision more precisely than prose can.
+
+If the destination uses identifier allocation and concurrent writes caused duplicate identifiers or filenames, preserve pre-existing artifacts, rename current outputs, update wikilinks, and advance the counter as needed.
+
+Done when every approved slice has exactly one open, unclaimed implementation task artifact.
+
+## 7. Report
+
+Report the created task artifacts by title using the destination's link style.
+Mention any assumptions, unresolved planning questions, human-dependent validation, or immediately actionable unblocked tasks.
+
+Done when the user can choose an implementation task.

deprecated/subagents/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: subagents
+description: Delegate isolated work through Pi subagent tools. Use when a workflow needs an independent worker, fresh context, parallel reviewers, or hidden role separation.
+disable-model-invocation: true
+---
+
+# subagents
+
+## 1. Confirm support
+
+Prefer tool calls when the current runtime exposes them.
+The supported tool names are `subagent_spawn`, `subagent_batch`, `subagent_list`, `subagent_status`, `subagent_result`, and `subagent_cancel`.
+
+If these tools are unavailable, do not pretend that an in-process role switch is a subagent.
+State that Pi subagent tools are unavailable in the current runtime.
+Do not perform the delegated subagent work in-process.
+
+Done when the run has a supported subagent tool path.
+
+## 2. Prepare a bounded prompt
+
+Give each subagent a self-contained prompt.
+Include the role, task, repository path, relevant files or artifacts, constraints, and expected output shape.
+Do not expose private planning state that the workflow is trying to isolate.
+For test-driven development, send one behavior at a time rather than a backlog.
+For review, send one review dimension at a time unless batching independent dimensions.
+
+Use `context: "independent"` for a fresh worker by default.
+Use `context: "fork"` only when the child intentionally needs the parent transcript as starting context.
+Choose named agents only when the project has configured them.
+Do not invent named agents as part of the delegation.
+
+Done when the prompt is narrow enough that the subagent can complete without sharing hidden state or requiring follow-up orchestration.
+
+## 3. Spawn and track workers
+
+Use `subagent_spawn` for one worker.
+Use `subagent_batch` when several independent workers can run in parallel.
+Both spawn tools return before the child work is complete.
+Record accepted child ids and per-entry failures.
+Use `subagent_list` or `subagent_status` to track lifecycle when needed.
+Use `subagent_result` to retrieve completion output.
+Use `subagent_cancel` for stale or no-longer-needed workers.
+
+Do not claim the delegated work is complete until every required child result is available or a failed child has an explicit disposition.
+Treat `queued`, `starting`, `running`, and `settling` as incomplete states.
+Treat `failed`, `cancelled`, `timed_out`, and `orphaned` as failures unless the caller explicitly accepts the missing result.
+
+Done when every required worker result has been collected or every missing result has a stated disposition.
+
+## 4. Integrate results
+
+Use subagent output as evidence, not as an unquestioned command.
+Preserve which child produced each material finding.
+When subagents disagree, report the disagreement rather than averaging it away.
+When a subagent result changes implementation direction, verify the relevant facts in the parent context before editing code.
+
+Done when the parent has integrated child results into the caller workflow with provenance and limitations visible.

deprecated/test-driven-development/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: test-driven-development
+description: Drive red-green-refactor implementation with tests written by someone other than the implementation agent, using public behavior and independent expected values.
+---
+
+# test-driven-development
+
+Use test-driven development as process discipline for behavior-bearing changes.
+The result is working behavior plus useful tests, not a separate report artifact.
+
+## 1. Establish roles and behavior backlog
+
+Name the two functional roles before writing tests.
+The implementation agent changes production code and drives the loop.
+The test writer writes and edits tests.
+Tests are always written by someone other than the agent doing implementation.
+
+Launch an independent test writer through whatever real context boundary the current harness provides.
+A separate agent, worker, subprocess, or documented headless session is sufficient when it cannot see the implementation agent's private backlog.
+If no real context boundary is available, stop before writing tests and report that test-driven development cannot be completed in the current runtime.
+Do not replace the independent test writer with an in-process role switch.
+Do not silently skip the independent-test-writer requirement.
+
+The implementation agent may keep a private behavior backlog.
+Keep that backlog isolated from the test writer.
+The test writer receives one behavior at a time, not the whole backlog.
+
+Done when roles are explicit and the implementation agent has the next behavior ready without exposing the whole backlog to the test writer.
+
+## 2. Choose the public seam and source of truth
+
+Test public behavior through the interface the code exposes or the task requires.
+When the seam is unclear, identify the smallest public seam that can prove the behavior.
+Do not test internals just to make RED easy.
+
+Each test needs an independent source of truth for expected values.
+Acceptable sources include a spec, task, intent excerpt, worked example, known-good literal, existing behavior being preserved, user clarification, or external standard.
+The implementation agent's derived computation is not enough.
+
+Done when the next behavior has a public seam, enough context for the test writer, and an independent expected-value source.
+
+## 3. Run one red-green cycle
+
+Give the test writer exactly one behavior, the public seam and context, the independent expected-value source, and any relevant project test conventions.
+The test writer writes or edits one test for that behavior and confirms it fails for the intended reason.
+A failing test should fail because the behavior is missing or wrong, not because of import, syntax, fixture, or collection errors.
+
+The implementation agent writes the minimal production code needed to pass that test.
+The implementation agent must not edit test-writer-authored tests.
+If the test has a mechanical defect, send the error back to the test writer.
+If the implementation agent believes the test asserts the wrong semantics, pause for user or intent clarification.
+
+Done when one behavior has a meaningful failing test and then passes through production-code changes made by the implementation agent.
+
+## 4. Repeat behavior by behavior
+
+Repeat the red-green cycle one behavior at a time.
+Do not bulk-write tests before implementation.
+Do not let the test writer see the behavior backlog.
+Do not add speculative behavior while making the current test pass.
+
+Run focused verification as each behavior lands.
+Use broader verification when the repository or change warrants it.
+
+Done when every selected behavior has passed through the one-behavior red-green loop or has been deliberately deferred by the implementation agent's judgment.
+
+## 5. Refactor only after green
+
+Never refactor while RED.
+After tests pass, the implementation agent may refactor production code.
+Refactoring means changing code structure without changing externally observable behavior.
+
+The test writer updates tests only for deliberate public seam changes or test defects.
+A test failure during refactoring normally means production behavior broke.
+Fix production code unless the public seam changed deliberately.
+
+Done when refactoring, if any, is complete and the relevant tests remain green.