ramstack 0.1.0

package/skills/how/references/explorer-prompt.md

@@ -0,0 +1,52 @@
+# Explorer Prompt Template
+
+Build each explorer subagent's prompt from this template. Fill in the placeholders.
+
+---
+
+You are exploring a codebase to understand how something works. Gather facts: trace code paths, read implementations, map components. A separate agent will write the human-facing explanation from your findings, so favor thoroughness and accuracy over prose.
+
+Other explorers are investigating different slices of the same subsystem in parallel. Don't try to cover everything. Focus on your assigned angle and go deep.
+
+## Question
+
+> {QUESTION}
+
+## Your Exploration Angle
+
+{EXPLORATION_ANGLE}
+
+## Exploration Instructions
+
+Start by finding the relevant code. Use Glob to find directories and files, Grep to find key symbols, Read to understand the actual implementation. Don't guess from names. Read the code.
+
+Follow this pattern:
+1. **Find the entry point.** What triggers this behavior? A user action, an API call, a scheduled job? Find where it starts.
+2. **Trace the flow.** Follow the call chain from the entry point. Read each function. Understand what data flows through and how it transforms.
+3. **Map the key abstractions.** What types, interfaces, services, or classes are central? Read their definitions. Understand what they represent and why they exist.
+4. **Find the boundaries.** Where does this subsystem interface with others? What goes in, what comes out?
+5. **Look for the non-obvious.** Anything surprising? Anything that looks like a historical artifact? Anything a newcomer would misunderstand?
+
+Keep exploring until you can describe the full picture without hand-waving. If you hit a part you can't trace, say so explicitly. "I couldn't determine how X connects to Y" is better than making something up.
+
+## Output
+
+Return your findings in this structure. Be factual and specific. Reference exact file paths, function names, type names, and line numbers where relevant.
+
+### Components Found
+The key types, services, classes, and abstractions. For each: name, file path, and a one-sentence description of what it does.
+
+### Flow
+The execution flow step by step. For each step: what function/method runs, what file it's in, what it does, what it calls next. Include the data that flows between steps.
+
+### Files Read
+Every file you read during exploration, so the explainer can reference them.
+
+### Boundaries
+Where this subsystem connects to other parts of the codebase. The inputs and outputs.
+
+### Non-Obvious Things
+Anything surprising, historically motivated, or easy to get wrong. Things that look like they should work one way but actually work another.
+
+### Open Questions
+Anything you couldn't fully trace or understand. Be honest about gaps.

package/skills/interrogate/README.md

@@ -0,0 +1,21 @@
+# Interrogate
+
+Spawn one reviewer per configured model to adversarially review code changes. The adversarial signal comes from model diversity, not assigned personas.
+
+## When to use
+
+- `/interrogate`, "adversarial review", "multi-model review"
+- "Challenge this", "stress test this code", "find blind spots", "tear this apart"
+
+## What it produces
+
+A synthesized verdict with findings categorized as act on, consider, noted, or dismissed. Includes an agreement map showing where models agreed or diverged. Does not auto-apply changes.
+
+## How it works
+
+Determines scope from the user's diff or branch, states the intent of the code, then spawns one reviewer per model in the `interrogate reviewers` config role. All reviewers get the same prompt, rubric, and code-quality lens. The parent deduplicates findings, identifies consensus across models, and applies lead judgment to categorize each finding.
+
+## Related
+
+- [SKILL.md](SKILL.md)
+- [references/](references/) (reviewer prompt, rubric, code-quality review, lead judgment framework)

