Sk Code Mobile Cli

mobile-cli Surface — Pi Remote Design-System and Svelte Evidence

Read-only evidence for code work on the Pi Remote Mobile-CLI app (app-mobile/ and its relay peer app-relay/, with the shared protocol in packages/pi-rpc-protocol/). The shipped web surface is a SvelteKit app with Svelte runes and component-scoped styles. When the hub bundles this surface, a code workflow gains the app's formalized design system, source-tree conventions, natural inline-comment grammar, guardrails that keep designer edits out of logic and the security boundary, and the browser-free verification gate this codebase actually uses.

---

1. WHEN THE HUB BUNDLES THIS

• The task's CWD or changed/target files sit under app-mobile/, app-relay/, or

packages/pi-rpc-protocol/ in the Mobile CLI app repository. The hub's surface detection resolves PI_REMOTE.

• The active workflow phase needs the app's design-system evidence: the primitive → semantic →

component token model, the natural inline-comment editability convention, the Do not edit — guardrail notes, or the browser-free verification gate.

• The active workflow needs the shipped Svelte source grammar: kebab-case names, SvelteKit route

exemptions, runes lifecycle rules, shared-folder ownership, section banners, or paired source-folder documentation.

• This surface never owns edits, tests, or verification itself. The bundled workflow mode does the

work (for example, sk-code-quality or sk-code-review) and this packet supplies the evidence it must honor. A typical resolution is [sk-code-quality, sk-code-mobile-cli] or [sk-code-review, sk-code-mobile-cli].

This packet is advisor-invisible (routingClass: metadata) and read-only. It never routes as a primary and mutates nothing. It supplies evidence while the acting workflow applies it.

---

2. REFERENCE MAP

| Folder | Read first | What the folder carries | | --- | --- | --- | | references/design-system/ | [design-system.md](references/design-system/design-system.md) | How the app looks. The three-layer token model (token-library), per-surface Layer-3 families (component-tokens), the light/dark role remap (theme-remap), two worked retints (retint-recipes), which file a rule belongs in (scoped-style-ownership), and the block--element class grammar (css-class-naming-bem). | | references/verification/ | [verification.md](references/verification/verification.md) | Proving a change. The browser-free resolver method, the value oracle, the CDP structural gates and the workspace gate in one document, plus the cross-repo path drift guard (skill-reference-integrity). | | references/conventions/ | [conventions.md](references/conventions/conventions.md) | How source reads. Banner and comment grammar (comment-grammar), the Do not edit — fences (editability-guardrails), and when a folder owes a CODE.md (folder-docs). | | references/svelte/ | [svelte.md](references/svelte/svelte.md) | Runtime correctness a green suite cannot see, in one document: the $effect self-invalidation trap and the untrack doctrine, then the react-aria → bits-ui accessibility contract and the four interaction actions. | | references/storybook/ | [storybook.md](references/storybook/storybook.md) | The component catalog and its screenshot archive: both audiences, the gates in the order they bite (component-story-upkeep, screenshot-archive), how to start it for someone (running-storybook), and the generated-versus-written split of its docs pages (docs-layer). | | references/operations/ | [operations.md](references/operations/operations.md) | Running the live relay: incident-playbooks, rollback. | | references/setup/ | [setup.md](references/setup/setup.md) | First run: install-and-onboarding, and putting the whole app on a phone-shaped screen — Chrome emulation, the iOS Simulator, an Android emulator, or a real phone (device-preview). | | references/standards/ | — | The rules a change must hold: code-standards, security, platform-support. | | references/release/ | — | Shipping a build: ai-deploy-playbook, release-verification. | | references/quality/ | — | [doc-quality-gate.md](references/quality/doc-quality-gate.md) — the DQI scorer, the bar, and the check a reviewer applies. [pi-remote-full-access-runtime-baseline.md](references/quality/pi-remote-full-access-runtime-baseline.md) — the operator-run evidence that the relay launched full-access Pi RPC. | | references/workflow-*.md | — | The shared implement → debug → verify doctrine (symlinked from ../../shared/references/). |

Every folder above whose "Read first" cell names a document follows the same /.md pattern, but that document plays one of two roles and it is worth knowing which. In conventions/, design-system/, storybook/, operations/ and setup/ it is a router: it opens with a table that picks a sibling by what you are doing, so one read reaches the right contract instead of scanning filenames. In verification/ and svelte/ it is the document itself — those subjects were small enough that a router above two files cost more than it saved, so the content was merged and the entry is simply where it lives.

Checklists (assets/) and the source-gates runner (scripts/) — token retint, guardrail audit, DS verification, BEM rename, runes-effect audit, story coverage, a11y parity, and run-source-gates.sh. See §4 for the full list.

