Skip to content

CLAUDE.md

Latest commit

 

History

History
106 lines (81 loc) · 8.66 KB

CLAUDE.md

File metadata and controls

106 lines (81 loc) · 8.66 KB
Raw

CLAUDE.md — appos-dev plugin

Project instructions for Claude Code when working inside this repo.

Note: per the Claude Code plugin docs, this root CLAUDE.md is NOT loaded as plugin context when the appos-dev plugin is installed — it exists for contributors editing THIS repo. Knowledge meant for plugin consumers belongs in the skills/agents/commands under plugins/appos-dev/.

What this is

A Claude Code plugin that gives Claude Code the skills, commands, and agents needed to create, build, test, and deploy AppOS workspace manager plugins. Canonical references: the developer docs at https://docs.appos.space (always reachable) and the flagship plugin https://github.com/appos/appos-plugin-ytdlp (public as of AppOS launch) — the plugin that exercises every supported SDK feature.

This plugin is versioned at 3.x (current: see .claude-plugin/marketplace.json, the repo's ONLY manifest — both metadata.version and plugins[0].version), deliberately aligned with the @appos.space SDK major it teaches. That alignment is versioning convenience, NOT a minHostVersion — the host version stays 1.0.0 (see Conventions). The v2.x line was the SDK+WebView rewrite; the legacy ViewDescriptor-only model is still supported but is no longer the primary pattern.

Repository layout

appos-dev-plugin/
├── .claude-plugin/
│   └── marketplace.json     # Marketplace catalog (the ONLY manifest — no plugin.json exists) — points at ./plugins/appos-dev
├── plugins/
│   └── appos-dev/           # The actual Claude Code plugin
│       ├── commands/
│       │   ├── new-plugin.md        # /appos-dev:new-plugin
│       │   ├── build.md             # /appos-dev:build
│       │   ├── deploy.md            # /appos-dev:deploy
│       │   └── validate.md          # /appos-dev:validate
│       ├── agents/
│       │   ├── plugin-architect.md          # Designs plugin architecture from requirements
│       │   ├── viewdescriptor-builder.md    # Builds ViewDescriptor UI trees
│       │   └── webview-panel-builder.md     # Builds WebView panels end-to-end
│       ├── skills/
│       │   ├── appos-plugin-dev/
│       │   │   ├── SKILL.md         # Main SDK+WebView skill
│       │   │   └── reference/       # API reference, patterns, plugin-api/ d.ts mirror (generated)
│       │   ├── viewdescriptor-authoring/
│       │   │   └── SKILL.md         # ViewDescriptor authoring skill
│       │   └── webview-panels/
│       │       └── SKILL.md         # Focused WebView authoring skill
│       └── compiled/        # GENERATED context artifacts for the AppOS host — do not hand-edit
├── scripts/                 # verify-knowledge.mjs + check-sdk-freshness.sh + check-compiled-freshness.sh (CI gates)
├── package.json             # exact-pinned toolchain for the gates (npm ci)
├── package-lock.json
├── README.md
└── LICENSE

Generated content — provenance

  • plugins/appos-dev/skills/appos-plugin-dev/reference/plugin-api/ is a byte-verbatim mirror of the published @appos.space/plugin-types tarball's dist/*.d.ts, regenerated with scripts/check-sdk-freshness.sh --update and verified against the npm registry on CI. Never edit by hand.
  • plugins/appos-dev/compiled/ is generated by the AppOS-Desktop repo's scripts/compile-factory-context.sh, which concatenates this repo's skill sources into the context artifacts the host bundles for its in-app AI features. Regenerate via that script (it writes both the Desktop-side copy and this repo's copy); the artifacts are validated by freshness manifests, not by verify-knowledge.mjs.

Key references

Before editing anything, be aware of these external sources of truth:

  • Developer docs: https://docs.appos.space — the canonical AppOS plugin developer documentation.
  • Flagship reference plugin: https://github.com/appos/appos-plugin-ytdlp — all patterns in the skills match this plugin's implementation. When in doubt, read its source files, in this order: (1) a local clone if one exists (preferred); (2) the GitHub repo — public as of AppOS launch; fetch raw files from https://raw.githubusercontent.com/appos/appos-plugin-ytdlp/main/<path>; (3) https://docs.appos.space — always reachable; its getting-started/first-plugin pages carry the same canonical patterns.
  • SDK source: https://github.com/appos/plugin-sdk (packages/plugin-types) — the current declaration-only TypeScript types, also published on npm as @appos.space/plugin-types. Use for reference when validating API shapes in skills or commands.
  • Host version: read /Applications/AppOS.app/Contents/Info.plist → CFBundleShortVersionString (currently 1.0.0). The host version is what plugin.json minHostVersion is compared against, NOT the SDK package version.

Conventions

  • Plugin IDs: use space.appos.* for flagship plugins (the ones shipped with AppOS), com.community.* for community plugins, other reverse-domain for private/personal plugins.
  • minHostVersion: always default to "1.0.0". The single biggest cause of "plugin installed but not appearing in Settings" is conflating the SDK version (3.0.x — or the older 2.4.x) with the host version (1.0.x). The appos-plugin-dev skill has a "minHostVersion landmine" section; keep it prominent.
  • tsconfig: always include verbatimModuleSyntax: true. Without it, TypeScript emits broken runtime imports from the declaration-only @appos.space/plugin-types package.
  • Entry point: always globalThis.activate = activate + globalThis.deactivate = deactivate, never ESM export. ESM exports disappear inside the IIFE closure and the host can't find them.
  • Parameter naming: always ctx, never pluginContext. Matches appos-plugin-ytdlp and every reference plugin.
  • rsync deploy: always use --delete-excluded and a comprehensive exclude list. Without --delete-excluded, files added to the exclude list after a previous deploy linger on the destination forever.

When updating skills or commands

  1. Read the corresponding code in appos-plugin-ytdlp first — that's the ground truth (local clone preferred; see Key references for the fallback order).
  2. If the SDK surface changed, check https://github.com/appos/plugin-sdk (packages/plugin-types) — or the published @appos.space/plugin-types npm package — for the current type definitions.
  3. Keep examples copyable — prefer full working snippets over fragments.
  4. When documenting a gotcha, include a **Why**: line with the root cause so future-you can judge edge cases.
  5. Run the CI gates before committing: npm ci once, then npm run check — the same sequence CI runs: scripts/check-sdk-freshness.sh (mirror byte-equality), node scripts/verify-knowledge.mjs (type-checks every ts fence against the pinned SDK, plus a stale-identifier denylist and count-string consistency; opt-out convention documented in the script header), and scripts/check-compiled-freshness.sh (compiled/ artifacts match their manifest, both directions).

When adding new commands/agents/skills

Follow Claude Code plugin conventions:

  • Commands go in plugins/appos-dev/commands/*.md with frontmatter declaring allowed-tools and argument-hint
  • Agents go in plugins/appos-dev/agents/*.md with frontmatter declaring name, description, whenToUse, tools
  • Skills go in plugins/appos-dev/skills/{name}/SKILL.md with frontmatter declaring description (include the trigger phrases that should activate it)

Testing locally

From the repo root (the plugin lives at plugins/appos-dev, not the repo root):

claude --plugin-dir ./plugins/appos-dev

Then verify:

  • /appos-dev:new-plugin scaffolds a plugin using the SDK pattern
  • The main skill triggers when asked something like "create an AppOS plugin that downloads with yt-dlp"
  • The webview-panels skill triggers when asked about registerWebPanel or pipeShellToWebPanel
  • The plugin-architect agent triggers when asked to design a new plugin
  • The webview-panel-builder agent triggers when asked to build a WebView panel

Do NOT

  • Do NOT copy from the legacy community-plugin template — it's the ViewDescriptor-only model and should not be used for new plugins
  • Do NOT recommend ESM export for activate/deactivate
  • Do NOT set minHostVersion to anything other than "1.0.0" without a documented reason
  • Do NOT add inline <script>/<style>/on*= to WebView HTML examples (CSP blocks them)
  • Do NOT recommend ctx.shell.pipeShellToWebPanel — that's stale documentation; the correct path is ctx.ui.pipeShellToWebPanel