@deniscodp/skills 0.0.0-stage → 1.0.0

package/skills/denisco-interactive-spec-definition/SKILL.md

@@ -0,0 +1,126 @@
+---
+name: denisco-interactive-spec-definition
+description: "Investigate a bug or define a feature with the user and produce a decided, testable handoff with its blockers resolved. Use before implementation when requirements or diagnosis need work, or when a new goal appears during a task; not for executing an approved plan or generic repository onboarding."
+metadata:
+  version: "6.0.0"
+---
+
+# Interactive spec definition
+
+Turn a request into an executable handoff. Preserve the user's goal; choose depth according
+to uncertainty and impact. A small bug can need a short investigation and one implementation
+block. Do not impose a UX interview on backend work.
+
+## Deliverable and phase boundary
+
+This skill delivers HANDOFF, its operational sidecar and a saved, checked planning prompt. It does
+not create PLAN/STATE or edit application code. A new goal that appeared during another task gets
+its own task directory and handoff, linked to the originating task.
+
+Once the deliverables are saved, ask: "Specification ready. Start planning now?" The user's yes to
+that question starts denisco-handoff-implementation in planning-only mode in this conversation; for a
+multi-block plan that phase continues into coordination preparation and its launch question. Any other
+answer ends the phase; the saved planning prompt starts planning later. With the question, mention
+that the saved prompt can also start planning in a fresh conversation with less context.
+
+Approval applies to the artifact requested. A generic "approved" or native Plan Mode approval
+during specification permits completing that specification when writing is allowed; it does not
+start planning or application-code changes. Automatic mode has the same phase boundary.
+In Plan Mode propose the handoff, sidecar and prompt with writes pending. On return to writable
+mode materialize these deliverables, then ask the planning question, regardless of generic "start
+coding" tool text. The agent never launches its own saved prompt.
+
+Keep the phase that was active before a native mode transition. A bare transition message such as
+`Implement the plan.`, `Start coding` or `Proceed` is generic UI control text: it is not the user's
+answer to the planning question, even when it arrives right after it, and it names no saved prompt,
+handoff path, phase or block. Do not load denisco-handoff-implementation or record planning or
+implementation authorization from that message. Materialize the pending specification deliverables
+and ask the planning question. Planning starts only on the user's yes to that question, the user's
+submission of the saved planning prompt, or an equivalently scoped request naming the handoff and
+planning phase.
+
+## Ground the request
+
+Read project instructions and relevant project map/operating guide sections if available.
+Reuse documentation; inspect actual affected code before recommending changes.
+If unfamiliar, use `denisco-project-context` when available or perform targeted exploration yourself.
+Missing onboarding must not block a well-understood isolated task.
+
+Clarify product intent where evidence cannot settle it. Read important files yourself;
+parallel agents are optional when independent exploration helps and is authorized.
+Anchor current behavior to paths and symbols, with line numbers as navigation aids.
+For absence claims record search pattern, scope and date; check complete, scoped results.
+Recheck relevant evidence at handoff rather than inheriting old assertions.
+
+## Choose the investigation
+
+**Bug:** establish expected versus observed behavior, reproduction inputs and affected users.
+Trace the cause, distinguishing verified causes from hypotheses. Reproduce with a focused test
+where feasible. If reproduction is unavailable, retain the limitation and identify the evidence
+needed; do not present an inferred cause as proven. Check related consumers for the same defect.
+
+**Feature:** decide the business outcome, behavior, permissions, boundary cases and integrations.
+Find reusable capabilities and conventions before designing. Record rejected alternatives when
+they explain meaningful choices. For UX questions consider effort, discoverability, keyboard/touch
+access and error risk; count clicks when useful.
+
+Separate product choices from implementation discretion. Engineers may choose ordinary technical
+details that preserve the contract. Ask about missing product decisions or material scope changes,
+not every helper name or internal decomposition.
+
+## Hunt blockers
+
+Before handing over, run the blocker hunt in [the blocker checklist](references/blocker-checklist.md):
+probe first, then ask in rounds until every item is decided, a user action or not in this task.
+Record the result in the handoff: the blocker table, the permission list, the verifier of each
+criterion, **Done when** and **Not in this task**. When a goal depends on a third-party wait, such
+as an external review, end the task before the wait; the wait and the work after it become a
+follow-up task.
+
+## Visual decisions and acceptance
+
+Show a rendering when a decision depends on perceived size, color, spacing or hierarchy.
+Use `denisco-visual-check` preview if available; label reproductions and uncertainty. Fixed wording,
+existing component reuse or functional UI changes do not automatically require visual candidates.
+If the user already chose the appearance, do not reopen the choice.
+
+Select acceptance evidence by requirement: technical tests, interaction checks, browser measurements
+or perceptual comparison. Not every point needs every category. Same appearance as an existing
+element is a measurement against that element; keep perceptual criteria for comparisons that
+measurement cannot settle. Reuse the operating guide for
+commands, login and fixtures. A required check the agent cannot run gets its verifier from the
+blocker hunt: the user, or a waiver with the reason and the user's yes. Never drop a criterion
+because tooling is missing.
+
+## Deliver incrementally
+
+Read [the handoff template](references/handoff-template.md) before drafting. In writable mode,
+record decisions as they converge. In Plan Mode keep drafts in chat and identify documents to
+materialize later; do not write files against the active mode's restrictions.
+
+Each point has a stable ID, decided behavior, dependencies and executable acceptance criteria,
+each with its verifier. Excluded points remain with reasons. The handoff is ready only when the
+blocker hunt left no open item. Review relevant code anchors and verification prerequisites before
+handing over.
+Deliver a copyable planning prompt saved in HANDOFF.md and link its section. Save and reread the
+prompt directly from the template. When measurement was explicitly enabled and denisco-workflow-benchmark
+is already available, its `planning-prompt --handoff <file> --save` and `--check` commands may be
+used instead. In Plan Mode deliver the prompt in chat with writes pending.
+Do not require the user or another AI to assemble the planning prompt. PLAN/STATE and the first
+execution prompt belong to planning.
+
+Measurement is disabled by default. Enable it only when the current user request or applicable
+project instructions explicitly request workflow measurement for this task. Skill availability,
+acceptance criteria, an old register or a prior task's preference are not activation. When disabled,
+do not load, install or use denisco-workflow-benchmark; do not create, search for or bind a register and do
+not track a session. Persist the disabled state so later planning and implementation sessions cannot
+infer a different default. When explicitly enabled, the agent owns setup and registration; never
+ask the user for session IDs, log paths or nonces. Keep unrecoverable prior work explicitly
+unmeasured and never estimate tokens.
+
+Persist measurement activation in `<handoff-path>.workflow.json`, not only in chat or external
+PROMPTS.md. Follow the handoff template for this operational link. If a run exists, link it using
+denisco-workflow-benchmark `bind`; do not initialize a replacement. Include the context path and
+enabled/disabled/unknown measurement state in the planning prompt. Use disabled when no explicit
+activation exists. Unknown is reserved for a legacy or interrupted explicit activation whose state
+cannot yet be reconciled; it never means "enable by default". Record the reason and next action.

