modkh 0.0.0-stage → 0.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +66 -2
- package/dist/agent/bundled-skills.d.ts +13 -0
- package/dist/agent/bundled-skills.js +95 -0
- package/dist/agent/compaction.d.ts +53 -0
- package/dist/agent/compaction.js +191 -0
- package/dist/agent/images.d.ts +10 -0
- package/dist/agent/images.js +33 -0
- package/dist/agent/loop.d.ts +103 -0
- package/dist/agent/loop.js +267 -0
- package/dist/agent/skills.d.ts +26 -0
- package/dist/agent/skills.js +190 -0
- package/dist/agent/types.d.ts +137 -0
- package/dist/agent/types.js +12 -0
- package/dist/cli/agenticreplay.d.ts +1 -0
- package/dist/cli/agenticreplay.js +66 -0
- package/dist/cli/agents.d.ts +8 -0
- package/dist/cli/agents.js +12 -0
- package/dist/cli/answer-markdown.d.ts +3 -0
- package/dist/cli/answer-markdown.js +29 -0
- package/dist/cli/approval.d.ts +29 -0
- package/dist/cli/approval.js +92 -0
- package/dist/cli/catalog.d.ts +37 -0
- package/dist/cli/catalog.js +46 -0
- package/dist/cli/chat.d.ts +18 -0
- package/dist/cli/chat.js +1061 -0
- package/dist/cli/clipboard.d.ts +11 -0
- package/dist/cli/clipboard.js +82 -0
- package/dist/cli/color.d.ts +59 -0
- package/dist/cli/color.js +244 -0
- package/dist/cli/compaction-settings.d.ts +21 -0
- package/dist/cli/compaction-settings.js +54 -0
- package/dist/cli/completion-art.d.ts +2 -0
- package/dist/cli/completion-art.js +62 -0
- package/dist/cli/config.d.ts +50 -0
- package/dist/cli/config.js +192 -0
- package/dist/cli/editor.d.ts +23 -0
- package/dist/cli/editor.js +115 -0
- package/dist/cli/file-mentions.d.ts +14 -0
- package/dist/cli/file-mentions.js +141 -0
- package/dist/cli/head-checks.d.ts +41 -0
- package/dist/cli/head-checks.js +146 -0
- package/dist/cli/initial-connection.d.ts +7 -0
- package/dist/cli/initial-connection.js +20 -0
- package/dist/cli/keys.d.ts +29 -0
- package/dist/cli/keys.js +107 -0
- package/dist/cli/language.d.ts +1 -0
- package/dist/cli/language.js +105 -0
- package/dist/cli/limits.d.ts +13 -0
- package/dist/cli/limits.js +19 -0
- package/dist/cli/lines.d.ts +18 -0
- package/dist/cli/lines.js +80 -0
- package/dist/cli/model-catalog.d.ts +16 -0
- package/dist/cli/model-catalog.js +130 -0
- package/dist/cli/models.d.ts +4 -0
- package/dist/cli/models.js +101 -0
- package/dist/cli/official-models.d.ts +6 -0
- package/dist/cli/official-models.js +77 -0
- package/dist/cli/pdf.d.ts +8 -0
- package/dist/cli/pdf.js +71 -0
- package/dist/cli/permissions.d.ts +25 -0
- package/dist/cli/permissions.js +30 -0
- package/dist/cli/plugins.d.ts +1 -0
- package/dist/cli/plugins.js +53 -0
- package/dist/cli/providers.d.ts +10 -0
- package/dist/cli/providers.js +82 -0
- package/dist/cli/shell-display.d.ts +6 -0
- package/dist/cli/shell-display.js +35 -0
- package/dist/cli/stateright.d.ts +1 -0
- package/dist/cli/stateright.js +37 -0
- package/dist/cli/terminal-mouse.d.ts +21 -0
- package/dist/cli/terminal-mouse.js +51 -0
- package/dist/cli/terminal.d.ts +231 -0
- package/dist/cli/terminal.js +1417 -0
- package/dist/cli/tool-display.d.ts +9 -0
- package/dist/cli/tool-display.js +87 -0
- package/dist/cli/transcript-selection.d.ts +22 -0
- package/dist/cli/transcript-selection.js +75 -0
- package/dist/cli/usage.d.ts +22 -0
- package/dist/cli/usage.js +117 -0
- package/dist/cli/waiting-nyan.d.ts +3 -0
- package/dist/cli/waiting-nyan.js +17 -0
- package/dist/cli/waiting-whales.d.ts +3 -0
- package/dist/cli/waiting-whales.js +24 -0
- package/dist/index.d.ts +11 -0
- package/dist/index.js +186 -0
- package/dist/language/catalog.d.ts +44 -0
- package/dist/language/catalog.js +100 -0
- package/dist/language/commonlisp-bundled.d.ts +11 -0
- package/dist/language/commonlisp-bundled.js +22 -0
- package/dist/language/commonlisp-dependencies.d.ts +16 -0
- package/dist/language/commonlisp-dependencies.js +68 -0
- package/dist/language/commonlisp-install.d.ts +15 -0
- package/dist/language/commonlisp-install.js +214 -0
- package/dist/language/commonlisp-reader.d.ts +17 -0
- package/dist/language/commonlisp-reader.js +47 -0
- package/dist/language/commonlisp-systems.d.ts +3 -0
- package/dist/language/commonlisp-systems.js +32 -0
- package/dist/language/commonlisp-tls.d.ts +10 -0
- package/dist/language/commonlisp-tls.js +51 -0
- package/dist/language/detect.d.ts +29 -0
- package/dist/language/detect.js +103 -0
- package/dist/language/grammars/LICENSE +24 -0
- package/dist/language/grammars/manifest.json +76 -0
- package/dist/language/grammars/tree-sitter-c.wasm +0 -0
- package/dist/language/grammars/tree-sitter-cpp.wasm +0 -0
- package/dist/language/grammars/tree-sitter-css.wasm +0 -0
- package/dist/language/grammars/tree-sitter-html.wasm +0 -0
- package/dist/language/grammars/tree-sitter-javascript.wasm +0 -0
- package/dist/language/grammars/tree-sitter-php.wasm +0 -0
- package/dist/language/grammars/tree-sitter-python.wasm +0 -0
- package/dist/language/grammars/tree-sitter-ruby.wasm +0 -0
- package/dist/language/grammars/tree-sitter-rust.wasm +0 -0
- package/dist/language/grammars/tree-sitter-swift.wasm +0 -0
- package/dist/language/grammars/tree-sitter-tsx.wasm +0 -0
- package/dist/language/grammars/tree-sitter-typescript.wasm +0 -0
- package/dist/language/install.d.ts +50 -0
- package/dist/language/install.js +293 -0
- package/dist/language/lsp/client.d.ts +97 -0
- package/dist/language/lsp/client.js +340 -0
- package/dist/language/lsp/pool.d.ts +75 -0
- package/dist/language/lsp/pool.js +140 -0
- package/dist/language/lsp/service.d.ts +50 -0
- package/dist/language/lsp/service.js +174 -0
- package/dist/language/native.d.ts +8 -0
- package/dist/language/native.js +100 -0
- package/dist/language/platform.d.ts +14 -0
- package/dist/language/platform.js +20 -0
- package/dist/language/positions.d.ts +20 -0
- package/dist/language/positions.js +46 -0
- package/dist/language/syntax/assets.d.ts +9 -0
- package/dist/language/syntax/assets.js +73 -0
- package/dist/language/syntax/parser.d.ts +33 -0
- package/dist/language/syntax/parser.js +162 -0
- package/dist/language/typescript-capability.d.ts +6 -0
- package/dist/language/typescript-capability.js +42 -0
- package/dist/lisp/builtin-agents.d.ts +5 -0
- package/dist/lisp/builtin-agents.js +52 -0
- package/dist/lisp/config.d.ts +25 -0
- package/dist/lisp/config.js +202 -0
- package/dist/lisp/routing.d.ts +5 -0
- package/dist/lisp/routing.js +24 -0
- package/dist/lisp/runtime.d.ts +26 -0
- package/dist/lisp/runtime.js +107 -0
- package/dist/memory/kiokuko.d.ts +32 -0
- package/dist/memory/kiokuko.js +102 -0
- package/dist/memory/mcp.d.ts +38 -0
- package/dist/memory/mcp.js +211 -0
- package/dist/model/ai-sdk.d.ts +27 -0
- package/dist/model/ai-sdk.js +185 -0
- package/dist/model/chatgpt/login.d.ts +42 -0
- package/dist/model/chatgpt/login.js +180 -0
- package/dist/model/chatgpt/responses.d.ts +41 -0
- package/dist/model/chatgpt/responses.js +254 -0
- package/dist/model/chatgpt/tokens.d.ts +11 -0
- package/dist/model/chatgpt/tokens.js +50 -0
- package/dist/model/connection.d.ts +6 -0
- package/dist/model/connection.js +67 -0
- package/dist/model/context-window.d.ts +3 -0
- package/dist/model/context-window.js +64 -0
- package/dist/model/context.d.ts +11 -0
- package/dist/model/context.js +69 -0
- package/dist/model/factory.d.ts +27 -0
- package/dist/model/factory.js +89 -0
- package/dist/model/fixed.d.ts +17 -0
- package/dist/model/fixed.js +41 -0
- package/dist/model/harness-profile.d.ts +6 -0
- package/dist/model/harness-profile.js +23 -0
- package/dist/model/providers.d.ts +32 -0
- package/dist/model/providers.js +72 -0
- package/dist/model/reasoning.d.ts +16 -0
- package/dist/model/reasoning.js +84 -0
- package/dist/model/record-fetch.d.ts +2 -0
- package/dist/model/record-fetch.js +19 -0
- package/dist/plugins/api.d.ts +60 -0
- package/dist/plugins/api.js +1 -0
- package/dist/plugins/manager.d.ts +35 -0
- package/dist/plugins/manager.js +280 -0
- package/dist/plugins/package.d.ts +13 -0
- package/dist/plugins/package.js +99 -0
- package/dist/plugins/registry.d.ts +8 -0
- package/dist/plugins/registry.js +14 -0
- package/dist/session/store.d.ts +93 -0
- package/dist/session/store.js +311 -0
- package/dist/session/workspace.d.ts +19 -0
- package/dist/session/workspace.js +73 -0
- package/dist/subagents/head-assignment.d.ts +11 -0
- package/dist/subagents/head-assignment.js +47 -0
- package/dist/subagents/limits.d.ts +4 -0
- package/dist/subagents/limits.js +6 -0
- package/dist/subagents/processes.d.ts +18 -0
- package/dist/subagents/processes.js +73 -0
- package/dist/subagents/request.d.ts +4 -0
- package/dist/subagents/request.js +38 -0
- package/dist/subagents/service.d.ts +73 -0
- package/dist/subagents/service.js +645 -0
- package/dist/subagents/settings.d.ts +10 -0
- package/dist/subagents/settings.js +32 -0
- package/dist/subagents/types.d.ts +63 -0
- package/dist/subagents/types.js +1 -0
- package/dist/subagents/verification.d.ts +34 -0
- package/dist/subagents/verification.js +215 -0
- package/dist/tools/browse.d.ts +13 -0
- package/dist/tools/browse.js +117 -0
- package/dist/tools/browser-capability.d.ts +3 -0
- package/dist/tools/browser-capability.js +29 -0
- package/dist/tools/diff.d.ts +6 -0
- package/dist/tools/diff.js +82 -0
- package/dist/tools/edit.d.ts +3 -0
- package/dist/tools/edit.js +152 -0
- package/dist/tools/files.d.ts +6 -0
- package/dist/tools/files.js +96 -0
- package/dist/tools/formal-input.d.ts +6 -0
- package/dist/tools/formal-input.js +29 -0
- package/dist/tools/formal.d.ts +9 -0
- package/dist/tools/formal.js +79 -0
- package/dist/tools/guard.d.ts +7 -0
- package/dist/tools/guard.js +48 -0
- package/dist/tools/job-tools.d.ts +19 -0
- package/dist/tools/job-tools.js +148 -0
- package/dist/tools/jobs.d.ts +79 -0
- package/dist/tools/jobs.js +186 -0
- package/dist/tools/language.d.ts +6 -0
- package/dist/tools/language.js +172 -0
- package/dist/tools/lean-proof.d.ts +38 -0
- package/dist/tools/lean-proof.js +83 -0
- package/dist/tools/registry.d.ts +30 -0
- package/dist/tools/registry.js +113 -0
- package/dist/tools/run.d.ts +13 -0
- package/dist/tools/run.js +163 -0
- package/dist/tools/search.d.ts +2 -0
- package/dist/tools/search.js +156 -0
- package/dist/tools/shell-process.d.ts +115 -0
- package/dist/tools/shell-process.js +297 -0
- package/dist/tools/skills.d.ts +2 -0
- package/dist/tools/skills.js +46 -0
- package/dist/tools/stateright-runtime.d.ts +3 -0
- package/dist/tools/stateright-runtime.js +16 -0
- package/dist/tools/stateright.d.ts +3 -0
- package/dist/tools/stateright.js +78 -0
- package/dist/tools/web.d.ts +24 -0
- package/dist/tools/web.js +391 -0
- package/dist/version.d.ts +2 -0
- package/dist/version.js +2 -0
- package/docs/ci-repair-20261116.md +30 -0
- package/docs/commonlisp-build-output.md +14 -0
- package/docs/commonlisp-provider-migration.md +22 -0
- package/docs/commonlisp-qlot-recovery.md +28 -0
- package/docs/commonlisp-tls-recovery.md +28 -0
- package/docs/context-efficiency.md +122 -0
- package/docs/input.md +126 -0
- package/docs/languages.md +117 -0
- package/docs/models.md +109 -0
- package/docs/modkh-evidence.json +641 -0
- package/docs/modkh-failure-comparison.json +675 -0
- package/docs/modkh-namespace.md +39 -0
- package/docs/modkh-qlot-evidence.json +37 -0
- package/docs/modkh-verification.md +173 -0
- package/docs/modkh.md +128 -0
- package/docs/presets.md +64 -0
- package/docs/setup.md +99 -0
- package/docs/stateright.md +45 -0
- package/docs/subagents.md +152 -0
- package/docs/web.md +57 -0
- package/experiments/presets/common-lisp.lisp +38 -0
- package/experiments/presets/css.lisp +38 -0
- package/experiments/presets/formal.lisp +18 -0
- package/experiments/presets/html.lisp +38 -0
- package/experiments/presets/js.lisp +38 -0
- package/experiments/presets/language-microagents.lisp +29 -0
- package/experiments/presets/php.lisp +38 -0
- package/experiments/presets/svelte.lisp +38 -0
- package/experiments/presets/tailwindcss.lisp +24 -0
- package/experiments/presets/ts.lisp +38 -0
- package/native/stateright/Cargo.lock +478 -0
- package/native/stateright/Cargo.toml +11 -0
- package/native/stateright/src/lib.rs +163 -0
- package/native/stateright/src/main.rs +38 -0
- package/package.json +57 -4
- package/plugins/modkh-explorer/index.mjs +3 -0
- package/plugins/modkh-explorer/plugin.json +1 -0
- package/plugins/modkh-worker/index.mjs +3 -0
- package/plugins/modkh-worker/plugin.json +1 -0
- package/skills/kiokuko-dsh/LICENSE +21 -0
- package/skills/kiokuko-dsh/coding-ideal-routine-skill/SKILL.md +106 -0
- package/skills/kiokuko-dsh/japanese-translation-for-oss-models/SKILL.md +65 -0
- package/skills/kiokuko-dsh/kiokuko-architecture/SKILL.md +20 -0
- package/skills/kiokuko-dsh/kiokuko-architecture/references/cases.md +11 -0
- package/skills/kiokuko-dsh/kiokuko-benchmark/SKILL.md +20 -0
- package/skills/kiokuko-dsh/kiokuko-benchmark/references/cases.md +11 -0
- package/skills/kiokuko-dsh/kiokuko-investigate/SKILL.md +20 -0
- package/skills/kiokuko-dsh/kiokuko-investigate/references/cases.md +11 -0
- package/skills/kiokuko-dsh/kiokuko-lisp/SKILL.md +390 -0
- package/skills/kiokuko-dsh/kiokuko-review/SKILL.md +20 -0
- package/skills/kiokuko-dsh/kiokuko-review/references/cases.md +11 -0
- package/skills/kiokuko-dsh/kiokuko-simple-work/SKILL.md +70 -0
- package/skills/kiokuko-dsh/kiokuko-single-purpose-functions/SKILL.md +79 -0
- package/skills/kiokuko-dsh/kiokuko-single-purpose-functions/references/boundaries-and-ownership.md +52 -0
- package/skills/kiokuko-dsh/kiokuko-single-purpose-functions/references/domain-and-types.md +48 -0
- package/skills/kiokuko-dsh/kiokuko-single-purpose-functions/references/effects-and-data.md +43 -0
- package/skills/kiokuko-dsh/kiokuko-single-purpose-functions/references/kiokuko-patterns.md +314 -0
- package/skills/kiokuko-dsh/kiokuko-single-purpose-functions/references/problem-shaping-and-language.md +90 -0
- package/skills/kiokuko-dsh/kiokuko-single-purpose-functions/references/protocols-and-idempotency.md +42 -0
- package/skills/kiokuko-dsh/kiokuko-single-purpose-functions/references/review-checklist.md +92 -0
- package/skills/kiokuko-dsh/kiokuko-single-purpose-functions/references/verification.md +45 -0
- package/skills/kiokuko-dsh/kiokuko-skill-authoring/SKILL.md +20 -0
- package/skills/kiokuko-dsh/kiokuko-skill-authoring/references/cases.md +11 -0
- package/skills/kiokuko-dsh/kiokuko-soul/SKILL.md +25 -0
- package/skills/kiokuko-dsh/kiokuko-technical-writing/SKILL.md +20 -0
- package/skills/kiokuko-dsh/kiokuko-technical-writing/references/cases.md +11 -0
- package/skills/kiokuko-dsh/kiokuko-ui-design-soul/SKILL.md +64 -0
- package/skills/kiokuko-dsh/kiokuko-ui-design-soul/references/accessibility-and-navigation.md +31 -0
- package/skills/kiokuko-dsh/kiokuko-ui-design-soul/references/async-recovery.md +49 -0
- package/skills/kiokuko-dsh/kiokuko-ui-design-soul/references/forms-and-controls.md +35 -0
- package/skills/kiokuko-dsh/kiokuko-ui-design-soul/references/interaction-feedback.md +34 -0
- package/skills/kiokuko-dsh/kiokuko-ui-design-soul/references/responsive-and-platform.md +38 -0
- package/skills/kiokuko-dsh/kiokuko-ui-design-soul/references/safety-and-review.md +43 -0
- package/skills/kiokuko-dsh/kiokuko-ui-design-soul/references/ui-checklist.md +75 -0
- package/skills/kiokuko-dsh/kiokuko-verification/SKILL.md +20 -0
- package/skills/kiokuko-dsh/kiokuko-verification/references/cases.md +11 -0
- package/skills/kiokuko-dsh/manifest.json +168 -0
- package/skills/kiokuko-dsh/memory-reasoning/SKILL.md +44 -0
- package/skills/kiokuko-dsh/one-shot-software-completion/SKILL.md +113 -0
- package/skills/kiokuko-dsh/one-shot-software-completion/references/boundaries-and-lifecycle.md +70 -0
- package/skills/kiokuko-dsh/one-shot-software-completion/references/discovery-and-scope.md +71 -0
- package/skills/kiokuko-dsh/one-shot-software-completion/references/failure-recovery.md +43 -0
- package/skills/kiokuko-dsh/one-shot-software-completion/references/verification-and-completion.md +73 -0
- package/skills/kiokuko-dsh/veteran-programmer-skill/SKILL.md +66 -0
|
@@ -0,0 +1,45 @@
|
|
|
1
|
+
<!-- KIOKUKO MANAGED STANDARD SKILL: kiokuko-single-purpose-functions -->
|
|
2
|
+
|
|
3
|
+
# `code.verification.v1` — focused evidence and review
|
|
4
|
+
|
|
5
|
+
Select this expert for regression repair, behavior review, compatibility changes, or any function whose correctness claim depends on evidence beyond ordinary local reasoning.
|
|
6
|
+
|
|
7
|
+
## Evidence contract
|
|
8
|
+
|
|
9
|
+
Verification must exercise the same boundary and pipeline as the reported or intended behavior. A build does not replace a typecheck. A unit test of a helper does not replace the HTTP, CLI, hook, database, browser, or packaging path that failed.
|
|
10
|
+
|
|
11
|
+
Before editing, state a falsifiable invariant and at least one counterexample. After editing, run the smallest focused verifier that proves the change, then the broader verifier proportional to regression risk.
|
|
12
|
+
|
|
13
|
+
## Test shape
|
|
14
|
+
|
|
15
|
+
For each changed contract cover:
|
|
16
|
+
|
|
17
|
+
- representative success;
|
|
18
|
+
- important expected failure;
|
|
19
|
+
- the reported regression or a concrete counterexample;
|
|
20
|
+
- absence of forbidden effects after rejection;
|
|
21
|
+
- ownership or immutability when mutable input is possible;
|
|
22
|
+
- concurrency, retry, cancellation, or cleanup when the selected experts require them.
|
|
23
|
+
|
|
24
|
+
Prefer observable behavior over private implementation details. Use deterministic inputs and narrow fakes. Keep test names specific enough to identify the contract and failure class.
|
|
25
|
+
|
|
26
|
+
## Review method
|
|
27
|
+
|
|
28
|
+
Trace caller to boundary to domain decision to effects to public result. Check generated instructions, stored representations, migrations, packaging manifests, and runtime adapters when they are part of delivery; source code alone may not be the shipped behavior.
|
|
29
|
+
|
|
30
|
+
Classify uncertainty honestly:
|
|
31
|
+
|
|
32
|
+
- verified by a matching runnable test;
|
|
33
|
+
- inspected from source only;
|
|
34
|
+
- blocked by environment or unavailable dependency;
|
|
35
|
+
- not checked.
|
|
36
|
+
|
|
37
|
+
Do not convert a sandbox, listener, DNS, registry, or permission restriction into a product defect without a matching permitted rerun. Do not repeatedly run an unchanged blocked verifier.
|
|
38
|
+
|
|
39
|
+
## Completion
|
|
40
|
+
|
|
41
|
+
Report exact verifier commands or test names, their result, changed contract scope, and remaining gaps. If only a subset ran, do not claim the full suite passed.
|
|
42
|
+
|
|
43
|
+
## Focused engineering practice
|
|
44
|
+
|
|
45
|
+
For a reproducible defect, run the smallest meaningful failing check before repair and confirm it passes afterward. Prefer no new test over a mock-only or implementation-mirroring test. When repeated fixes fail on the same premise, identify the actors and shared state before trying another patch. Prefer validated domain types and exhaustive variants; casts require evidence, not blanket bans. Eliminate unnecessary shared state before adding serialization; preserve required transaction and idempotency guarantees.
|
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: kiokuko-skill-authoring
|
|
3
|
+
description: Create or improve a narrowly triggered skill from explicit preferences or verified reusable lessons.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
<!-- KIOKUKO MANAGED STANDARD SKILL: kiokuko-skill-authoring -->
|
|
7
|
+
|
|
8
|
+
<!-- kiokuko:runtime contract -->
|
|
9
|
+
# Skill authoring
|
|
10
|
+
|
|
11
|
+
Follow SOUL and the current host directive. This skill grants no extra permissions, model changes or delegation. Use the current model and proportionate evidence.
|
|
12
|
+
|
|
13
|
+
Use the current request, current conversation and explicitly authorized evidence. Never mine other chats. Find the existing owner before adding a new skill. Define trigger, exclusions, observable result and failure boundaries. Prefer executable checks over prose when they enforce a rule more reliably. Keep host-owned memory, model selection and permissions intact.
|
|
14
|
+
|
|
15
|
+
## Completion
|
|
16
|
+
|
|
17
|
+
Write compact instructions and load examples only for concrete ambiguity. Test triggering, non-triggering and failure scenarios. Preserve uncertainty and provenance; do not generalize a single anecdote into a universal rule. Editing a skill or globalizing memory needs scope authority, not inferred permission.
|
|
18
|
+
|
|
19
|
+
Read [worked cases](references/cases.md) only when the decision or failure boundary is unclear. Do not load unrelated specialists or repeat completed checks without new evidence.
|
|
20
|
+
<!-- /kiokuko:runtime -->
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
<!-- KIOKUKO MANAGED STANDARD SKILL: kiokuko-skill-authoring -->
|
|
2
|
+
|
|
3
|
+
# Decision example
|
|
4
|
+
|
|
5
|
+
One failed migration led to a proposed always-read-all-docs rule.
|
|
6
|
+
|
|
7
|
+
Reject the universal rule. Capture the concrete compatibility boundary and add an executable migration check if authorized. A lesson needs scope and a counterexample.
|
|
8
|
+
|
|
9
|
+
## Non-trigger
|
|
10
|
+
|
|
11
|
+
A mechanical edit with known behavior uses the existing simple-work and code contracts. Do not turn it into a panel, benchmark or architecture exercise.
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: kiokuko-soul
|
|
3
|
+
description: Kiokuko's entry router for non-trivial DSH work. Read it before any other Kiokuko Skill to reach the applicable specialist and the expert fragments that task needs.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
<!-- KIOKUKO MANAGED STANDARD SKILL: kiokuko-soul -->
|
|
7
|
+
|
|
8
|
+
<!-- kiokuko:runtime contract -->
|
|
9
|
+
# SOUL router
|
|
10
|
+
|
|
11
|
+
Read first. Host owns identity, capabilities and routing. Ordinary Lisp work needs no memory intake, Goal or review. Never invent a profile.
|
|
12
|
+
|
|
13
|
+
User instructions outrank Skills. Preserve identity, revisions, leases, Plan, cancellation and ownership. Optional enrichment never vetoes work. Clarify unclear intent or destructive effects; finish, verify and report blockers.
|
|
14
|
+
|
|
15
|
+
**本当に、それを全部計算・保存・検索する必要があるのか?**
|
|
16
|
+
Preserve results: eliminate needless computation/storage/search, narrow scope, then optimize. Justify exhaustive work. Never silently approximate/delete data or waive validation, recovery or audit. No extra approvals/artifacts.
|
|
17
|
+
|
|
18
|
+
Read relevant Skill indexes and risk-selected references; non-code needs no coding startup. Preserve roles, exclusions and recovery.
|
|
19
|
+
|
|
20
|
+
Use current model/memory/Skills and kioku_read/write/edit/remove/exec/result. Changes within the working project directory, including deletion, replacement and project DB updates, need no extra user permission. Outside-project changes require concrete confirmation. PATH/bash/zsh, Lisp and builds/tests remain authorized; native permissions and integrity checks still apply. Recover Lisp or explicitly change route. Pre-bind source/test/config checks; collect final background receipts. Receipts establish observations only; check recalled candidates against current sources. Report work, verification and memory saving separately. After each native turn, the host compacts evidence into summary, tags and keywords. Automatic mode saves in the background; review mode requires approval of the exact proposal. Memory preparation/review/save never gate work or completion. Never replay work or invent save identities. Human implementation requests or Plan approval request exit at the next accepted boundary; plan-only answers stay in Plan.
|
|
21
|
+
|
|
22
|
+
Without Skills, use current evidence within host identity/authority/integrity; never substitute required Skills or auto-install/execute fetched ones. Claim no unread Skills or unrun checks. Check supported file types before diagnostics; manually check Markdown/unsupported documents for structure, requirements and whitespace. Unavailable diagnostics stay unverified. After each successful edit/write, re-read before the next mutation; reconcile stale content and never force overwrites. Never repeat unsupported diagnostics unchanged.
|
|
23
|
+
|
|
24
|
+
Select kiokuko-{investigate,architecture,review,benchmark,verification,skill-authoring,technical-writing} as needed. Coding: coding-ideal-routine-skill owns coding_workflow and fresh Goal evidence.
|
|
25
|
+
<!-- /kiokuko:runtime -->
|
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: kiokuko-technical-writing
|
|
3
|
+
description: Write or revise technical explanations, instructions, reference material and change descriptions.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
<!-- KIOKUKO MANAGED STANDARD SKILL: kiokuko-technical-writing -->
|
|
7
|
+
|
|
8
|
+
<!-- kiokuko:runtime contract -->
|
|
9
|
+
# Technical writing
|
|
10
|
+
|
|
11
|
+
Follow SOUL and the current host directive. This skill grants no extra permissions, model changes or delegation. Use the current model and proportionate evidence.
|
|
12
|
+
|
|
13
|
+
Lead with the usable answer. Choose explanation, how-to, tutorial or reference based on the reader goal. Use real identifiers and concrete actions; remove filler and vague claims. Preserve uncertainty, conditions, technical meaning and useful rationale. Do not enforce word or punctuation bans that make prose worse. Apply natural-japanese-output for Japanese.
|
|
14
|
+
|
|
15
|
+
## Completion
|
|
16
|
+
|
|
17
|
+
Check commands and examples against current evidence. Separate tested behavior from suggestions. Match requested depth; a plain-language rewrite must not erase important failure modes. Report only the artifact unless explanation is useful.
|
|
18
|
+
|
|
19
|
+
Read [worked cases](references/cases.md) only when the decision or failure boundary is unclear. Do not load unrelated specialists or repeat completed checks without new evidence.
|
|
20
|
+
<!-- /kiokuko:runtime -->
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
<!-- KIOKUKO MANAGED STANDARD SKILL: kiokuko-technical-writing -->
|
|
2
|
+
|
|
3
|
+
# Decision example
|
|
4
|
+
|
|
5
|
+
A draft says the new cache guarantees instant results, but only one warm run was measured.
|
|
6
|
+
|
|
7
|
+
Write that the warm run completed in the measured time. Preserve dataset and sample count; omit universal claims. Japanese: 測定した1回では短縮した。再現性は未確認。
|
|
8
|
+
|
|
9
|
+
## Non-trigger
|
|
10
|
+
|
|
11
|
+
A mechanical edit with known behavior uses the existing simple-work and code contracts. Do not turn it into a panel, benchmark or architecture exercise.
|
|
@@ -0,0 +1,64 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: kiokuko-ui-design-soul
|
|
3
|
+
description: Use for user-facing interface work — design, implementation, or review — so every action stays discoverable, operable, recoverable, and accessible. Read only the expert fragments the interaction risks select.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
<!-- KIOKUKO MANAGED STANDARD SKILL: kiokuko-ui-design-soul -->
|
|
7
|
+
|
|
8
|
+
<!-- kiokuko:runtime contract -->
|
|
9
|
+
# UI design soul router
|
|
10
|
+
|
|
11
|
+
## Outcome
|
|
12
|
+
|
|
13
|
+
Make every interactive action discoverable, operable, perceivable, recoverable, accessible, and coherent across supported sizes and input methods.
|
|
14
|
+
|
|
15
|
+
Covers Web, desktop, mobile, CLI, touch, keyboard, screen-reader, form, navigation, async, destructive, permission, and other user-facing interaction work; not backend-only work. This is the compact UI index: read it completely, then read only the expert fragments selected for the current component, flow, design decision, or WorkUnit.
|
|
16
|
+
|
|
17
|
+
## Universal core
|
|
18
|
+
|
|
19
|
+
For new or behaviorally changed interactive actions, an action is complete only when the user can:
|
|
20
|
+
|
|
21
|
+
1. discover and understand it, with available choices shown whenever practical;
|
|
22
|
+
2. select and activate it comfortably through suitable shortcuts, menus, or checkbox lists;
|
|
23
|
+
3. perceive immediate acknowledgement;
|
|
24
|
+
4. follow intermediate progress or status during slow work, recognize completion, and understand the known cause of a failure;
|
|
25
|
+
5. recover without losing work or context;
|
|
26
|
+
6. continue through keyboard, touch, pointer, and assistive technology as applicable.
|
|
27
|
+
|
|
28
|
+
For purely visual changes, verify the affected appearance, layout, and accessibility properties, and expand into action-state behavior only when the change can affect it — a target size or a focus ring, for example.
|
|
29
|
+
|
|
30
|
+
Invisible work is a UI failure, so every reachable state needs defined behavior:
|
|
31
|
+
|
|
32
|
+
```text
|
|
33
|
+
idle -> pressed -> processing -> success | failure | cancelled
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
Add offline, permission-denied, empty, stale, and recovered states when reachable. Preserve input, selection, focus, scroll, navigation, and completed work through failure and rerender, and prevent duplicate and stale actions. Prefer native or semantic controls and the existing product design system. Respect Reduced Motion. Apply platform conventions and WCAG 2.2 requirements; do not imitate another vendor's visuals.
|
|
37
|
+
|
|
38
|
+
When requirements compete, prioritize safety and data preservation, accessibility, interaction correctness, user context, platform familiarity, performance, visual refinement, then decoration.
|
|
39
|
+
|
|
40
|
+
## Expert selection
|
|
41
|
+
|
|
42
|
+
Select one dominant expert for each UI component or cohesive flow, add at most two more only when the same WorkUnit genuinely crosses those risks, and record a concrete reason for each. Interactive UI changes also select `code.*` expertise. Tests, documentation and operations select expertise for their actual risks.
|
|
43
|
+
|
|
44
|
+
Do not read every UI reference “for completeness.” If implementation exposes a new risk, update the working plan and expert selection before reading the additional fragment.
|
|
45
|
+
|
|
46
|
+
## Expert index
|
|
47
|
+
|
|
48
|
+
| Expert ID | Select for | Read |
|
|
49
|
+
| --- | --- | --- |
|
|
50
|
+
| `ui.interaction.v1` | controls, feedback, targets, success, perceived responsiveness | [interaction-feedback.md](references/interaction-feedback.md) |
|
|
51
|
+
| `ui.async.v1` | loading, progress, retry, cancellation, concurrency, offline | [async-recovery.md](references/async-recovery.md) |
|
|
52
|
+
| `ui.forms.v1` | forms, validation, uploads, labels, disabled or empty states | [forms-and-controls.md](references/forms-and-controls.md) |
|
|
53
|
+
| `ui.accessibility.v1` | keyboard, focus, semantics, screen readers, contrast, motion | [accessibility-and-navigation.md](references/accessibility-and-navigation.md) |
|
|
54
|
+
| `ui.layout.v1` | responsive layout, zoom, content growth, platform adaptation | [responsive-and-platform.md](references/responsive-and-platform.md) |
|
|
55
|
+
| `ui.safety.v1` | destructive actions, permissions, user-work preservation, severity review | [safety-and-review.md](references/safety-and-review.md) |
|
|
56
|
+
|
|
57
|
+
Typical pairs: async Save button → `ui.interaction.v1` + `ui.async.v1`; validated settings form → `ui.forms.v1` + `ui.accessibility.v1`; delete flow → `ui.safety.v1` + `ui.interaction.v1`.
|
|
58
|
+
|
|
59
|
+
## Verification
|
|
60
|
+
|
|
61
|
+
For new or behaviorally changed actions, do not review screenshots alone: trace the affected activation, processing, success, failure, recovery, focus, and responsive behavior. For purely visual changes, use focused visual and accessibility checks. Read [ui-checklist.md](references/ui-checklist.md) for detailed review or final verification of affected interactions — a change crossing several `ui.*` risks, or the last check before accepting — not for a single visible change inside one expert's contract.
|
|
62
|
+
|
|
63
|
+
Report what was exercised in a running interface, what was inferred from source, and what remains unverified. A build, an API success, or a good screenshot alone does not prove UI correctness.
|
|
64
|
+
<!-- /kiokuko:runtime -->
|
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
<!-- KIOKUKO MANAGED STANDARD SKILL: kiokuko-ui-design-soul -->
|
|
2
|
+
|
|
3
|
+
# `ui.accessibility.v1` — accessibility, focus, and navigation
|
|
4
|
+
|
|
5
|
+
Select this expert when a flow depends on keyboard order, focus, screen-reader semantics, dynamic status, contrast, motion, dialogs, menus, or navigation continuity.
|
|
6
|
+
|
|
7
|
+
## Keyboard and focus
|
|
8
|
+
|
|
9
|
+
Primary functionality must be keyboard-operable where the platform supports it. Verify logical order, visible focus, expected activation keys, Escape behavior, no traps, and sensible focus restoration after dialogs, menus, sheets, or popovers close.
|
|
10
|
+
|
|
11
|
+
Do not remove focus outlines without an equally visible replacement. Do not move focus merely because content changed; move it only when that helps the next task.
|
|
12
|
+
|
|
13
|
+
## Semantics and announcements
|
|
14
|
+
|
|
15
|
+
Prefer native HTML or platform controls. Every interactive element needs a programmatic role and accessible name. Expose values, checked or selected states, expanded state, validation errors, progress, busy state, and material status changes.
|
|
16
|
+
|
|
17
|
+
Use ARIA only when native semantics are insufficient. Avoid redundant or contradictory attributes. Dynamic announcements must be timely without repeating every incidental update.
|
|
18
|
+
|
|
19
|
+
## Perception
|
|
20
|
+
|
|
21
|
+
For Web UI, target WCAG 2.2 AA or the project's stricter standard. Normal text generally needs 4.5:1 contrast, large text 3:1, and meaningful component boundaries or state indicators 3:1 where the criterion applies.
|
|
22
|
+
|
|
23
|
+
Do not communicate meaning through color, sound, motion, or shape alone. Respect Reduced Motion while preserving equivalent state information. Test zoom, increased text, long values, translated strings, and multiline labels.
|
|
24
|
+
|
|
25
|
+
## Navigation continuity
|
|
26
|
+
|
|
27
|
+
Back, browser history, deep links, tabs, modal dismissal, and async completion must preserve a coherent mental model. Closing transient UI should return focus appropriately. Data refresh must not unexpectedly navigate or reset the current item.
|
|
28
|
+
|
|
29
|
+
## Focused verification
|
|
30
|
+
|
|
31
|
+
Complete the primary flow keyboard-only, inspect visible focus and focus restoration, check names/roles/status with a screen reader, verify contrast and non-color cues, test 200% text resizing where WCAG applies, and exercise Reduced Motion.
|
|
@@ -0,0 +1,49 @@
|
|
|
1
|
+
<!-- KIOKUKO MANAGED STANDARD SKILL: kiokuko-ui-design-soul -->
|
|
2
|
+
|
|
3
|
+
# `ui.async.v1` — asynchronous state and recovery
|
|
4
|
+
|
|
5
|
+
Select this expert for save, submit, upload, download, import, export, search, AI generation, OCR, sync, authentication, or any user-triggered delayed work.
|
|
6
|
+
|
|
7
|
+
## State machine
|
|
8
|
+
|
|
9
|
+
List reachable states before implementation:
|
|
10
|
+
|
|
11
|
+
```text
|
|
12
|
+
idle -> pressed -> processing -> success | failure | cancelled
|
|
13
|
+
\-> offline | permission-denied | stalled
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
Define how each state is entered, rendered, announced, exited, retried, and cleaned up. Loading, empty, and failure must be distinguishable.
|
|
17
|
+
|
|
18
|
+
## Processing
|
|
19
|
+
|
|
20
|
+
- Acknowledge activation immediately; do not wait for the server.
|
|
21
|
+
- Use determinate progress only when it measures real progress. Never fake a percentage.
|
|
22
|
+
- Keep completed user work visible.
|
|
23
|
+
- Prevent accidental duplicate execution while leaving unrelated controls usable.
|
|
24
|
+
- For long work, update expectations and offer cancellation only when it truly stops or safely abandons the operation.
|
|
25
|
+
- State whether work continues in the background and provide completion feedback if users may leave the view.
|
|
26
|
+
|
|
27
|
+
## Concurrency and lifetime
|
|
28
|
+
|
|
29
|
+
Guard against double clicks, overlapping requests, stale responses, navigation, unmount, retry while active, and out-of-order completion. When only the newest result is valid, older results must not overwrite it.
|
|
30
|
+
|
|
31
|
+
Cancellation semantics must be exact. Hiding a dialog or ignoring a result is not cancellation of backend work unless communicated as such.
|
|
32
|
+
|
|
33
|
+
## Failure and recovery
|
|
34
|
+
|
|
35
|
+
On failure:
|
|
36
|
+
|
|
37
|
+
1. stop the busy state;
|
|
38
|
+
2. preserve input and completed work;
|
|
39
|
+
3. explain the affected action in user language;
|
|
40
|
+
4. place the message in the task context;
|
|
41
|
+
5. offer the next real action: Retry, Reconnect, Back, fix a field, choose another file, or save locally.
|
|
42
|
+
|
|
43
|
+
Do not represent failure only in logs, a rejected promise, a stopped spinner, or “Something went wrong” when a useful cause is known.
|
|
44
|
+
|
|
45
|
+
Offline queueing may be promised only when work is actually persisted. Permission denial should not cause repeated prompts; explain the limitation and recovery route.
|
|
46
|
+
|
|
47
|
+
## Focused verification
|
|
48
|
+
|
|
49
|
+
Test slow success, server failure, timeout, offline, cancellation, repeated activation, stale completion, unmount/navigation, recovery, and accessible status announcements.
|
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
<!-- KIOKUKO MANAGED STANDARD SKILL: kiokuko-ui-design-soul -->
|
|
2
|
+
|
|
3
|
+
# `ui.forms.v1` — forms, validation, and control states
|
|
4
|
+
|
|
5
|
+
Select this expert for data entry, validation, uploads, searchable controls, disabled behavior, and empty states.
|
|
6
|
+
|
|
7
|
+
## Form state
|
|
8
|
+
|
|
9
|
+
Define:
|
|
10
|
+
|
|
11
|
+
```text
|
|
12
|
+
pristine -> editing -> invalid | submitting -> submitted | failed
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
Use visible labels rather than placeholder-only labels. Make required state understandable without color alone. Validation must identify the affected field and tell users how to fix it without reporting errors prematurely.
|
|
16
|
+
|
|
17
|
+
Preserve entered values after validation or server failure. After failed submission, guide focus without stealing it unexpectedly. Keyboard submit behavior must be predictable; multiline input must not submit when a newline is expected.
|
|
18
|
+
|
|
19
|
+
## Submission and uploads
|
|
20
|
+
|
|
21
|
+
Submitting needs immediate acknowledgement and duplicate prevention. Success must be observable. Failure must retain the form and provide a recovery path.
|
|
22
|
+
|
|
23
|
+
For uploads show the chosen file, current state, measurable progress, failure and retry, and accurate cancellation semantics. Keep successful uploads when another file fails unless the product contract explicitly makes the batch atomic.
|
|
24
|
+
|
|
25
|
+
## Disabled and unavailable
|
|
26
|
+
|
|
27
|
+
A disabled control must look unavailable. If the reason is not obvious, make it discoverable. Do not use low opacity when it makes text illegible, and do not make silent refusal the only explanation. Hiding an action without context is often worse than exposing the requirement near it.
|
|
28
|
+
|
|
29
|
+
## Empty and loading states
|
|
30
|
+
|
|
31
|
+
An empty state should say what is absent, why when useful, and the next real action. Loading must not look like empty or broken content. Prefer local placeholders and layout stability over blocking the whole screen for one region.
|
|
32
|
+
|
|
33
|
+
## Focused verification
|
|
34
|
+
|
|
35
|
+
Test pristine, partially entered, invalid, keyboard submission, slow submission, server failure, preserved values, focus after error, success, disabled explanation, empty state, and upload retry/cancellation where applicable.
|
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
<!-- KIOKUKO MANAGED STANDARD SKILL: kiokuko-ui-design-soul -->
|
|
2
|
+
|
|
3
|
+
# `ui.interaction.v1` — controls and perceivable feedback
|
|
4
|
+
|
|
5
|
+
Select this expert when users activate buttons, links, menus, tabs, toolbars, gestures, list rows, or other controls.
|
|
6
|
+
|
|
7
|
+
## Interaction contract
|
|
8
|
+
|
|
9
|
+
Every activation must produce immediate perceivable acknowledgement before slow work completes. A network request or callback beginning in the background is not feedback.
|
|
10
|
+
|
|
11
|
+
Use the lightest truthful signal:
|
|
12
|
+
|
|
13
|
+
- pressed or active state for immediate actions;
|
|
14
|
+
- changed label, local spinner, status, or optimistic state for perceptible delay;
|
|
15
|
+
- visible navigation or content change when the result is self-evident;
|
|
16
|
+
- accessible status text when visual change alone is ambiguous.
|
|
17
|
+
|
|
18
|
+
Do not force a second click merely to discover whether the first worked. Clear busy and disabled states after success or failure. Avoid noisy success toasts when the result itself is obvious.
|
|
19
|
+
|
|
20
|
+
## Controls and targets
|
|
21
|
+
|
|
22
|
+
Prefer native or semantic controls. Labels should predict the action: “Save changes” or “Delete project” is stronger than “OK.”
|
|
23
|
+
|
|
24
|
+
Judge the effective hit target, not icon artwork. Use platform defaults first. On touch-oriented Web UI, aim around 44×44 CSS px when practical; WCAG 2.2's 24×24 criterion is a floor with exceptions, not the general design target. On Apple platforms prefer standard control sizes; do not shrink ordinary controls to the minimum.
|
|
25
|
+
|
|
26
|
+
For icon-only controls provide an accessible name, enough context, an expanded target, and pointer discoverability such as a tooltip when useful. Essential actions must not depend on hover or a precision gesture.
|
|
27
|
+
|
|
28
|
+
## Locality and context
|
|
29
|
+
|
|
30
|
+
Keep feedback near the initiating control or affected content. Block duplicates of the same operation without disabling unrelated areas. Preserve selection, focus, scroll, cursor, filters, and current item through local updates.
|
|
31
|
+
|
|
32
|
+
## Focused verification
|
|
33
|
+
|
|
34
|
+
Exercise pointer, keyboard, and touch when supported. Verify visible focus, immediate acknowledgement, target size and spacing, duplicate activation, success visibility, and the user's retained context after rerender.
|
|
@@ -0,0 +1,38 @@
|
|
|
1
|
+
<!-- KIOKUKO MANAGED STANDARD SKILL: kiokuko-ui-design-soul -->
|
|
2
|
+
|
|
3
|
+
# `ui.layout.v1` — responsive behavior and platform adaptation
|
|
4
|
+
|
|
5
|
+
Select this expert for breakpoints, multi-pane collapse, viewport overlays, safe areas, touch/pointer adaptation, content growth, or cross-platform behavior.
|
|
6
|
+
|
|
7
|
+
## Functional responsiveness
|
|
8
|
+
|
|
9
|
+
Responsive design must preserve capability, not merely eliminate horizontal overflow. At each supported size verify:
|
|
10
|
+
|
|
11
|
+
- the primary action remains visible or readily reachable;
|
|
12
|
+
- navigation remains understandable;
|
|
13
|
+
- important information is not silently removed;
|
|
14
|
+
- controls remain discoverable and comfortable;
|
|
15
|
+
- overlays fit the viewport;
|
|
16
|
+
- fixed bars do not cover content;
|
|
17
|
+
- safe areas are respected;
|
|
18
|
+
- current selection and navigation context survive layout changes.
|
|
19
|
+
|
|
20
|
+
If a desktop multi-pane layout collapses to one pane, preserve the current item and provide a clear route back. Do not simply remove desktop functionality on mobile without an intentional replacement.
|
|
21
|
+
|
|
22
|
+
## Content growth
|
|
23
|
+
|
|
24
|
+
Test increased text, browser zoom, long data, translations, dynamic content, and multiline labels. Avoid fixed heights that clip required content. Truncation must not hide information needed to complete the task.
|
|
25
|
+
|
|
26
|
+
## Platform conventions
|
|
27
|
+
|
|
28
|
+
Use the existing product design system and adapt interaction to the target platform:
|
|
29
|
+
|
|
30
|
+
- Apple platforms: native controls, standard navigation, accessibility behavior, keyboard/pointer conventions, and normal control sizes;
|
|
31
|
+
- Web: semantic HTML, browser behavior, WCAG 2.2, responsive URL-aware navigation, pointer, touch, and keyboard;
|
|
32
|
+
- cross-platform: preserve product identity without forcing identical behavior where platform expectations differ.
|
|
33
|
+
|
|
34
|
+
HIG principles are decision filters, not a request for iOS styling on the Web.
|
|
35
|
+
|
|
36
|
+
## Focused verification
|
|
37
|
+
|
|
38
|
+
Exercise the narrowest and widest supported layouts with real and long content, touch and pointer when applicable, zoom or dynamic type, overlays near viewport edges, orientation or pane changes, and context preservation across breakpoint transitions.
|
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
<!-- KIOKUKO MANAGED STANDARD SKILL: kiokuko-ui-design-soul -->
|
|
2
|
+
|
|
3
|
+
# `ui.safety.v1` — destructive actions, permissions, and review severity
|
|
4
|
+
|
|
5
|
+
Select this expert when an interaction can lose data, change permissions, expose privacy-sensitive information, interrupt unsaved work, or block a primary flow.
|
|
6
|
+
|
|
7
|
+
## User-work preservation
|
|
8
|
+
|
|
9
|
+
Preserve form values, edits, generated content, selection, cursor, scroll, filters, and completed work through failure, refresh, navigation, and recovery. A technically successful action that loses the user's place is still defective.
|
|
10
|
+
|
|
11
|
+
Warn about unsaved work only when loss is real. Prefer persistence or recovery over repeated confirmation friction.
|
|
12
|
+
|
|
13
|
+
## Destructive actions
|
|
14
|
+
|
|
15
|
+
Prefer Undo for safely reversible operations. Use explicit confirmation when harm is material, recovery is unavailable, or scope may surprise users. Name the action, count or scope, consequence, and destructive button:
|
|
16
|
+
|
|
17
|
+
```text
|
|
18
|
+
Delete 14 documents?
|
|
19
|
+
This permanently removes them from this workspace.
|
|
20
|
+
[Cancel] [Delete 14 documents]
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
Do not use vague “Are you sure?” dialogs or place destructive actions where common actions are easy to hit accidentally. Do not add confirmation to harmless actions by habit.
|
|
24
|
+
|
|
25
|
+
## Permissions and privacy
|
|
26
|
+
|
|
27
|
+
Request permission in context and explain why it is needed. After denial, do not repeatedly trigger the system prompt; explain the unavailable capability and provide a safe Settings route or alternative when one exists. Never imply permission, persistence, encryption, background continuation, or cancellation that the system does not provide.
|
|
28
|
+
|
|
29
|
+
## Review severity
|
|
30
|
+
|
|
31
|
+
- **BLOCKER:** data loss, irreversible unintended action, inaccessible or impossible primary flow, privacy/security harm, or indefinite ambiguity about an important action.
|
|
32
|
+
- **MAJOR:** invisible async work, duplicate submission, missing recovery, lost input/context, tiny primary target, inaccessible primary operation, hidden mobile functionality, or unprotected destructive behavior.
|
|
33
|
+
- **MINOR:** non-critical copy, spacing, motion, or secondary discoverability that does not block or mislead.
|
|
34
|
+
|
|
35
|
+
Review actual interaction behavior, not screenshots alone. Trace discovery, activation, processing, duplicate/stale execution, success, failure, recovery, preserved work, focus, and supported layouts.
|
|
36
|
+
|
|
37
|
+
## Focused verification
|
|
38
|
+
|
|
39
|
+
Test destructive scope and cancellation, Undo or recovery, failed save after editing, navigation with unsaved work, permission denial and repeat entry, privacy-sensitive output, and the complete primary flow. Do not approve with a known blocker.
|
|
40
|
+
|
|
41
|
+
## Focused engineering practice
|
|
42
|
+
|
|
43
|
+
For bot-triggering controls, keep credentials server-side and treat webhook bodies as untrusted. Define acknowledgment, progress, cancellation and failure recovery. Do not invent a provider endpoint, expose a listener or install a tunnel without authorized configuration.
|
|
@@ -0,0 +1,75 @@
|
|
|
1
|
+
<!-- KIOKUKO MANAGED STANDARD SKILL: kiokuko-ui-design-soul -->
|
|
2
|
+
|
|
3
|
+
# UI design and review checklist
|
|
4
|
+
|
|
5
|
+
Last reviewed against the official sources: 2026-08-22.
|
|
6
|
+
|
|
7
|
+
This checklist paraphrases decision principles. It does not reproduce Apple text or require Apple-styled visuals.
|
|
8
|
+
|
|
9
|
+
Read this file for detailed implementation review or final verification of affected interactions. For a single visible change inside one expert's contract, the selected `ui.*` fragment and its universal-core checks are sufficient.
|
|
10
|
+
|
|
11
|
+
## Required GUI and CLI interaction checks
|
|
12
|
+
|
|
13
|
+
Apply these requirements to graphical interfaces and command-line interfaces alike:
|
|
14
|
+
|
|
15
|
+
- **Visible choices:** show the available, task-relevant choices whenever practical. Do not require users to guess valid values or memorize identifiers when the application already knows the options. Group, filter, search, or paginate large sets so choices remain discoverable.
|
|
16
|
+
- **Easy selection:** provide suitable shortcuts, numbered menus, or checkbox lists instead of unnecessary free-text entry. Show the relevant keys or gestures beside the choices. Distinguish single selection from multiple selection, make the current selection visible, and make confirmation and cancellation clear. For interactive CLIs, use number keys or arrow navigation, Space to toggle, and Enter to confirm where appropriate.
|
|
17
|
+
- **Visible progress and state:** acknowledge the action promptly and show intermediate status during slow work. Display measured progress when available; otherwise show the current phase or an honest activity indicator. Make completion, failure, cancellation, and stalled work distinguishable; do not leave users guessing whether processing has started or finished.
|
|
18
|
+
- **Useful error causes:** display what failed, its known cause, and the next available recovery action. A generic failure message, error code, or log entry alone is insufficient when the cause is known. If the cause is unknown, say so and give a useful diagnostic next step rather than inventing an explanation. Keep secrets out of messages.
|
|
19
|
+
|
|
20
|
+
For non-interactive CLI use, keep explicit flags or input formats available instead of forcing a prompt. Preserve the command's output contract: progress and diagnostics must not corrupt machine-readable output; use the documented diagnostic channel, typically stderr, and disable terminal animation when no TTY is available.
|
|
21
|
+
|
|
22
|
+
## Eight-principle map
|
|
23
|
+
|
|
24
|
+
| Principle | Practical question |
|
|
25
|
+
| --- | --- |
|
|
26
|
+
| Purpose | Does every important element help the user complete the primary task? |
|
|
27
|
+
| Agency | Can the user understand, initiate, interrupt where safe, and recover from actions? |
|
|
28
|
+
| Responsibility | Does the interface protect privacy, attention, safety, and user-created work? |
|
|
29
|
+
| Familiarity | Do labels, controls, navigation, and feedback follow the target platform's conventions? |
|
|
30
|
+
| Flexibility | Does the flow adapt to ability, input method, device, content size, and context? |
|
|
31
|
+
| Simplicity | Is the next meaningful action clear without hiding necessary information or control? |
|
|
32
|
+
| Craft | Are states, spacing, copy, timing, focus, and edge cases implemented consistently? |
|
|
33
|
+
| Delight | Does successful, calm, recoverable use feel better because the details work together? |
|
|
34
|
+
|
|
35
|
+
## State coverage
|
|
36
|
+
|
|
37
|
+
For each primary action, verify the applicable states:
|
|
38
|
+
|
|
39
|
+
- **Actionable:** the label predicts the result; enabled and disabled states are distinguishable without color alone.
|
|
40
|
+
- **Pressed and focused:** feedback is immediate; keyboard focus is visible; focus order follows the task.
|
|
41
|
+
- **Processing:** status remains near the initiating control; duplicate submission is prevented without trapping the user.
|
|
42
|
+
- **Progress:** measurable work uses a determinate value; unmeasurable work uses an indeterminate indicator and an accessible status message.
|
|
43
|
+
- **Long or stalled work:** expectations are updated; a reason and next step are shown; cancellation is available only when it is safe and real.
|
|
44
|
+
- **Success:** completion is perceivable visually and programmatically; the interface moves focus only when that helps the next task.
|
|
45
|
+
- **Empty:** the state explains what is absent and offers a relevant next action rather than presenting a dead end.
|
|
46
|
+
- **Failure:** input and completed work are retained; the message says what happened in actionable language; retry, undo, or back is available where meaningful.
|
|
47
|
+
- **Offline:** unavailable behavior is explicit; queued or local work is not implied unless it is actually preserved.
|
|
48
|
+
- **Permission denied:** explain the missing capability and provide a safe route to settings, an alternative, or back.
|
|
49
|
+
- **Destructive:** communicate scope and consequence; prefer undo for reversible actions and use explicit confirmation for material irreversible harm.
|
|
50
|
+
- **Recovered:** clear stale errors and busy states; restore a coherent focus position; avoid re-running the action unexpectedly.
|
|
51
|
+
|
|
52
|
+
## Accessibility and adaptation
|
|
53
|
+
|
|
54
|
+
- Use semantic HTML or native controls before recreating their behavior.
|
|
55
|
+
- Verify the full primary flow with keyboard only, including visible focus and escape from overlays.
|
|
56
|
+
- Verify names, roles, values, errors, progress, and status announcements with a screen reader.
|
|
57
|
+
- Test touch, pointer, keyboard, and relevant alternate input; do not require hover, precise pointing, or a single gesture.
|
|
58
|
+
- Test narrow and wide layouts, zoom or text resizing, longer translated copy, and dynamic content.
|
|
59
|
+
- Do not encode meaning with color, motion, shape, or sound alone.
|
|
60
|
+
- Respect Reduced Motion and provide equivalent state information without animation.
|
|
61
|
+
- Keep time limits adjustable or avoid them unless the task itself requires one.
|
|
62
|
+
- On the web, apply the existing design system and WCAG 2.2; do not imitate iOS merely because these principles originated in Apple HIG.
|
|
63
|
+
|
|
64
|
+
For an asynchronous action, run the `ui.async.v1` state, processing, and recovery contract in [async-recovery.md](async-recovery.md) against the flow.
|
|
65
|
+
|
|
66
|
+
## Official sources
|
|
67
|
+
|
|
68
|
+
- Apple Human Interface Guidelines — Design principles: https://developer.apple.com/design/human-interface-guidelines/design-principles
|
|
69
|
+
- Apple Human Interface Guidelines — Buttons: https://developer.apple.com/design/human-interface-guidelines/buttons
|
|
70
|
+
- Apple Human Interface Guidelines — Loading: https://developer.apple.com/design/human-interface-guidelines/loading
|
|
71
|
+
- Apple Human Interface Guidelines — Progress indicators: https://developer.apple.com/design/human-interface-guidelines/progress-indicators
|
|
72
|
+
- Apple Human Interface Guidelines — Feedback: https://developer.apple.com/design/human-interface-guidelines/feedback
|
|
73
|
+
- Apple Human Interface Guidelines — Motion: https://developer.apple.com/design/human-interface-guidelines/motion
|
|
74
|
+
- Apple Human Interface Guidelines — Accessibility: https://developer.apple.com/design/human-interface-guidelines/accessibility
|
|
75
|
+
- W3C Web Content Accessibility Guidelines 2.2: https://www.w3.org/TR/WCAG22/
|
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: kiokuko-verification
|
|
3
|
+
description: Create or maintain a project-specific recipe that exercises real user-visible behavior.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
<!-- KIOKUKO MANAGED STANDARD SKILL: kiokuko-verification -->
|
|
7
|
+
|
|
8
|
+
<!-- kiokuko:runtime contract -->
|
|
9
|
+
# Verification
|
|
10
|
+
|
|
11
|
+
Follow SOUL and the current host directive. This skill grants no extra permissions, model changes or delegation. Use the current model and proportionate evidence.
|
|
12
|
+
|
|
13
|
+
Inspect existing launch commands and test drivers before introducing tools. Define launch readiness, exercise steps, expected results, evidence, isolation and cleanup. Reuse the project test harness. Create a project-local verify skill only when requested; use the repository convention or .agents/skills/verify-<app>/SKILL.md. Never overwrite an unmanaged recipe.
|
|
14
|
+
|
|
15
|
+
## Completion
|
|
16
|
+
|
|
17
|
+
Maintain a feature map with entry points and repeatable recipes. Exercise each claimed covered feature. Distinguish doc drift from product regression; report the latter without rewriting expectations to hide it. Report clean, changed or blocked, plus coverage gaps. Cleanup only resources created by this verification.
|
|
18
|
+
|
|
19
|
+
Read [worked cases](references/cases.md) only when the decision or failure boundary is unclear. Do not load unrelated specialists or repeat completed checks without new evidence.
|
|
20
|
+
<!-- /kiokuko:runtime -->
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
<!-- KIOKUKO MANAGED STANDARD SKILL: kiokuko-verification -->
|
|
2
|
+
|
|
3
|
+
# Decision example
|
|
4
|
+
|
|
5
|
+
The feature map says failed Save preserves input, but a live check loses it.
|
|
6
|
+
|
|
7
|
+
Report a product regression with the reproduction. Do not rewrite the map to bless data loss. Keep recipe corrections separate from product changes.
|
|
8
|
+
|
|
9
|
+
## Non-trigger
|
|
10
|
+
|
|
11
|
+
A mechanical edit with known behavior uses the existing simple-work and code contracts. Do not turn it into a panel, benchmark or architecture exercise.
|