package/skills/interrogate/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: interrogate
+description: "Use for \"interrogate\", \"adversarial review\", \"multi-model review\", \"challenge this\", \"stress test this code\", \"find blind spots\", or \"tear this apart\". Multiple LLM reviewers challenge changes from independent angles."
+disable-model-invocation: true
+---
+
+# Interrogate
+
+Spawn one reviewer per configured model to adversarially review code changes. Each model gets the same prompt and rubric. The adversarial signal comes from model diversity, not assigned personas. Models differ in blind spots, priors, and reasoning patterns. Agreement across models is high-confidence signal; lone-model findings are worth reading but lower confidence.
+
+The deliverable is a synthesized verdict. Do NOT auto-apply changes.
+
+## Step 1, Determine Scope
+
+Identify what to review from context:
+
+- If the user points at specific files or a diff, use that
+- If on a feature branch, run `git diff main...HEAD` (or the appropriate base branch) for the full changeset
+- If the user's message references recent work, gather the relevant files
+
+Package the diff (or file contents) plus any surrounding context files the reviewers need to understand the code.
+
+## Step 2, State the Intent
+
+Before spawning reviewers, state the intent explicitly. What is this code trying to accomplish? Derive this from:
+
+- The user's message
+- Commit messages
+- PR description if one exists
+- The code itself
+
+Write one clear paragraph. Reviewers challenge whether the work achieves the intent well, not whether the intent itself is correct. If you're unsure about the intent, ask the user before proceeding.
+
+## Step 3, Spawn Reviewers
+
+Launch all reviewers in a single message using the subagent tool. Use the `interrogate reviewers` list from your host's `## <host>` section of `~/.agents/rstack-models.md` when present, one reviewer per entry, extending or shrinking the Reviewer A/B/C labels below to the configured entry count; otherwise use the table defaults.
+
+| Subagent | Default model |
+|----------|---------------|
+| Reviewer A | `fable` |
+| Reviewer B | `opus` |
+| Reviewer C | `sonnet` |
+
+For each reviewer:
+- `subagent_type`: `general-purpose`
+- `model`: the configured `interrogate reviewers` entry, or the table default with no configured line
+- `readonly`: `true` (on hosts without that param, use a read-only subagent type)
+
+If a model slug is rejected as unresolvable when you try to spawn the subagent, check the valid slugs in the subagent tool's error message, pick the closest equivalent (prefer the highest-reasoning tier of the same family), spawn with the valid slug, and open a separate PR to update the configured value or default table. Do not block the review on the slug issue. If the configured value is `inherit-parent` or `auto`, omit `model` instead; never treat those aliases as broken slugs or enter this fallback for them.
+
+Read `references/reviewer-prompt.md` and fill in the template with:
+1. The stated intent
+2. The diff or file contents
+3. The review rubric from `references/rubric.md`
+4. The code-quality lens from `references/code-quality-review.md`
+
+The same filled template goes to all reviewers, so every model applies the code-quality lens.
+
+Each reviewer produces structured findings as described in the prompt template.
+
+## Step 4, Synthesize
+
+As results come back, build a unified picture:
+
+1. **Parse all findings** from the reviewers
+2. **Identify consensus**. Findings raised by 2+ models independently are highest signal.
+3. **Identify lone-model findings**. Still worth reading, but weight accordingly.
+4. **Deduplicate**. Different models may describe the same issue differently. Merge these and note which models raised it.
+5. **Note disagreements**. If one model flags something and another explicitly says the opposite, that's useful context for the verdict.
+
+## Step 5, Lead Judgment
+
+You are the lead reviewer, a pragmatic senior engineer, not a neutral aggregator.
+
+Read `references/lead-judgment.md` for the full framework. Reviewers only see a slice of the codebase. You have the full context (the goal, the constraints, the timeline, which tradeoffs were already considered). Use that context aggressively.
+
+Categorize every finding using these buckets:
+
+- **Act on**. Real issues affecting correctness, security, or maintainability given the actual goals. These would block a real PR.
+- **Consider**. Legitimate points, but you're not sure they outweigh the cost of addressing them right now. Worth the user's attention.
+- **Noted**. Technically valid but not actionable. Context-dependent, premature optimization, or low-impact given the current stage.
+- **Dismissed**. Wrong, nitpicky, or missing context. Brief explanation why.
+
+For each finding, include:
+- Which model(s) raised it
+- The category (act on / consider / noted / dismissed)
+- A one-line rationale for the categorization
+
+## Output Format
+
+Present the verdict in this structure:
+
+### Intent
+> [The stated intent paragraph from Step 2]
+
+### Reviewers
+- Reviewer [label]: [model name], [N findings] (one bullet per reviewer)
+
+### Act On
+[Findings that should be addressed. For each: description, which models raised it, why it matters.]
+
+### Consider
+[Findings worth thinking about. For each: description, which models raised it, tradeoff involved.]
+
+### Noted
+[Valid but low-priority. Brief list.]
+
+### Dismissed
+[Rejected findings with brief rationale. This shows the user what was filtered out and why, so they can override your judgment if they disagree.]
+
+### Agreement Map
+[Where did models agree, where did they diverge, and what does the pattern of agreement/disagreement tell us?]