package/skills/denisco-interactive-spec-definition/references/blocker-checklist.md

@@ -0,0 +1,71 @@
+# Blocker checklist
+
+A **blocker** is anything the agent cannot settle alone that would stop or reshape the work: a fact
+only the user knows, an action only the user or a third party can take, a permission, or a check
+the agent cannot run. The **blocker hunt** finds them before the work they affect starts.
+
+## Probe first
+
+Settle by looking whatever looking can settle, then ask about the rest:
+
+- Read the official requirements of every external platform the task touches (submission, review,
+  publication, authentication, hosting limits). Record the links and each requirement found.
+- Run the project's verification cycle once and record the failures that already exist.
+- Validate a draft configuration or manifest when a validator exists.
+- Check what you can operate here: portals and dashboards, an authenticated browser, GUI clients,
+  media files, push and deploy. Every step you cannot operate is a step for the user.
+
+## Categories
+
+Name the concrete value for each category, or ask for it. Skip a category only when the task
+cannot touch it.
+
+| Category | Settle |
+|---|---|
+| Accounts and credentials | which account, who holds it, where the secret lives (never its value) |
+| Console and portal access | which console, organization and project; who can sign in |
+| Who operates each step | for every portal, GUI or physical step: the agent or the user |
+| Permissions | the permission list below |
+| Environments | staging or production, which domain, which data |
+| Size facts | facts that change how much to build: how many users, existing data, whether data may be lost |
+| Product decisions | choices only the user can make |
+| Third-party waits | reviews, approvals, propagation; expected duration; what the plan does meanwhile |
+| Paid services | which plan, who pays, limits that stop the work |
+| Legal and content | texts, policies and media the user must supply or approve |
+| Checks the agent cannot run | who verifies each one, below |
+
+## Close every item
+
+Each item ends in exactly one state:
+
+- **decided:** the answer is recorded where it applies;
+- **your action:** the user agreed to do it; the item names the point it unblocks and how the agent
+  will check it, and it appears in **Your actions**;
+- **not in this task:** moved out of the task with the user's yes.
+
+An item never asked, or recorded as unknown, is still open, and the work that depends on it is not
+ready.
+
+## Permission list
+
+Ask once for the actions the agent may take during this task without asking again. Each entry
+names the action, its target and its limit, for example: push to `auth/*` branches; deploy
+`mcp-service`; write to the staging database.
+
+These actions always need a fresh yes, even when listed: submitting or publishing to a store or
+portal; DNS and certificates; deleting or migrating production data; spending money; messages to
+real people. Ask before any action outside the list.
+
+## Who verifies
+
+Every acceptance criterion names its verifier:
+
+- **agent:** the agent runs the check;
+- **user:** the user performs it and reports; the report is the evidence;
+- **waived:** nobody runs it; record the reason and the user's yes.
+
+## Asking
+
+Ask in rounds. Number each question and give your recommended answer, so that "yes" accepts it.
+Put every question that is ready into the same round; a question that depends on another answer
+waits for the next round.