The feature catalog and the manual testing playbook are the single source of truth at the app repository root (feature-catalog/ and manual-testing-playbook/). This surface does not mirror them, so the evidence cannot drift from the shipped app.

The live design-system evidence lives in the app repository, not in this packet: feature-catalog/design-system/token-library.md (token catalogue), feature-catalog/design-system/designer-editability.md (designer editability guide), and app-mobile/catalog.html (the live catalog — every migrated surface in every state, light and dark).

---

2b. SMART ROUTING (machine-readable)

This block is the deterministic projection of code-mobile-cli's own intent → reference/asset routing, consumed by the skill-benchmark router-replay. Keep it in sync with the parent hub union.

# code-mobile-cli owns its intent -> reference/asset routing. Paths are relative to
# this skill root. The parent sk-code hub RESOURCE_MAP is the union of this map
# (re-prefixed with sk-code-mobile-cli/) and the sibling surface maps plus the
# parent-owned universal/shared tier. A drift guard enforces that equality.
DEFAULT_RESOURCE = [
    "references/design-system/design-system.md",
    "references/conventions/conventions.md",
]

INTENT_SIGNALS = {
    "IMPLEMENTATION":     {"weight": 1, "keywords": ["retint", "token edit", "component token", "semantic role", "presentation seam", "presentation comment", "css custom property", "implement", "build", "primitive", "theme remap"]},
    "CODE_QUALITY":       {"weight": 1, "keywords": ["guardrail", "do-not-edit", "lint", "quality gate", "frozen value", "code smell", "naming", "folder docs", "comment grammar"]},
    "DEBUGGING":          {"weight": 1, "keywords": ["debug", "broken", "regression", "wrong theme", "unexpected color", "leaking retint", "orphaned reference", "self-invalidation", "effect loop"]},
    "VERIFICATION":       {"weight": 1, "keywords": ["verify", "resolver", "value-preservation", "contrast", "wcag", "type-check", "test:web", "completion claim", "browser-free", "scan-skill-references"]},
    "LANGUAGE_STANDARDS": {"weight": 1, "keywords": ["Svelte", "SvelteKit", "runes", "$state", "$derived", "$effect", "untrack", "scoped style", "app.css", "kebab-case", "MODULE", "section divider", "folder docs", "contrast.test.ts"]},
    "ACCESSIBILITY":      {"weight": 1, "keywords": ["a11y", "accessibility", "reduced motion", "prefers-contrast", "forced-colors", "focus ring", "target size", "44px", "wcag aa"]},
}

RESOURCE_MAP = {
    "IMPLEMENTATION": [
        "references/design-system/design-system.md",
        "references/design-system/token-library.md",
        "references/conventions/comment-grammar.md",
        "references/design-system/component-tokens.md",
        "references/design-system/retint-recipes.md",
        "references/design-system/theme-remap.md",
        "references/design-system/scoped-style-ownership.md",
        "assets/token-retint-checklist.md",
    ],
    "CODE_QUALITY": [
        "references/conventions/conventions.md",
        "references/storybook/running-storybook.md",
        "references/conventions/editability-guardrails.md",
        "references/design-system/css-class-naming-bem.md",
        "references/conventions/comment-grammar.md",
        "references/conventions/folder-docs.md",
        "references/storybook/storybook.md",
        "references/storybook/component-story-upkeep.md",
        "references/storybook/screenshot-archive.md",
        "references/storybook/docs-layer.md",
        "assets/guardrail-audit-checklist.md",
        "assets/bem-rename-checklist.md",
        "assets/story-coverage-checklist.md",
    ],
    "DEBUGGING": [
        "references/svelte/svelte.md",
        "references/verification/verification.md",
        "references/design-system/component-tokens.md",
        "assets/runes-effect-audit-checklist.md",
    ],
    "VERIFICATION": [
        "references/verification/verification.md",
        "references/setup/device-preview.md",
        "references/verification/skill-reference-integrity.md",
        "assets/ds-verification-checklist.md",
    ],
    "LANGUAGE_STANDARDS": [
        "references/design-system/token-library.md",
        "references/design-system/component-tokens.md",
        "references/design-system/theme-remap.md",
        "references/design-system/scoped-style-ownership.md",
        "references/design-system/css-class-naming-bem.md",
        "references/svelte/svelte.md",
        "references/conventions/comment-grammar.md",
        "references/conventions/folder-docs.md",
    ],
    "ACCESSIBILITY": [
        "references/conventions/editability-guardrails.md",
        "references/verification/verification.md",
        "references/svelte/svelte.md",
        "assets/a11y-parity-checklist.md",
    ],
}

---

3. SURFACE STANDARDS (the non-negotiables)

These are frozen by the design and security contracts the app ships under. A workflow bundling this surface MUST honor them:

• Token values are frozen. The 8 --pi-* primitives (ink-on-parchment, Inter + Source Serif 4)