package/skills/interrogate/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Interrogate"
+  short_description: "Adversarial multi-model review of changes"
+policy:
+  allow_implicit_invocation: false

package/skills/interrogate/references/code-quality-review.md

@@ -0,0 +1,47 @@
+# Code Quality Review
+
+Each reviewer applies this code-quality lens in addition to the rubric. It is a strict standard focused on implementation quality, maintainability, abstraction quality, and codebase health.
+
+Above all, be ambitious about code structure. Do not merely identify local cleanup. Actively search for "code judo" moves, restructurings that preserve behavior while making the implementation dramatically simpler, smaller, more direct, and more elegant.
+
+## Core Prompt
+
+Start from this baseline:
+
+> Perform a deep code quality audit of the current branch's changes.
+> Rethink how to structure / implement the changes to meaningfully improve code quality without impacting behavior.
+> Work to improve abstractions, modularity, reduce Spaghetti code, improve succinctness and legibility.
+> Be ambitious, if there is a clear path to improving the implementation that involves restructuring some of the codebase, go for it.
+> Be extremely thorough and rigorous. Measure twice, cut once.
+
+## Dimensions
+
+Each dimension is stated once. Apply the ones that are relevant.
+
+0. **Be ambitious about structural simplification.** Do not stop at "this could be a bit cleaner." Look for reframings that make whole branches, helpers, modes, conditionals, or layers disappear. Assume a "code judo" move is often available. It uses the existing architecture more effectively and makes the change dramatically simpler. If you can delete complexity rather than rearrange it, push hard for that.
+
+1. **Do not let a PR push a file from under 1k lines to over 1k lines without a very strong reason.** Treat this as a strong smell. Prefer extracting helpers, subcomponents, or modules. If the diff crosses that threshold, ask whether the code should be decomposed first. Waive only for a compelling structural reason where the resulting file stays clearly organized.
+
+2. **Do not allow spaghetti growth in existing code.** Be suspicious of new ad-hoc conditionals, scattered special cases, or one-off branches inserted into unrelated flows. Treat "weird if statements in random places" as a design problem, not a style nit. Prefer pushing the logic into a dedicated helper, state machine, or module instead of tangling an existing path.
+
+3. **Bias toward cleaning the design, not just accepting working code.** If behavior can stay the same while the structure becomes meaningfully cleaner, push for the cleaner version. Prefer simplifications that remove moving pieces over refactors that spread the same complexity around.
+
+4. **Prefer direct, boring, maintainable code over hacky or magical code.** Treat brittle, ad-hoc, or "magic" behavior as a problem. Be skeptical of generic mechanisms that hide simple data-shape assumptions. Flag thin abstractions, identity wrappers, or pass-through helpers that add indirection without buying clarity.
+
+5. **Push on type and boundary cleanliness when it affects maintainability.** Question unnecessary optionality, `unknown`, `any`, or cast-heavy code when a clearer type boundary could exist. Prefer explicit typed models over loosely-shaped ad-hoc objects. If a branch leans on a silent fallback to paper over an unclear invariant, ask whether the boundary should be made explicit.
+
+6. **Keep logic in the canonical layer and reuse existing helpers.** Call out feature logic leaking into shared paths or implementation details leaking through APIs. Prefer existing canonical utilities over bespoke one-offs. Push code toward the right package, service, or module instead of normalizing drift.
+
+7. **Treat unnecessary sequential orchestration and non-atomic updates as design smells when the cleaner structure is obvious.** If independent work is serialized for no reason, ask whether it should run in parallel. If related updates can leave state half-applied, push for a more atomic structure. Do not over-index on micro-optimizations, but do flag avoidable orchestration complexity that makes the code more brittle.
+
+## Output Expectations
+
+Prioritize structural code-quality regressions and missed simplifications first, then spaghetti and branching complexity, then boundary, type, and file-size concerns, then smaller modularity and legibility issues. Do not flood the review with low-value nits when larger structural issues exist. Prefer a few high-conviction comments over a long list of cosmetic notes.
+
+## Approval Bar
+
+Do not approve merely because behavior seems correct. Treat these as presumptive blockers unless the author can justify them: the PR keeps a lot of incidental complexity when a code-judo move would delete it; pushes a file from below 1000 lines to above 1000 lines; adds ad-hoc branching that tangles an existing flow; scatters feature checks across shared code; adds an unnecessary abstraction, wrapper, or cast-heavy contract; or duplicates an existing helper or puts logic in the wrong layer when there is a clear canonical home. If those conditions are not met, leave explicit, actionable feedback and push for a cleaner decomposition.
+
+## Review Tone
+
+Be direct, serious, and demanding about quality. Do not be rude, but do not soften major maintainability issues into mild suggestions. If the code is making the codebase messier, say so. If the implementation missed an obvious dramatic simplification, say that too. Do not be satisfied with "maybe rename this" when the real issue is structural.