package/skills/denisco-interactive-spec-definition/references/handoff-template.md

@@ -0,0 +1,124 @@
+# Handoff template
+
+Write in the project's documentation language. Use its established task directory; otherwise
+use `docs/agent-workflow/tasks/<task-id>/`. Measurement records are separate from the product
+contract. Never copy credentials or duplicate the operating guide.
+
+## HANDOFF.md
+
+First line: **Use `denisco-handoff-implementation` in planning-only mode to produce PLAN, STATE and the
+first execution prompt, then ask before implementing; use `denisco-visual-check` only for the selected
+visual criteria.**
+
+- Task ID, title, kind (bug/feature), goal and scope; the originating task when a new goal split off.
+- **Done when:** one observable outcome for the whole task.
+- **Not in this task:** each item moved out, with its reason and the user's yes. A third-party wait
+  and the work after it form a follow-up task.
+- Specification request/approval evidence, date and scope. Completion means delivering this
+  handoff and planning prompt; planning starts only on the user's yes to the planning question or
+  a submitted planning prompt. Preserve any explicit later requests; never infer them from
+  specification approval or a native mode transition. In particular, do not record bare native
+  control text such as `Implement the plan.` as planning or implementation authorization.
+- **Blockers:** the blocker hunt's result as a table: item, state (decided, your action, not in this
+  task), the point it unblocks and how the agent checks it. Platform requirements found by probing
+  link their source; pre-existing verification failures are listed with their output location.
+- **Permission list:** action, target and limit for each entry. The always-ask actions in the blocker
+  checklist stay outside it.
+- Project map and operating-guide links; code snapshot (commit and relevant uncommitted changes).
+- What already works and must remain intact; superseded/complemented documents.
+- Bug: expected/observed behavior, reproduction, cause evidence and unresolved hypotheses.
+- Feature: target business outcome and relevant users/roles.
+
+For each stable point ID (P1, P2, ...):
+
+1. **Status:** ready, or excluded with its reason.
+2. **Why and current behavior:** paths/symbols, constraints and verified findings.
+3. **Decided behavior:** normal and boundary cases, what must not regress.
+4. **Implementation guidance:** reuse, affected areas, invariants, backend impact and order.
+   Avoid making incidental file lists absolute when equivalent internals work.
+5. **Dependencies and difficulty:** point IDs and your-action items it waits for; green/yellow/red
+   as estimates, not session limits.
+6. **Acceptance:** stable criterion IDs (P1-A1), expected result, evidence procedure and verifier
+   (agent, user, or waived with reason).
+
+Select only applicable categories:
+
+| Category | Required information |
+|---|---|
+| Technical | Command/test or API operation, inputs, expected output and regression case |
+| Interaction | Route, role, fixture references, actions and observable effect |
+| Measurement | Selector, property, expected value/relation and justified tolerance; for parity, the reference element and compared properties |
+| Perceptual | Comparative criterion that measurement cannot settle, surrounding context and approved reference if one exists |
+
+Reference the project verification cycle once. A required check the agent cannot run names its
+verifier: the user, or waived with the reason and the user's yes. Do not fabricate fixtures or
+substitute weaker acceptance checks without agreement. An approved mockup is intent, not
+application evidence.
+
+For visual criteria identify IDs and evidence types. The principal normally performs denisco-visual-check;
+only perceptual judgment uses an independent blind judge when available and permitted.
+Delegate the whole check only on an explicit user request. The planning skill assigns sidecar
+visualChecks entries with a unique ID, block, criteria and executor "principal" by default, or
+"subagent" for the requested delegation. Record attempts/results with the matching executor.
+
+## PLAN.md and STATE.md
+
+Produced by planning-only denisco-handoff-implementation. PLAN is the block map; STATE is the current
+picture with **Your actions** first; STATE-HISTORY.md keeps the history. Implementation starts on
+the user's yes to the start question or a submitted execution prompt; neither specification nor
+planning starts it by itself. HANDOFF holds decided behavior, not progress. A later blocker hunt
+for a new point edits that point here in place and moves the replaced text to STATE-HISTORY.md.
+
+## Operational link
+
+Preserve task-local measurement in `<handoff-path>.workflow.json` (append after `.md`):
+`schemaVersion: 1`, `taskId`, `handoff`, `plan`, `state`, `measurement`, and `blocks: []`.
+Document paths are relative to this JSON; use existing paths or default to PLAN.md/STATE.md
+alongside the handoff. Measurement is disabled by default: write `{ "status": "disabled" }` unless
+the current user request or applicable project instructions explicitly enable workflow measurement
+for this task. Use `{ "status": "unknown" }` only for a legacy or interrupted explicit activation
+whose setup cannot yet be reconciled. Once explicitly enabled, denisco-workflow-benchmark's `bind --run
+<file> --handoff <file>` populates the validated binding: absolute run, runId, benchmark taskId and
+criteriaHash. Installed tooling, criteria or an old register do not activate measurement.
+The implementation skill fills the planned block map; specification must not invent the split.
+Do not copy token counts or changing outcomes into this file. Include its path in the outgoing
+prompt even when the register lives outside the project. Propose, rather than write, in Plan Mode.
+
+## Ready to hand over
+
+Check code evidence, decided product choices, executable acceptance criteria with verifiers,
+**Done when**, and the blocker table. Every blocker is decided, a your-action item or not in this
+task; an open blocker means the handoff is not ready, so ask about it. Technical unknowns that
+implementation will settle stay as stated hypotheses, each with the check that settles it.
+
+When measurement is explicitly enabled, initialize/bind it and register this conversation through
+denisco-workflow-benchmark `track --handoff <file> --provider <actual-provider> --phase specification`;
+execute its returned nextCall yourself in a separate tool call. Retry a delayed transcript once;
+retain any remaining gap in the handoff. Never pass a registration ticket to the next conversation.
+When disabled, do not load, install or invoke denisco-workflow-benchmark and do not inspect unrelated runs.
+
+Save the initial prompt with `planning-prompt --handoff <file> --save`, then run `--check`.
+It works with an empty block map and without PLAN/STATE. It appends a managed section to HANDOFF,
+preserving the specification; it never approves a plan or creates fictitious progress. Link the
+section and provide its saved text. Plain printing is not delivery. Without the helper save and
+reread this equivalent, replacing paths and measurement with actual values:
+
+```text
+Use denisco-handoff-implementation with <absolute HANDOFF.md>.
+Phase: planning only. Read <absolute HANDOFF.md.workflow.json> and existing PLAN/STATE.
+Check the blocker table and permission list; ask in chat about any unresolved item first.
+Create or reconcile PLAN, STATE and the complete planned block map, preserving decisions and
+observed progress. Select the first dependency-ready block and save/check its execution prompt in
+STATE. Do not implement application code in this phase. Once the planning documents and prompt are
+saved, choose the execution path as denisco-handoff-implementation specifies: prepare coordination and ask
+its start question, or ask "Plan ready. Start <block>?". Only the user's yes to the start question
+starts implementation.
+Measurement is disabled. Preserve `measurement.status` as `disabled`; do not initialize, discover
+or invoke measurement tooling or registers in this or later sessions.
+In Plan Mode propose these deliverables in chat with writes pending. Once writing is permitted,
+save/check them and ask; native plan approval or automatic mode does not start implementation.
+```
+
+Only an explicit activation request replaces the disabled measurement sentence with the enabled
+binding/setup instructions. Unavailable helpers or write restrictions leave an explicitly requested
+setup pending; they do not activate measurement or remove the prompt or independent ready work.

package/skills/denisco-project-context/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: denisco-project-context
+description: "Explore or refresh a repository's business/architecture map and operational procedures for startup, login and tests. Use for onboarding or stale project context; not for deciding a feature or implementing a bug fix."
+metadata:
+  version: "2.0.0"
+---
+
+# Project context
+
+Input: repository path, optional first-task area, optional refresh scope.
+Output: a concise map and operating guide that a fresh agent can locate and reuse.
+
+## Explore before asking
+
+Read applicable project instructions and existing README/design/run/test documents. Inspect
+manifests, entrypoints, module boundaries and verification tooling. Begin with a broad map,
+then deepen the first-task area; do not read the entire repository or dependencies by default.
+
+Record business purpose, modules, shared rules and integration boundaries. Label business meaning
+inferred from code as inferred; ask only for consequential gaps that inspection cannot resolve.
+Read important evidence yourself. Negative findings include scoped search evidence and date.
+
+Discover startup commands, local/shared services, login procedure, roles, test commands, fixtures,
+write permissions and restoration steps. Name the value of each prerequisite, not only the rule:
+a group that must be selected, a day with usable data, an account with the required role. Record
+where the executable tooling lives and whether it survives a new worktree.
+Inspect existing denisco-visual-check configuration without copying sensitive values. A configured command
+is not an executed command. Do not run production commands or write shared data just to complete
+onboarding. Read-only discovery is sufficient to
+produce an initial map, with runtime checks marked unverified.
+
+Record the project's approved tool-permission entries. When a command needs a tool permission or
+sandbox escalation that the project does not grant yet, propose one permanent entry: command
+pattern, client settings file and reason. Add it to the settings and to the operating guide only
+after the user's yes; permission settings never change without it.
+
+## Produce and refresh
+
+Read [document templates](references/project-documents.md). Reuse the project's documents and
+add links rather than replacing or duplicating them. Otherwise use docs/agent-workflow/PROJECT.md
+and OPERATIONS.md. A grown operating guide becomes an index over
+docs/agent-workflow/operations/, keeping its own path stable for the skills that reference it.
+Include an index link in existing agent instructions only within authorized scope.
+In Plan Mode return the proposed contents and paths; materialize only when writes are allowed.
+
+Track source path/symbol, verification date, snapshot and evidence level. Keep unknowns explicit.
+Store machine paths/session files locally; references to approved credential sources may be documented,
+but never credential values. Read the minimum relevant sections in subsequent task sessions.
+
+On targeted refresh inspect changed/relevant areas and update only supported facts, retaining user
+decisions and marking conflicts. Full refresh revisits the map and operational prerequisites; it
+does not promise every business rule was exhaustively audited. Documentation guides exploration;
+reverify load-bearing facts before changing code.
+
+## Handoff and measurement
+
+Report documents, coverage and unresolved runtime prerequisites. Provide the next prompt for
+denisco-interactive-spec-definition on the selected task, if there is one. Do not invent a task.
+When benchmarking, register initial discovery as exploration; record later refreshes as exploration
+sessions linked to their task. Keep this investment visible rather than hiding it in implementation.

package/skills/denisco-project-context/references/project-documents.md

@@ -0,0 +1,70 @@
+# Project documents
+
+Follow existing documentation language; use Italian for a new user-facing project guide in this workflow.
+Paths below are defaults, not competing copies of existing authoritative documents.
+
+## PROJECT.md
+
+- Repository identity and links to instructions/README/OPERATIONS.md.
+- Business purpose and users; distinguish confirmed meaning from code-derived inference.
+- Module map: responsibility, entrypoint/symbol and dependencies.
+- Important flows and shared invariants; generated code and sources of truth.
+- First-task area: relevant producers, consumers and verification.
+- Evidence table: finding, source, checked date, commit/dirty state, discovered/executed/unknown.
+- Coverage and open questions. Do not claim complete system knowledge.
+
+## OPERATIONS.md
+
+- Prerequisites and versions; commands with working directory and expected readiness signal.
+- Services: local/shared, which configuration selects endpoints, actual permission boundaries.
+- Authentication: entry route, human or approved automated procedure, required role, success signal,
+  session reuse/expiry. Refer to secret sources, never values.
+- Verification matrix: area, command/interaction, prerequisites, expected outcome, last execution.
+- Fixtures: case name, how to obtain non-sensitive test data, allowed writes and reset/cleanup.
+- Visual capture: link existing config; otherwise viewport/theme/routes only when needed.
+- Browser access for agents: interactive tools available (MCP or DevTools servers, extensions),
+  scripted drivers, and how each reaches the checked app state.
+- Coordinated workers: the extra skills each programmer loads, with purpose and limits; the browser
+  tools to load; the ports and services workers may use or start. denisco-implementation-coordinator gives
+  workers only the skills listed here.
+- Known environmental failures and expected noise, backed by evidence.
+- Named prerequisites: a prerequisite stated as a rule is not documented until its value is named.
+  Which group, which day, which account, which flags, with the value, how it was obtained and when
+  it was last verified. A value that lives only in a command example or a script default is lost.
+- Executable tooling: record where it lives and whether it survives a new worktree. An ignored
+  directory inside one worktree is not a durable home; name the shared location, what it holds, and
+  what stays per worktree. Paths, never secret values.
+- Approved permission entries: command pattern, client and settings file, reason and approval date.
+  An entry is written only after the user's yes.
+
+Use explicit "not executed" for commands only discovered in source. Missing browser tooling affects
+browser checks, not unrelated unit tests. Missing write authorization leaves write tests blocked.
+
+## Growing the operating guide
+
+OPERATIONS.md is the entry point named by `operatingGuide` and by denisco-visual-check,
+denisco-interactive-spec-definition and denisco-handoff-implementation. Do not rename or replace it when it grows:
+it becomes the index.
+
+Move a topic to `docs/agent-workflow/operations/<topic>.md` once it stops describing and starts
+accumulating, which happens first to known failures and the verification matrix. Leave one index
+row per topic: topic, file, one sentence of purpose, last update. Expected topics follow the
+sections themselves: startup and build, services and environment, authentication, roles and flags,
+verification, fixtures, known failures.
+
+Split incrementally: move the topic you are touching rather than rewriting the document in one
+pass. Keep the index short enough to read at once, and keep every moved fact's provenance with it.
+
+## Updating existing documentation
+
+Keep useful user-authored content. Update verified facts with a short reason; link rather than copy
+procedures. If established documents disagree, record the discrepancy until source/runtime/user
+evidence settles it. Keep workstation paths and saved sessions in the existing ignored local area.
+
+## Refresh prompt
+
+```text
+Use denisco-project-context on this repository. Refresh the module map and operating guide for <area>.
+Reuse existing documents, inspect the actual sources, and distinguish discovered from executed
+procedures. Retain unresolved login/test prerequisites. Do not implement a feature.
+```

package/skills/denisco-visual-check/SKILL.md

@@ -0,0 +1,136 @@
+---
+name: denisco-visual-check
+description: "Preview appearance choices or verify explicit visual requirements using browser measurements and perceptual comparisons. Use for size, color, spacing or visual hierarchy; not as a mandatory gate for every UI edit, functional test or new design project."
+metadata:
+  version: "4.0.0"
+---
+
+# Visual check
+
+The principal normally loads this skill and performs captures, measurements and evidence recording.
+Here principal means the implementation owner. A bounded programming worker with its own worktree
+claim follows those responsibilities, including index updates and source corrections; it is not
+the restricted visual-only child described below. Its coordinator remains read-only. When measured,
+follow denisco-handoff-implementation's bounded contract for native executor attribution: operational
+ownership does not turn a native child into a top-level session.
+Delegate the whole check only on an explicit user request; record that choice in the workflow map.
+Only perceptual judging uses an automatic fresh, independent agent when available and permitted.
+
+An explicitly delegated visual-only child must load this skill and return assigned criterion IDs,
+evidence paths and pass/fail/not-run results. It writes only its exclusive attempt directory:
+no application source, PLAN/STATE, sidecar, register, shared tooling or new implementation CLI.
+The principal merges shared records and applies source corrections after capture. Establish the
+principal, criteria and directory before child writes. An unavailable explicitly requested child
+leaves the check unverified unless the user changes that assignment.
+
+Choose preview for an undecided appearance and check for an implemented visual requirement.
+Do not reopen a settled choice. A fixed requirement may be implemented directly and checked.
+
+## Scope the evidence
+
+Select applicable criteria before acquiring images:
+
+- Measurable: values/relations read from the browser, with expected values and justified tolerances.
+  Parity with an existing element is measurable: compare resolved computed values, inherited ones
+  included, and the rendered box (size, padding, gap, text position) of candidate and reference
+  in the same state. Declared CSS alone does not prove parity.
+- Perceptual: comparative questions about hierarchy, balance or visibility in context that
+  measurement cannot settle.
+- Functional: belongs to the project's interaction tests, not a blind visual judge.
+
+Do not invent measurable or perceptual gates when that category is absent.
+Never infer exact pixels/colors from screenshots. Cite resolved source values when browser
+measurement is unavailable, and label them as source-derived rather than measured.
+
+## Acquire only what the question needs
+
+Use the project operating guide for start commands, login, roles and fixtures.
+Read [configuration](references/project-config.md) when using an existing visual config or needing
+persistent capture coordinates. A supplied screenshot or standalone preview needs no app config.
+
+1. User screenshot: useful for perceptual review when the state is unreachable; measurements remain unchecked.
+2. Standalone mockup: resolve tokens and reproduce surrounding context for a design decision.
+   Use available HTML/browser or artifact tools; no dependency on a named artifact skill.
+3. Real app: reuse the configured server and available browser tooling; start it only as authorized.
+   Use an existing project run skill if available, otherwise the documented command.
+4. Authenticated/stateful app: follow the operating guide, reuse a valid session and navigate to the fixture.
+
+Prefer interactive browser tooling (an MCP browser, DevTools or an open automation session) to
+explore the page, find selectors, measure and try a CSS hypothesis on the running app. Keep that
+session and the project's incremental rebuild running between checks instead of relaunching a
+whole scenario per question. A probe script reproduces the final evidence; it is not the
+diagnostic loop. When the checked state exists only through script-side interception, keep that
+browser open and attach the interactive tool to it when possible.
+
+Check existing MCP browser tooling, project/global drivers and system browsers before proposing
+installation. If tooling is absent, report the narrow missing capability. Do not install or kill
+processes simply to obtain an image without task authorization. Track each resource this check starts by its returned handle or verified PID and ownership.
+In a finally/cleanup path on success, failure or cancellation, close temporary browser contexts,
+browser processes, shell jobs and servers created solely for the check. Preserve pre-existing or
+shared services and resources explicitly needed for subsequent work, recording why they remain.
+Use the environment's close/release operation for a returned child when available; a final response
+alone does not prove its resources closed. The blind judge must not start any processes.
+Never kill by a broad process name or port. Verify owned resources exited; if the tool cannot close
+or verify one, report its identifier and pending cleanup without claiming success. Cleanup is part
+of the check and must finish before the worktree claim is released.
+
+Follow the environment's documented write permissions. Shared services do not authorize arbitrary
+saves. A write test needs a permitted fixture and recovery procedure. Never embed credentials in
+documents. Prefer user login plus saved session or an existing approved authentication mechanism.
+
+Record viewport (default 1440x900, scale 1), rendered theme, route, state and capture provenance.
+Match dimensions across images and crop to the element **plus surrounding context**.
+
+## Organize artifacts
+
+Group artifacts by task, not by session. Write probes, diagnostics and captures under
+`<artifactsDir>/<taskId>/`, reusing the task ID of the handoff folder so that a task's documents
+and its artifacts carry one name. Shared configuration and the index stay at the artifacts
+root; nothing task-specific belongs there. The browser profile, the login helper and anything
+reused across worktrees belong to toolingDir, outside the worktree, because an ignored directory
+inside one does not survive the next checkout. Without an assigned task use a
+descriptive slug and the same layout. Keep the outputs of one run in a subfolder named after it.
+
+Name a probe after the criteria or points it covers, not after an ordinal from a superseded plan.
+Read [the layout and index](references/project-config.md) before writing a new probe and reuse or
+extend an existing one instead of recreating a near-duplicate.
+
+An independent principal updates the index when writing artifacts. A delegated child writes only
+inside its assigned attempt directory and returns exact proposed index rows; the principal merges
+those rows serially after return. Shared probes, configuration and index updates belong to the
+principal. Read existing probes for reuse; copy into the attempt directory before changing them.
+The index records what exists and what superseded it, never that a criterion passed: results belong
+to the run register.
+
+## Preview
+
+Show current state and the meaningful candidates at the same scale. Recommend one with evidence.
+Label mockups as reproductions; they can be wrong about runtime behavior. A mockup cannot sign off
+the implementation. If rendering is unavailable, explain the gap rather than substitute ASCII for
+a decision about color or weight. Structural discussions can use prose or diagrams.
+
+## Check
+
+For a pre-edit baseline, the principal must wait for capture to finish before changing the
+measured application. For post-edit checks, keep the relevant source, shared capture tooling and
+fixture stable until capture finishes (and until the child returns when delegated). If they change during capture, disclose the overlap and
+recapture affected evidence; an unchanged Git HEAD does not prove an unchanged dirty worktree.
+
+Measure applicable criteria and their reference elements. Report selector, property, expected,
+actual and pass/fail. A failed measurement prevents sign-off; independent diagnostics may continue.
+
+For perceptual criteria, use [the blind judge contract](references/judge-prompt.md).
+Spawn a fresh agent without inherited conversation only when the capability is available and
+authorized. Otherwise offer user review and mark independent judgment unavailable; do not fabricate it.
+The judge sees only anonymized images and comparisons. Preserve its observations verbatim and apply
+the predeclared acceptance condition yourself; its preference is not a product decision.
+A failed judgment allows one correction and one new judgment of the same criterion. If that also
+fails, or contradicts passing measurements of the same properties, stop the loop: show the user the
+images with the measurements and ask once to verify it from them, rewrite the criterion or waive it.
+
+## Report
+
+State evidence type (real app, supplied screenshot, mockup), applicable measurements, quoted judge
+or user observations, criterion results and artifact paths. Use pass/fail/not-run per requirement.
+Do not report a preview or partial visual evidence as full verification. If a judge cannot tell,
+improve capture when justified or retain uncertainty; never soften the criterion until it agrees.

package/skills/denisco-visual-check/references/judge-prompt.md

@@ -0,0 +1,55 @@
+# Blind visual judge
+
+Use only for explicit perceptual criteria. Numerical criteria are measured separately.
+No requirement for two screenshots: comparison with unchanged siblings in one image can suffice.
+
+## Caller
+
+- Start a fresh agent without conversation inheritance, when available and authorized. Limit its
+  tools to opening the listed images when the runtime allows it. Pixel or color computations in
+  an answer are a boundary deviation to record, not measurement evidence.
+- Copy captures to neutral filenames A.png/B.png before sharing; remove revealing path labels.
+- For two versions randomize A/B and retain the mapping outside the judge prompt.
+- Provide comparable crops including context. Include an approved reference only if it exists.
+  Do not send an image whose content another listed image already contains.
+- Withhold code, spec, intent, diff and pass/fail measurements.
+- Ask comparative questions only. Do not request pixel sizes, coordinates or color values: those
+  are browser measurements.
+- The judge starts no shell, browser, server or further agent. After its response, the caller uses
+  the available close/release operation and reports any unavailable cleanup; returning is not proof
+  of process exit. Register its native usage separately from the principal visual attempt.
+- Preserve the original criterion on retries. An inconclusive verdict is a valid result.
+- Declare the acceptance condition before judgment; a ranking alone is not a pass condition.
+
+## Prompt
+
+Send this boundary and only the applicable image/criterion entries:
+
+```text
+Judge only the appearance visible in the supplied images.
+
+Boundary: do not read repository source, configuration, plans or documentation; do not run git;
+do not search files or the web; do not invoke skills or other agents. Do not run shell commands,
+scripts or other programs, and do not compute pixel or color values: judge by looking at the
+images. You may open only the image paths explicitly listed below.
+Do not reconstruct what changed or infer which version is newer.
+Do not write files, install tools, or change the application. Return your observations in the response.
+If context is insufficient, report that rather than investigating.
+
+Images:
+A: <neutral absolute image path>
+B: <optional neutral absolute image path>
+Approved design intent: <optional actual approved image>
+
+Criteria:
+1. <comparison, e.g. rank toolbar controls by visual weight and explain the visible signals>
+
+For each criterion report the observation, visible evidence and A/B label where applicable.
+Say "cannot tell from these images" when appropriate and identify a useful crop or additional view.
+End with an unprompted observation, including "nothing" if applicable.
+Do not give an overall score, infer intent or recommend implementation changes.
+```
+
+Report the judge's words verbatim and decode labels separately. Keep user review distinct from
+independent-agent review. If fresh judging is unavailable, record that limitation rather than
+silently using a context-aware agent.