Start

organic-os start (guided front door)

This is the first thing a new or returning user should run. It never writes anything itself - it health-checks, then hands off to setup or to whatever the user picks from the menu.

Step 1: greet

One sentence, no hype: organic-os observes a site's search and AI-answer- engine performance, proposes changes, and only ships them once a human approves - the loop is the product.

Step 2: health check

Run each check in order and report plainly what passed and what did not. Do not stop at the first failure - collect all three results, then act.

1. python3 on PATH: python3 --version. If missing, tell the user

organic-os needs Python 3.9+ and stop here - nothing else in this skill works without it.

1. PyYAML importable: python3 -c "import yaml". If this fails, show the

fix and stop: python3 -m pip install --user pyyaml. Offer to run it for them.

1. Registry readable:

PYTHONPATH="$CLAUDE_PLUGIN_ROOT/lib" python3 -c "from core import registry; print(registry.load())". A clean {'active': None, 'sites': {}} or a populated registry both count as a pass - this check is about core.registry importing and running, not about whether any site exists yet.

If all three pass, say so in one line and move to Step 3.

Step 3: route

Use the Step 2 registry read to decide which branch applies.

Registry empty (no sites)

Offer two paths, AskUserQuestion with options:

• Quick start - URL, then 2 more questions, sensible defaults, about 2

minutes.

• Full setup - audits the URL first (brand voice, audience, keywords,

competitors, geos proposed from the actual site, not asked blind), then covers whatever the audit cannot infer: operator knowledge, connectors, Google Ads, WordPress, approval channel, runtime, brain location and mode.

Mention the install form once, before handing off: if you filled the configuration form when you enabled the plugin, setup will use it - nothing is asked twice, and a filled form makes quick start a single confirmation click.

Then invoke the setup skill in the chosen mode - quick-start mode or the full setup interview - and let it run to completion (scaffold, register, summary). Do not duplicate its questions here.

Registry has sites

Resolve the active site's brain path, then run core.contracts.check_schema(brain_path) before anything else in this branch:

• action: "stamp" - tell the user this brain predates schema versioning

and that running /organic-os:setup in update mode will stamp schema_version: 1 into it; continue to the status view below (stamping is informational, not blocking).

• action anything else with compatible: false - relay the action string

verbatim and stop. Do not show status or the menu, and do not route into a routine, until the user has resolved it.

• compatible: true with action: "none" - continue silently.

Show a compact status, read-only, no writes:

1. Active site: name + url (core.registry.get_active()).
2. Pending approvals: count lines under a status: proposed (or similar

pending) heading in /approvals/queue.md.

1. Last signal date: the filename (or latest entry date) of the most recent

file in /signals/. If the directory is empty, say "no signals yet".

1. Latest setup scorecard: find the most recent `/runs/*-setup-

scorecard/REPORT.md by folder date, if any, and print one summary line from its table - e.g. "setup scorecard (2026-07-19): 7/9 checks passing, 2 degraded (GA4 connector, approval channel) - run /organic-os:setup to fix." If no scorecard folder exists yet, say "no setup scorecard yet - run /organic-os:setup to generate one." This is a read, never a write - start` still writes nothing itself.

Then offer a menu, AskUserQuestion with options:

• Run daily - invoke hoo-daily (the daily signal pull).
• Review approvals - open /approvals/queue.md and walk the user

through pending items.

• Update settings - invoke setup in update mode.
• Add a site - invoke setup in add mode.
• Docs - point at $CLAUDE_PLUGIN_ROOT/docs/getting-started.md and README.md's

Quickstart-by-persona section.

Step 4: always close with the three commands

Regardless of which branch ran, end every /organic-os:start session by naming the three commands a user reaches for most:

• /organic-os:daily - the daily signal pull.
• /organic-os:onsite-audit - a credential-free on-page audit of any URL.
• /organic-os:weekly - the weekly reflection pass.

Rules

• This skill never writes to the registry, a brain repo, or any config file

itself - every write happens inside setup, hoo-daily, or whichever skill the menu hands off to.

• Never skip the health check, even for a returning user with sites already

registered - a broken PyYAML install fails silently deep inside setup or a routine otherwise.

• If the registry read in Step 2 fails for a reason other than "no sites yet"

(a corrupt YAML file, a permissions error), show the raw error and stop - do not guess a fix.

Source & license

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

• Author: shalintripathi
• Source: shalintripathi/organic-os
• License: MIT
• Homepage: https://organicos.shivaatripathi.com

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