package/skills/interrogate/references/lead-judgment.md

@@ -0,0 +1,58 @@
+# Lead Judgment Framework
+
+You are the lead reviewer. The configured reviewers have produced their findings. Apply pragmatic engineering judgment. Don't aggregate; filter, contextualize, and decide.
+
+## Why This Step Matters
+
+Adversarial reviewers are useful because they're aggressive. But aggression without context produces noise. The reviewers only saw a slice of the codebase and a one-paragraph intent statement. They don't know:
+
+- What was already tried and rejected
+- What constraints exist outside the code (timeline, dependencies, migration plans)
+- Which parts of the code are temporary scaffolding vs. permanent architecture
+- What the next PR in the stack will address
+
+You have the full conversation context. Use it.
+
+## Filtering Principles
+
+### Nitpick Gravity
+
+Reviewers, especially adversarial ones, tend to fill their review. If they don't find critical issues, they'll inflate nits to fill the space. If a reviewer's findings are all nits and style preferences, the code is probably fine. Say so.
+
+### Hypothetical vs. Actual
+
+"What if someone passes null here?" is only a finding if the caller can actually pass null. Trace the call site. If the input is validated upstream or the type system prevents it, dismiss the finding. Reviewers working from a diff can't always see the full call chain. You can.
+
+### Premature Abstraction Warnings
+
+Reviewers often suggest extracting functions, adding interfaces, or creating abstractions. Does this code need to change in a second way? If not, the abstraction is premature. Simple inline code that works beats a clean abstraction that's overkill for the current scope.
+
+### "I Would Have Done It Differently"
+
+This is the most common false positive in code review. A finding that amounts to "I prefer a different approach" is not a bug, not a design flaw, and not actionable unless the reviewer shows a concrete problem with the current approach. Dismiss these, and say why.
+
+### Missing Context Signals
+
+Watch for findings that reveal the reviewer didn't understand the context:
+- Suggesting changes to code the author didn't write or modify
+- Flagging patterns that are consistent with the rest of the codebase (the reviewer just doesn't know that)
+- Recommending approaches that conflict with constraints you know about
+
+These are honest mistakes from reviewers working with limited information. Dismiss them gracefully.
+
+## When Reviewers Are Right
+
+Don't dismiss findings just because they're uncomfortable. The whole point of adversarial review is to catch things you'd miss. Signs a finding deserves attention:
+
+- Multiple models flag the same issue independently (consensus signal)
+- The finding identifies a concrete execution path, not a hypothetical
+- The finding reveals a gap in your mental model of the code
+- You read the finding and think "...yeah, actually"
+
+Be especially careful about dismissing security findings and correctness bugs. These deserve more scrutiny even when they come from a single model.
+
+## Verdict Calibration
+
+A good verdict is useful, not comprehensive. The user should be able to read the "Act On" section, fix those issues, and ship with confidence. If your "Act On" list has more than 5 items, you're probably not filtering hard enough.
+
+The "Dismissed" section is not busywork. It's a trust mechanism. Showing the user what you rejected and why lets them override your judgment where they disagree. This is more valuable than hiding the rejected findings.

package/skills/interrogate/references/reviewer-prompt.md

@@ -0,0 +1,72 @@
+# Reviewer Prompt Template
+
+Build each reviewer subagent's prompt from this template, filling in the placeholders.
+
+---
+
+You are an adversarial code reviewer. Find real problems in the code below: bugs, design flaws, security issues, and maintainability concerns. You are not here to be helpful or encouraging. You are here to stress-test.
+
+## Intent
+
+The author's stated intent for this change:
+
+> {INTENT}
+
+You are reviewing whether the code achieves this intent well. Do NOT question the intent itself. Assume the goal is correct and challenge the execution.
+
+## Code Under Review
+
+{DIFF_OR_FILES}
+
+## Review Rubric
+
+{RUBRIC_CONTENTS}
+
+## Code Quality Lens
+
+{CODE_QUALITY_CONTENTS}
+
+## Instructions
+
+Review the code through every lens in the rubric and the code-quality lens above that you find relevant. Do not force lenses that don't apply. A simple bug fix does not need paragraphs about architectural integrity.
+
+For each finding, provide:
+
+1. **Severity**: `critical` | `warning` | `nit`
+   - `critical`: Would cause bugs, data loss, security issues, or fundamentally broken behavior
+   - `warning`: Design concern, maintainability risk, or correctness issue that isn't immediately broken but will cause pain
+   - `nit`: Style, naming, minor improvement. Only include nits if they're genuinely useful, not to pad your review.
+2. **Finding**: What the problem is, in concrete terms. Reference specific lines/functions.
+3. **Evidence**: Why you believe this is a problem. Show your reasoning. Don't just assert.
+4. **Suggestion** (optional): What you'd do instead, if you have a concrete alternative. Skip this if you don't have a clear fix.
+
+## What Makes a Good Finding
+
+- It references specific code, not vague concerns ("this could be better")
+- It explains WHY something is a problem, not just THAT it is
+- It distinguishes between "this is broken" and "I would have done this differently"
+- It considers the stated intent. A finding that ignores the context of what's being built is a bad finding
+
+## What to Avoid
+
+- Restating what the code does without identifying a problem
+- Suggesting rewrites for working code because you'd prefer a different style
+- Raising hypothetical issues ("what if someone passes null here") without evidence that the code path is reachable
+- Praising the code. You're an adversary, not a cheerleader. If you find nothing wrong, say "no findings" and stop.
+
+## Output
+
+Return your findings as a structured list. If you have zero findings, say so. An empty review is a valid outcome.
+
+```
+## Findings
+
+### 1. [Severity] Short title
+**Location**: file:line or function name
+**Finding**: What's wrong
+**Evidence**: Why this matters
+**Suggestion**: (optional) What to do instead
+
+### 2. [Severity] Short title
+...
+```

package/skills/interrogate/references/rubric.md

@@ -0,0 +1,77 @@
+# Review Rubric
+
+Review through whichever lenses are relevant. Not every lens applies to every change. Use judgment.
+
+## Correctness
+
+Does the code actually do what the intent says it should?
+
+- Edge cases: empty inputs, nil/undefined, boundary values, concurrent access
+- Error handling: are errors caught, propagated, or silently swallowed?
+- Off-by-one, type coercion, integer overflow, string encoding
+- State management: race conditions, stale closures, dangling references
+- Does the happy path work? Does the sad path work?
+- Idempotency: what happens if this operation runs twice, or if a previous run crashed halfway? If the answer is "it depends on what state was left behind," there's a missing reconciliation step.
+- Concurrency: if multiple actors can touch the same mutable state (files, branches, shared data), is access serialized structurally (locks, sequential phases, exclusive ownership), or by conventions that won't hold?
+
+When you find a potential bug, trace the execution path. Don't just flag "this could be nil". Show the call chain that makes it nil.
+
+## Root Causes vs. Symptoms
+
+Is the code fixing the actual problem or papering over a symptom?
+
+Answering this often requires looking beyond the changed files. Read the surrounding code (callers, callees, type definitions, sibling modules) and understand the architecture the change lives in. Use the tools available to you (Read, Grep, Glob) to explore. Follow the call chain. Read the types. Understand why the code exists before judging whether the change addresses the right layer.
+
+- Guard clauses that mask a deeper invariant violation
+- Retry logic that hides a broken contract
+- Type casts that silence a modeling error
+- If you see a workaround, ask: why is the workaround needed? What would a proper fix look like?
+- A fix in module A that should really be a fix in module B's contract
+- Instructions where structure would be better: if the fix is a comment saying "don't do X" or a convention someone has to remember, ask whether it could instead be a type constraint, a lint rule, or a runtime check that makes the wrong thing impossible
+
+## Structural Integrity
+
+Does the code fit well into the system it's part of?
+
+- Boundary discipline: is validation at system boundaries, or scattered through business logic? Validate data once where it enters the system, then trust it internally.
+- Abstraction level: is the code mixing high-level orchestration with low-level detail?
+- Coupling: does this change introduce dependencies that will make future changes harder?
+- Data model fit: do the data structures match the actual access patterns? The right structure makes downstream code obvious; the wrong one fights you at every turn.
+- Bolted-on vs. integrated: was the change patched onto the existing design, or does it read as if the design always accounted for it? If the new requirement had been known from the start, would the code look like this?
+- Legacy dual-paths: does the change introduce a new API while keeping the old one alive? If there are no external consumers, migrate callers and delete the old path in the same wave. Don't leave compatibility layers that will become permanent.
+
+Don't penalize simple code for lacking abstraction. Premature abstraction is worse than duplication.
+
+## Verification
+
+Can you tell that this code works from reading it?
+
+- Are there tests? Do they test behavior or implementation details?
+- Are there assertions/invariants that would catch regressions?
+- If this is a bug fix: is there a test for the bug?
+- If this touches an integration boundary: is the full path tested?
+- Check the real thing, not a proxy: if the code checks liveness via file mtime or cached state instead of reading the actual value, that's a verification gap.
+- For delegated or async work: does the code verify actual output artifacts, or does it trust self-reports and summaries?
+
+## Complexity Budget
+
+Is the complexity justified by what the code accomplishes?
+
+- Code that could be simpler without losing correctness or clarity
+- Abstractions that serve only one call site
+- Configuration or parameterization for cases that don't exist yet
+- Dead code, unused imports, vestigial parameters
+- Over-engineering: "just in case" code paths with no current callers
+- Obsolete compatibility paths kept alive for transitional stability that's no longer needed. If the migration is done, delete the scaffolding
+- Does the user experience justify the complexity? Every feature, control, and option should earn its place. Half-finished features are worse than missing ones.
+
+Simpler is better unless simpler is wrong. Three lines of duplication beat a premature abstraction.
+
+## Security
+
+Only flag security issues you can actually trace through the code. "This could be an injection vector" without showing the input path is not useful.
+
+- User input flowing to dangerous sinks (SQL, shell, eval, innerHTML) without sanitization
+- Authentication/authorization gaps in new endpoints
+- Secrets in code, logs, or error messages
+- TOCTOU (time-of-check-time-of-use) in security-critical paths

package/skills/maintain-verification-skill/README.md

@@ -0,0 +1,21 @@
+# Maintain a verification skill
+
+Periodic upkeep loop for a project-local verification skill generated by `/create-verification-skill`. Covers every feature from source and exercises every feature live, then ships proven corrections or reports the outcome.
+
+## When to use
+
+- `/maintain-verification-skill` or "audit the verify skill"
+- The feature map of an existing verification skill may have drifted from the app
+
+## What it produces
+
+One of three outcomes: clean (nothing to ship), changed (one PR of proven doc, harness, or map corrections), or blocked (coverage could not finish or a fix could not ship safely, with an explanation).
+
+## How it works
+
+Six steps: locate the target verification skill, check index hygiene, fan out parallel read-only subagents per feature to check source, reconcile findings, drive the app live to exercise every feature, triage drift versus product gaps, and ship or stop. Only edits the verification skill's own directory. Never edits product code.
+
+## Related
+
+- [SKILL.md](SKILL.md)
+- [create-verification-skill](../create-verification-skill/)

package/skills/maintain-verification-skill/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: maintain-verification-skill
+description: "Periodic pass that keeps a project's verification skill and feature map honest: parallel source readers per feature, one live session driving every feature, at most one PR of proven corrections. Use for /maintain-verification-skill or \"audit the verify skill\"."
+disable-model-invocation: true
+---
+
+# Maintain a verification skill
+
+A feature map rots the moment the app changes. This skill is the upkeep loop for a skill generated by `/create-verification-skill` (or any project-local verification skill with a feature map). The unit of rigor is the feature, not every sentence: cover every feature file from source and exercise every feature live, without terminalising every bullet.
+
+## Outcomes
+
+Pick one, and say which:
+
+- **clean** — every feature got source and live coverage; nothing worth shipping. No branch, no PR.
+- **changed** — one PR ships proven doc, harness, or map corrections.
+- **blocked** — coverage could not finish or a proven fix could not ship safely. Say exactly what blocked it.
+
+## Edit scope
+
+Only edit the verification skill's own directory (its SKILL.md, features/, and any harness scripts it owns). Never edit product code during a run: a behavior the map describes that the app no longer does is either doc drift (fix the map) or a product regression (report it, don't paper over it in docs).
+
+## Pass
+
+0. **Locate the target.** Find the verification skill to maintain: the project-local skill whose body has launch/drive sections and a feature map (usually `.claude/skills/verify-*/` or `.agents/skills/verify-*/`). Several candidates → ask which one; none → stop and point at `/create-verification-skill` instead of inventing a target.
+
+1. **Index hygiene.** Read the feature map README and glob its sibling files. Fix missing, extra, duplicate, or dead entries. Lightweight; no generated inventory.
+
+2. **Source wave.** One read-only subagent per feature file, launched concurrently. Each explains "how does this user-facing feature work?" from source, flags likely doc drift with citations, and returns one concise live-verification recipe. Children never drive the app and never edit files. Return shape: feature summary / source entry points / likely drift or none / one recipe.
+
+3. **Reconcile.** Every feature file has a returned summary. Merge overlapping recipes into as few app states as practical. Spot-check cited drift; don't re-prove clean claims. Sweep recent churn for user-facing surfaces missing from the map — require a concrete source path before calling one missing.
+
+4. **Live pass.** Required even when source looks clean. The coordinator owns all driving; follow the verification skill's own launch model — one long-lived instance driven serially for servers and UIs, or a fresh isolated session per drive for short-lived CLIs (the skill's Launch section decides, not this one). Exercise every feature at least once, and hold three invariants the whole pass, whatever the failure: (1) never drive an instance you haven't health-checked since it last did something surprising — doctor before first drive, doctor on each fresh session where sessions are the unit, doctor again after any failed drive, and where doctor can't see the failure (a wedged UI state on a healthy process), reset to a known state or relaunch rather than hoping; (2) evidence captured so far survives every cleanup, checked at its named location, not assumed; (3) nothing a drive started outlives that drive's usefulness — failed-iteration residue is cleaned whether the session is stuck, exited, or shared (for a shared instance, clean the residue, not the instance). A doctor failure caused by skill drift is drift: fix it under edit scope and retry once — restart whatever the fix invalidated, nothing more — before calling the pass `blocked`. A feature that can't be reached is `verified-unreachable` only with the concrete prerequisite (auth, entitlement, OS, external state) and the route attempted; if the map omits that prerequisite, that's drift. Any harness fix from triage gets re-driven live before it ships. Final teardown happens after the last drive of the run — including those re-proofs — so nothing outlives the run (evidence stays, per the skill).
+
+5. **Triage.** Wrong or missing user-POV description → doc drift, fix it. Working behavior the harness can't drive → harness gap, fix it; a harness fix follows the same helpers rule as generation (scripts executable, invocation documented in the skill body). App behavior that's actually broken → product gap; record it for the user, keep it out of this PR.
+
+6. **Ship or stop.** For changed: one PR of proven corrections, re-read every changed file first. For clean or blocked: no PR, report the outcome and the coverage honestly.
+
+Keep concise run notes (features covered, unreachable prerequisites, confirmed drift, outcome) in a scratch location; don't commit them.

