omarchy plugin validate .
qmllint -I "${OMARCHY_PATH:-/usr/share/omarchy}/shell" ./*.qml

~/.config/omarchy/plugins/<plugin-id>

omarchy-shell shell rescanPlugins
omarchy restart shell

# Omarchy Plugin Development

Develop Omarchy Quattro shell plugins from initial implementation through a reviewed local release candidate. Plugins execute as unsandboxed code inside the long-running Omarchy shell, so treat host APIs, external data, process execution, persistence, and failure behavior as production security boundaries.

This skill owns local source changes and release readiness. It does not publish marketplace listings, change repository visibility or security settings, push a release candidate, or create or edit marketplace issues. Hand those public actions to `omarchy-plugin-publishing`.

## Refresh the development contract

Before substantial plugin work:

1. Read the repository's own instructions and existing manifest, README, entry points, tests, license, notices, preview, and security policy.
2. Read the current official shell-plugin manual at https://github.com/basecamp/omarchy/blob/quattro/manual/32-shell-plugins.md and the installed host documentation under `${OMARCHY_PATH:-/usr/share/omarchy}/shell/plugins/`. Do not rely on remembered APIs.
3. Inspect the current installed implementations of imported `qs.Ui` and `qs.Commons` components when their rendering, input, process, or security behavior matters.
4. Check the current CLI with `omarchy plugin --help` and validate against the installed Omarchy version.

Never edit `/usr/share/omarchy/`. It is safe to read as the active host contract. Keep plugin source in its repository or under the user's plugin directory.

## Inspect the plugin contract

Confirm:

- The repository root contains exactly one plugin and a valid `manifest.json`.
- The plugin ID is globally namespaced, lowercase, stable, and outside `omarchy.*`.
- Manifest kinds and entry points match real files.
- The README accurately documents installation, removal, dependencies, state left behind, privacy behavior, IPC commands, and user-visible effects.
- A root license exists, and third-party services, data, code, and assets are documented.
- Any root preview uses an allowed filename and contains no private or accidental personal data.
- Installation and removal are safe and do not overwrite unrelated user configuration.

Preserve unrelated user changes. Ask before destructive replacement of installed plugins, state, configuration, or symlinks.

## Implement against current host behavior

- Prefer stable Omarchy components and APIs already present in the installed shell.
- Inspect shared controls rather than assuming how they render dynamic text, open URLs, handle focus, or execute commands.
- Pass process commands as argument arrays. Avoid a shell; when one is unavoidable, keep the script constant, pass dynamic values as positional arguments, and strictly allowlist them.
- Encode dynamic URL components and use fixed HTTPS origins unless the product explicitly requires user-configurable endpoints.
- Bound network time, response size, parsed collection lengths, retries, and persistent data.
- Validate external values before they affect commands, paths, URLs, schedules, rendering, or durable state.
- Use atomic writes for durable state when available. Store private state in owner-only directories.
- Preserve required attribution and licensing links while keeping externally derived text out of rich-rendering surfaces.
- Design async work so stale responses, overlapping processes, and retries cannot apply obsolete state.

## Validate continuously

Run the plugin's own tests and the installed Omarchy validators. At minimum, when available:

```bash
omarchy plugin validate .
qmllint -I "${OMARCHY_PATH:-/usr/share/omarchy}/shell" ./*.qml
```

Also run repository-specific tests and `git diff --check`. Treat warnings and skipped checks explicitly; never imply an unavailable check passed.

Validation is not a security review or proof of safety.

## Perform a focused security review

Perform a focused, adversarial review of the complete proposed snapshot, not only the recent diff or suspicious keywords. For an update, also compare against the last released or marketplace-listed exact commit to identify new capabilities and changed trust boundaries.

Start by inventorying capabilities, including network access, process execution, filesystem access, persistent configuration, DBus or other IPC, privileged services, environment access, and dynamic loading of URLs, images, QML, JavaScript, HTML, Markdown, or SVG.

Identify attacker-controlled or externally derived sources, including:

- network responses and redirects;
- process output;
- configuration, state, and cache files;
- filenames and directory contents;
- environment variables;
- clipboard, notification, window, and other desktop content;
- manifest or marketplace metadata;
- DBus and other IPC messages;
- user input and previously cached external data.

Trace those sources into security-sensitive sinks, including:

- shell commands, interpreter invocation, dynamic evaluation, and process arguments;
- rich text, Markdown, HTML, SVG, image, URL, and other resource-loading renderers;
- filesystem paths, overwrites, deletion, permissions, and symlink handling;
- sudo, DBus, service control, and other privileged interfaces;
- outbound requests that could disclose credentials or private data or contact attacker-selected hosts;
- persistent state, logs, notifications, previews, and configuration.

Also review supply-chain pinning and runtime downloads; installation and removal symmetry; races and stale asynchronous responses; partial writes and interruption recovery; malformed or oversized input; retry behavior; resource exhaustion; privacy disclosures; and failure handling.

Test credible trust boundaries with adversarial inputs such as markup and resource-loading tags, shell metacharacters, multiline values, traversal and absolute paths, symlinks, hostile URLs and redirects, malformed or oversized responses, missing fields, control characters, and unusual Unicode. Add regression tests for concrete findings where practical.

For QML, never leave an externally derived string using `Text.AutoText`. Use `textFormat: Text.PlainText` unless rich rendering is intentional, bounded, and reviewed. Treat dynamic URLs, links, images, SVG, and other resource sources as active capabilities. This is one QML-specific example, not the scope of the review.

When delegation is available, use an independent read-only security reviewer with fresh context, then verify each reported source-to-sink path before treating it as a finding. Reject speculative findings only with source evidence. After fixes, run a focused post-fix review for the controls and regressions introduced.

Record the reviewed snapshot, capability inventory, important data flows, findings, fixes, tests, and residual risks. This is not a security audit, certification, warranty, endorsement, or guarantee.

## Link and test locally

Use the user plugin directory for local testing:

```text
~/.config/omarchy/plugins/<plugin-id>
```

Before linking, inspect the existing target and whether a dotfile or configuration manager owns it. If managed, change the manager's source and apply only that target instead of bypassing it.

- If it is already a symlink to the working repository, leave it in place.
- If it does not exist, create a symlink from the plugin ID directory to the repository.
- If it is a real directory, a different symlink, or a managed installation, stop and obtain approval before replacing or backing it up.

Enable the plugin through the supported CLI when needed. Source changes under a directly watched plugin directory may hot-reload; changes reached through a symlink may require:

```bash
omarchy-shell shell rescanPlugins
omarchy restart shell
```

Use the least disruptive command first. Verify the service through its documented IPC status when available, but do not expose private status fields in reports.

Perform manual testing of every user-visible mode and changed behavior. Include normal, empty, loading, offline, malformed-data, long-content, keyboard, restart, persistence, and recovery states relevant to the plugin. Preserve required attribution in every state where third-party terms require it.

## Prepare the release candidate

Before handoff:

1. Confirm the intended version. Do not bump again merely because an unpublished candidate needed fixes.
2. Use a release-facing commit message when update interfaces expose the commit title to users.
3. Ensure all intended files are committed and the working tree is clean.
4. Rerun tests, Omarchy validation, QML lint, diff hygiene, and the focused security review against the final committed tree.
5. Confirm the committed tree is identical to the reviewed working snapshot.
6. Stop with the committed candidate local. Do not push from this skill; `omarchy-plugin-publishing` owns the separate public push approval and action.

## Hand off to marketplace publishing

When the owner wants to submit or update the marketplace listing, stop local-development work and use `omarchy-plugin-publishing`. Do not create or edit marketplace issues, change repository visibility or security settings, or infer permission to push.

Provide this release-readiness record:

- plugin ID, name, and version;
- repository root URL;
- new listing or existing-listing update;
- exact candidate commit SHA and branch name;
- currently listed commit, when applicable;
- clean working-tree status, whether the candidate is already pushed, and whether remote branch HEAD equals it;
- tests and validation commands with results;
- full security-review scope, findings, fixes, tests, and residual risks;
- manual testing performed;
- capabilities, dependencies, privacy behavior, and attribution requirements;
- preview status;
- release-facing commit message.

## Completion report

Report:

- files changed;
- behavior implemented or fixed;
- validation and manual-test results;
- security-review findings and residual risks;
- local-link status;
- version and exact candidate commit, if prepared;
- skipped or unavailable checks;
- whether the working tree is ready for publisher handoff.