slicc
CLAUDE.md37 starsChanged 20 days agoApache-2.0View on GitHub
Repo navigation hub. Keep package details in the nearest package CLAUDE.md and fast-changing how-to in docs/. Purposes per package: docs/root-details.md. Per-package internals: each packages/<name>/CLAUDE.md. Other top-level: docs/ (long-form docs + screenshots), packages/*/tests/ (Vitest suites), dist/ (generated; do not hand-edit). Runtime-specific guides: webapp · cherry · cloudflare-worker · node-server · cloud-core · shared-ts · webcomponents · spoon · vfs-root · go-optel · swift-launcher · swift-optel · swift-server · swift-traysession · swift-trayfollower · swift-traykit · swift-widgetkit · ios-app · slicc-cli · github-workflow…
- Installs packages
In this repository9 other files it gives its agents.
- docs/CLAUDE.mdCLAUDE.md
- .github/copilot-instructions.mdCopilot instructions
- adding-slicc-featuresSkill
- cdp-smoke-testSkill
- demo-recordingSkill
- deploying-tray-workerSkill
- slicc-handoffSkill
- verifying-before-pushSkill
- writing-slicc-testsSkill
The file
We split this CLAUDE.md into the rules it gives an agent
11 rules. About 0 are common, 2 are distinctive, and 9 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
9
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- could be automatic: a setting could enforce it
- Very specific: line 41
Use ice cream terms in review comments and docs when they match the domain (e.g., feed_scoop not delegate_to_scoop).
- Distinctive: line 45
Keep commits focused and package-local when possible.
- Very specific: line 47
Do not hand-edit generated output in dist/.
- Very specific: line 77
Model ID aliases: use pi-ai aliases (e.g., claude-opus-4-6), not dated snapshot IDs.
- Distinctive: line 82
Every change must satisfy tests, docs, and verification.
- Very specific: line 86
Add/update tests for behavior changes.
- Very specific: line 101
Run the full pre-push/PR pass — lint (first.
- Very specific: line 107
Add/change a SLICC feature surface → use adding-slicc-features
- Very specific: line 112
Write/update SLICC tests → use writing-slicc-tests
- Very specific: line 113
Commit, push, open/update a PR, diagnose verification CI failures → use verifying-before-push
- Very specific: line 134
When you change a category, update docs/review-patterns.md (source of truth) and the ≤4,000-char .github/copilot-instructions.md so all …
≈ “Common” is an estimate: at least 1 in 5 of the 28,029 CLAUDE.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
CLAUDE.md
Repo navigation hub. Keep package details in the nearest package CLAUDE.md and fast-changing how-to in docs/.
Module Map
Purposes per package: docs/root-details.md. Per-package internals: each packages/<name>/CLAUDE.md.
- Web / TS:
packages/webapp/,packages/webcomponents/,packages/cherry/,packages/spoon/(the Chrome extension lives in ai-ecoverse/slicc-extension) - Node / cloud:
packages/node-server/,packages/cloudflare-worker/,packages/cloud-core/,packages/shared-ts/,packages/vfs-root/,packages/dev-tools/,packages/assets/,packages/github-workflow/,packages/bench/ - Native (Swift / iOS / Go):
packages/swift-launcher/,packages/swift-server/,packages/swift-optel/,packages/swift-traysession/,packages/swift-trayfollower/,packages/swift-traykit/,packages/swift-widgetkit/,packages/ios-app/,packages/slicc-cli/,packages/go-optel/
Other top-level: docs/ (long-form docs + screenshots), packages/*/tests/ (Vitest suites), dist/ (generated; do not hand-edit).
Top-Level Commands
npm install # Install dependencies (first time)
npm run build # Production build (all workspaces)
npm run build -w @slicc/webapp # UI-only build (faster for UI changes)
npm run test # Vitest run
npm run typecheck # Browser + Node typecheck
npm run dev # Thin /cdp bridge + Chrome (UI from hosted origin)Runtime-specific guides: webapp · cherry · cloudflare-worker · node-server · cloud-core · shared-ts · webcomponents · spoon · vfs-root · go-optel · swift-launcher · swift-optel · swift-server · swift-traysession · swift-trayfollower · swift-traykit · swift-widgetkit · ios-app · slicc-cli · github-workflow · bench · dev-tools · docs
External Handoffs
handoff to slicc / move this to slicc opens https://www.sliccy.ai/handoff?handoff=<text> (or ?upskill=<url>) with a handoff:/upskill: verb-prefixed instruction. Worker returns an RFC 8288 Link header SLICC observes on navigation for approval. Prefer .agents/skills/slicc-handoff/scripts/slicc-handoff.
Ice Cream Vocabulary
- Cone: main agent. Full filesystem access, all tools.
- Scoops: isolated sub-agents; sandboxed filesystems (
/scoops/{name}/+/shared/). Tools:scoop_scoop,feed_scoop,drop_scoop. - Licks: external events — webhooks, cron, workflow completions.
- Floats: runtime envs — CLI, extension, Electron, cloud (hosted-leader), Cherry (embedded follower garnish;
?cherry=1in a host page's iframe). - Biscotto (pl. biscotti): a revocable guest seat on a cone. Holder gets a private
*.sliccy.nowURL showing the live transcript; its messages are untrusted by default and pass a message/tool gate. Restricted at the wire byscoops/tray-leader/biscotto-gate.ts. Approvers:user,cone,agent(a bounded per-request approver driven by/etc/APPROVALS.md), or a delegatedscoop.
Use ice cream terms in review comments and docs when they match the domain (e.g., feed_scoop not delegate_to_scoop).
Git Conventions
- Keep commits focused and package-local when possible.
- Linear history: CI rejects merge commits. Rebase onto
origin/main; Husky enforces viapackages/dev-tools/tools/check-linear-history.sh. - Do not hand-edit generated output in
dist/. - Auth: GitHub OAuth login (preferred; renews the git bridge on network ops) or
git config github.token <PAT>; seedocs/secrets.md.
Requires Node >= 22 (LTS). Ports: 5710 (bridge + /api), 9222 (Chrome CDP), 9223 (Electron CDP). node-server serves no UI — the webapp loads from the hosted origin and dials back to the local /cdp bridge.
Parallel Instances
Override the UI port to run parallel standalone instances; profiles and CDP ports stay isolated:
PORT=5720 npm run dev # Second instance on port 5720
PORT=5730 npm run dev # Third instance on port 5730Principles
- Claw pattern — persistent browser orchestration layer over Pi.
- Virtual CLIs first — composable shell commands over dedicated tools.
- Browser-first — state client-side; the server is a stateless relay; the extension has zero server.
- Skills over hardcoded features — add capabilities as SKILL.md files when possible.
Architecture
SLICC runs as standalone CLI (Express + Chrome), Chrome extension, Electron float, cloud hosted leader, or Cherry follower. See docs/architecture.md + float topology. Each package CLAUDE.md is authoritative for its subsystem. Shell: docs/shell-reference.md. Verification/CI gates: .agents/skills/verifying-before-push/SKILL.md.
Key Conventions
- Tests:
packages/*/tests/mirrorssrc/. Vitest,globals: true,environment: node.fake-indexeddb/autofor VFS tests. - Dual-mode compatibility: features MUST work in CLI and extension. The thin extension runs no dynamic code — UI, sprinkles/dips, JS realms, WASM all run in the hosted leader tab / kernel worker; extension assets load via
chrome.runtime.getURL(). The extension itself is inai-ecoverse/slicc-extension: an extension-protocol change in webapp (kernel/messages.ts, offscreen/picker clients) orshared-tsmust also land there. - Extension detection:
isChromeExtensionRealm()from@slicc/shared-ts(lint-gated). - Model ID aliases: use pi-ai aliases (e.g.,
claude-opus-4-6), not dated snapshot IDs. - Developer vs agent CLAUDE.md: developer-facing
CLAUDE.mdlives at repo root and each package. Agent-facing runtimeCLAUDE.mdispackages/vfs-root/shared/CLAUDE.md(bundled as/shared/CLAUDE.md). Tier table:docs/CLAUDE.md.
Change Requirements
Every change must satisfy tests, docs, and verification.
Tests
- Add/update tests for behavior changes; TS tests in
packages/*/tests/, mirrored by subsystem. Patterns:.agents/skills/writing-slicc-tests/SKILL.md. - Coverage thresholds enforced in CI. Floors in
coverage-thresholds.json; raised by the nightly ratchet (packages/dev-tools/tools/coverage-ratchet.mjs). Never hand-lower them. TS:npm run test:coverage:<package>; Swift:packages/dev-tools/tools/swift-coverage-check.sh.
Documentation
Doc tier map (full table: docs/CLAUDE.md):
README.md— user-facing behavior changesCLAUDE.mdfiles — developer conventions, architecture, buildsdocs/— detailed tools, commands, patternsvfs-root/workspace/skills/*/SKILL.md— agent skills (shell command changes).agents/skills/*/SKILL.md— developer agent skills (verification, wiring, tests, runbooks)
Verification
Run the full pre-push/PR pass — lint (first; top CI failure), typecheck, test, test:coverage, both builds, plus the touched-file debt gate — before committing. Commands and CI-only gates: .agents/skills/verifying-before-push/SKILL.md; CI in .github/workflows/ci.yml.
Developer Agent Skills (.agents/skills/)
Skill-aware harnesses load these directly; this list routes AGENTS.md-only harnesses to them.
- Add/change a SLICC feature surface → use
adding-slicc-features - Deploy/debug the Cloudflare tray hub worker → use
deploying-tray-worker - Record a UI demo for a PR → use
demo-recording - Hand work off to SLICC → use
slicc-handoff - Smoke-test a build in a controlled browser → use
cdp-smoke-test - Write/update SLICC tests → use
writing-slicc-tests - Commit, push, open/update a PR, diagnose verification CI failures → use
verifying-before-push
Automated PR Review Checklist
Reviewers (Claude action, Codex AGENTS.md, Copilot .github/copilot-instructions.md) and humans check PRs against these blind spots. Descriptions: docs/root-details.md; full catalog: docs/review-patterns.md.
- Error-path coverage
- UI state preservation
- Cross-runtime parity
- CDP edge cases
- Native/macOS permissions
- Model metadata / provider pipeline
- Test coverage
- Follower wiring parity
- Origin/bridge routing
- Layer import direction
- Untyped string-keyed bags (
Record<string, unknown>) - Agent skill freshness
- Transcript export
--helpthat does the thing
When you change a category, update docs/review-patterns.md (source of truth) and the ≤4,000-char .github/copilot-instructions.md so all reviewers stay in sync.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