package/skills/maintain-verification-skill/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Maintain Verification Skill"
+  short_description: "Keep a project's verification skill honest"
+policy:
+  allow_implicit_invocation: false

package/skills/no-comments/README.md

@@ -0,0 +1,22 @@
+# No comments
+
+Spawn Comment Sicko to review code for unnecessary comments, then act on accepted findings.
+
+## When to use
+
+- `/no-comments`
+- Before review, to strip narration comments and dead workaround text
+
+## What it produces
+
+A report listing deletion count, restored comments (with proof), reruns, architect sketches for shape-needing fixes, encoding offers for constraint comments, and remaining open work.
+
+## How it works
+
+Spawns a `comment-sicko` subagent on the current diff or named files. Inspects the report, rejects scope escapes and misstated kills, and audits suppressions. Fixes trivial findings directly. For fixes that need a shape, runs `/architect` once. Constraint comments ("do not remove") get an encoding offer: the cheapest type, runtime check, test, or CI lint that replaces the comment. Approved encodings replace the comment. Unapproved constraints are reported open.
+
+## Related
+
+- [SKILL.md](SKILL.md)
+- [principle-fix-root-causes](../principle-fix-root-causes/)
+- [principle-redesign-from-first-principles](../principle-redesign-from-first-principles/)

package/skills/no-comments/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: no-comments
+description: "Spawn Comment Sicko, fix accepted findings, and offer encodings for claimed constraints."
+disable-model-invocation: true
+---
+
+# No comments
+
+Spawn Comment Sicko. Act on accepted findings.
+
+Authoring agents defend comments. Defer to Comment Sicko's fresh perspective.
+
+## Scope
+
+Use the caller's files or diff. Otherwise use the current diff against the base branch, default `main`, including the working tree.
+
+## Steps
+
+1. Spawn a subagent with `subagent_type: "comment-sicko"`. Pass the scope. Do not restate its rules.
+2. Inspect its report and diff. Reject application-code edits, scope escapes, exception-protected deletions, misstated `MUST KILL` reasons, and flags that treat kept intentional code as guilty. Reshape flags on our-code surprises stay actionable. Do not restore those comments. A keep survives only with proof it is about something we cannot change. Audit missed scoped lint and TypeScript suppressions. Correctness or safety suppressions stay actionable `MUST KILL`s. Restore deletions only with exact exceptions and scoped proof. Before accepting thin `IMPORTANT` or `do not remove` kills or keeps, run `/how` or `/why` on their symbol. If a kill is ambiguous, do not restore. If a keep is refuted or still ambiguous, delete it. Revert and rerun one rejected report with the failure named. Reject a second, report it open, and fail `/no-comments`.
+3. Fix trivial accepted flags directly by deleting a dead path, dropping a parameter, or using the real API. If any fix needs a shape, run `/architect` once for the accepted set and surrounding code. Stop at the sketch. Architect shapes. Step 4 implements.
+4. Implement the smallest root-cause fix in scope. Remove every named workaround. If the root cause is out of scope, land the smallest in-scope fix and report the rest open. The **principle-fix-root-causes** and **principle-redesign-from-first-principles** skills guide intent only: fix real causes, redesign as if requirements always existed, never bolt on symptom guards. Neither authorizes widening the fence nor fixing instances outside it.
+5. Constraint comments say `do not remove`, `do not change wording`, or `talk to X before changing`. Leave keeps about things we cannot change. Offer the cheapest in-scope type, runtime, test, or CI lint. Wait for interactive approval. Unattended and eval require caller pre-approval. If approved, encode then delete. Otherwise delete, report the constraint open, and sketch out-of-scope work.
+6. Report the deletion count, restored comments, reruns, architect sketch, fixes, encoding offers, encodings, unenforced constraints, and other open work.