are the palette contract. Retint a semantic role or a component token, never a --pi-* value.

• Natural comments mark the seams. A nearby purpose comment identifies the surface, slot, state,

variant, token, theme, catalog, or layout presentation that may change. A frozen line or region begins with Do not edit — (frozen primitives, focus ring, reduced-motion/contrast/forced-colors, ≥44px targets, per-surface state machines + status text, plan-mode overlay + atomic execute path, redaction chip, bounded-reading overflow) and is off-limits.

• CSS/token edits are presentation-only. They cannot reach state computation, the mutation/ticket

path, redaction, or plan-mode enforcement. That logic lives in TypeScript and Svelte modules, never in a component's style block.

• WCAG AA holds in both themes, controls stay ≥44px, and clay is never the sole state signal.
• CSS ownership is scoped. Every surface's CSS lives in its component's scoped `` block.

app-mobile/src/app.css holds only rules shared by two or more renderers, including shared tokens, theme remaps, and resets.

• Every component change updates its story. Adding or changing a renderable component includes

creating or updating its co-located *.stories.ts (scaffold: npm run story:new), so the Storybook catalog stays trustworthy; the coverage gate (npm run story:coverage) enforces it and a red coverage gate is a failing test. A story must show what the app actually renders — never invented values. See the repo-root STORYBOOK.md.

• Verification is browser-free. Because the app's strict CSP renders it unstyled under headless CDP,

value-preservation is proven by resolving app-mobile/src/app.css together with the changed component's scoped ` block to final values per theme, not by screenshots. Structural mount checks run against the built output. npm run typecheck, build, and test:web (including app-mobile/tests/contrast.test.ts) gate every change. See references/verification/verification.md`.

---

3b. SOURCE TREE CONVENTIONS (the shipped grammar)

This is the current source authority for the Mobile CLI tree. Apply it together with the frozen design and security standards above. Each convention below has a detailed, executable-backed reference pulled on demand — references/design-system/scoped-style-ownership.md, references/design-system/css-class-naming-bem.md, references/svelte/svelte.md, references/conventions/comment-grammar.md, and references/conventions/folder-docs.md.

Naming and routing

• Kebab-case applies everywhere under app-mobile/src/ except app-mobile/src/routes/**. This

includes Svelte components, TypeScript modules, stories, workers, and .svelte.ts runes twins.

• The routes/** exemption is deliberate. SvelteKit reads +page, +layout, +error, and

[param] segments as routing directives. Renaming one changes the URL contract, so those reserved names remain exactly as SvelteKit requires them.

• The kind comes first in a component name, from the closed list: sheet-, menu-, dialog-,

card-, button-, toggle-, radio-, screen-. Use sheet-model-effort.svelte for model-effort sheets. A prefix search then reaches every instance of a kind.

• Screens carry screen-: screen-chat.svelte, screen-home.svelte, screen-review.svelte,

screen-attention-inbox.svelte, and screen-enrollment.svelte. A screen is a kind like any other.

• Feature components take no prefix, because the feature name already identifies the thing. Only an

instance of a listed kind leads with that kind.

• The grammar is executable. scripts/naming/scan-naming.mjs reports any in-scope path that does not

match, and renames are generated from a manifest rather than typed by hand.

The package surface is the single packages/pi-rpc-protocol/ package. Do not infer sibling packages from the workspace wildcard. No .tsx remains under app-mobile/: the contrast gate is app-mobile/tests/contrast.test.ts, and the .test.tsx glob was dropped when the last JSX-using test was renamed to .test.ts.

Shared ownership

app-mobile/src/shared/ is grouped by one reason to change, not by an abstract layer split:

| Folder | Changes when | | --- | --- | | transport/ | The relay, auth, cache, or browser I/O contract changes. | | state/ | A reducer, state machine, or reactive state projection changes. | | commands/ | Host-command or slash-command behavior changes. | | catalog/ | Model, effort, or design-system catalog data changes. | | format/ | Display formatting or view-model shaping changes. | | viewport/ | Keyboard-safe visual viewport behavior changes. | | fixtures/ | Offline demo or story data changes. | | primitives/ | Reusable interaction primitives change. | | chrome/ | App-wide shell, status, theme, or header surfaces change. |

Keep feature-specific composition in app-mobile/src/pages/. A module belongs in the shared folder whose reason to change matches the change. The grouping is an ownership boundary, not a claim that all shared code has the same runtime layer.

Styles: scoped `` blocks

Each component's styles live in a component-scoped ` block inside its .svelte` file — Svelte scopes those rules to the component, so a class name is local

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: MichelKerkmeester
• Source: MichelKerkmeester/skilled-harness_spec-driven-agent-loops
• License: MIT

Install and usage instructions live in the source repository linked above.