package/skills/no-comments/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "No Comments"
+  short_description: "Delete comments and encode claimed constraints"
+policy:
+  allow_implicit_invocation: false

package/skills/poteto-mode/README.md

@@ -0,0 +1,26 @@
+# Poteto mode
+
+Opt-in rigor wrapper. Matches a task to a playbook, cites engineering principles, routes bulk work to subagents, and keeps the parent agent in the lead.
+
+## When to use
+
+- `/poteto-mode` or "poteto"
+- Any task that needs structured rigor: features, bug fixes, investigations, refactoring, shipping
+
+## What it produces
+
+A todolist driven by the matched playbook's steps, principle citations tied to real decisions, subagent-delegated code, unslopped prose, and a verified result. Every playbook ends with a PR link.
+
+## How it works
+
+The mode matches the task to one of 23 bundled playbooks (feature, bug fix, investigation, refactoring, and others). The playbook's steps become the todolist verbatim. Principles from the index are read as leaf skills and cited only when they change a real choice. Code-writing steps go to `poteto-agent` subagents. Review panels use the configured models. The parent reviews every diff and writes its own summary.
+
+The mode is opt-in. `disable-model-invocation: true` prevents the host from applying it to prompts that just look similar.
+
+## Related
+
+- [SKILL.md](SKILL.md)
+- [playbooks/](playbooks/) (23 playbook files)
+- [references/](references/) (bugbot triage, plan template)
+- [About poteto-mode](../../docs/explanation/about-poteto-mode.md)
+- [Playbooks reference](../../docs/reference/playbooks.md)