- What is Solaris
- Quick Start
- How Solaris Works
- Modes of Solaris Operation
- Starting a Solaris Project
- Developing a Solaris Project
- Sharing and Collaborating on a Solaris Project
- Extending Solaris with Plugins
- Keeping Solaris Projects Current
- Skills Reference
- Specification
- Solaris serves as command center that runs many projects from one place, injecting an AI-Pack that can be updated from master version at any time, bringing improvements with it.
- Memory system in Solaris projects has a short- and long-term layers. Sort-term is specific to current installation, long term memories can be shared with the team.
- A Solaris project can be completely detached for standalone development or deployment and shared with customers or public.
- Solaris AI-Packs are collaboration-compatible through git-based workflow. Long-term memories can go through PRs or standard git processes.
- Solaris AI-Packs and plugins are evolving over time: improvements from one project flow back into Solaris master version, and from there into all the other Solaris projects.
- Plugins are supported for quickly adding skills, tools, domain or company-specific workflows, etc) and are designed to be compatible with collaborative process too.
- Ad-Hoc Tasks allow quick one-off work such as research, system setup, and quick prototyping.
You need uv (it manages Python 3.14) and Cursor or Claude Code.
git clone https://github.com/myurasov/Solaris && cd Solaris
uv sync # deps + venv
cp mcp.json.example .mcp.json # runtime MCP (Claude Code)
mkdir -p .cursor && cp mcp.json.example .cursor/mcp.json # runtime MCP (Cursor)
git config core.hooksPath .githooks # optional commit-policy hookOpen the repo root in Cursor or Claude Code and just talk to the agent - there are no slash commands. Try:
- "create a new python-cli project called pingpong"
- "import project ~/code/my-app"
- "new task: research local LLM serving options"
- "health-check"
Everything else in this guide happens through phrases like these; the full list is in the Skills Reference.
One agent runs everything; it adopts a persona from wherever it is working:
- At the repo root it is the orchestrator - it routes your prompts to skills (markdown
procedures) and manages
projects/,plugins/, andtasks/. - Inside a project folder (
projects/<group>/<slug>/, grouped e.g.projects/my/<slug>/; writtenprojects/<slug>/for short) it is that project's primary persona (engineerby default; a project can rename it and add role personas as<role>.agent.mdbriefs beside it) - it plans, builds, and runs the project against the project's ai-pack.
You do not manage this switch; saying "work on <project>" hands off automatically.
Under the hood, hooks make context loading deterministic: read_first injects the rules and
operating memory at session start, skill_loader injects the matching skill when your prompt
triggers one, and log_interaction keeps a backstop log of every prompt. Instructions live in one
canonical AGENTS.md per scope (Cursor reads it natively; Claude Code through a one-line
CLAUDE.md shim).
Solaris supports several modes of use; each has its own workflow, and they mix freely.
- Command center (the full setup, this repo): you run many projects from one place.
Workflow: create or import a project -> develop through the engineer -> keep packs current with
"update
<project>" -> publish or hand off when a project leaves the nest. - Standalone pack (no Solaris at all): a teammate or customer works on a single project repo
that carries its ai-pack. Workflow: clone -> say "init" to onboard -> develop with any AI
tool (the pack loads through
AGENTS.md) -> "refresh" after pulls -> propose pack changes through normal PRs. - Ad-hoc mode: no project at all - "new task: ..." gives a dated folder under
tasks/for research, setup, or prototyping, withnotes.mdas the record; promising tasks graduate into projects or plugins. - Plugin development: attach a plugin in link mode so a real project exercises the live
plugin source. Workflow: "link plugin
<name>to<project>" -> iterate in place -> version the plugin -> consumers pick it up on their next update.
Say "create a new project" (the agent will ask for what it needs) or "import project
<path>" to adopt an existing codebase. Either way you get an ai-pack at
projects/<slug>/<pack>/ - the bundle that tells any AI agent how to develop that project (its
generated <pack>/README.md explains the pack to humans: contents, configuration, everyday how-tos).
<pack>/ is the project's ai-pack folder (default aipack/, ai/ in projects made before 0.39.0,
any name); Solaris finds it by its manifest.json, so you can pick the name at creation and rename
it later.
A project can be anything - a service, a research codebase, a firmware tree, a content pipeline, a doc site; nothing limits you to the bundled kinds. Choices you make at creation:
- Type: just a starting template that seeds structure and planning hints.
python-cli,web-service, andios-appship with Solaris, plugins can provide more, and anything else works fine as the nearest type (or an import) plus your own spec. - Mode:
local(code insource/beside the pack),remote-code(code stays on an SSH host), orembedded(the pack lives inside your source repo and commits with it). - Plugins to attach and, for multi-track projects, workspaces (see below).
What lands in the pack:
- Shareable, long-term (commits with the repo):
<primary>.agent.md(the primary persona,engineerunless renamed), optional<role>.agent.mdrole persona briefs beside it,instructions.md(the one shared know-how store every persona reads and maintains: build/run/test, conventions, gotchas, lessons),spec.md(the contract),manifest.json, always-on pack rules inrules/(token economy, subagent delegation, YAGNI mode, git collaboration: developer branches + PR-based back-contribution) with their committed defaults indefaults.json, perishable reference data the rules read ininfo/(model tiers, harness capabilities), and inskills/theinit/refreshstubs for teammates plus ahandoverskill to pause, hand over and resume work. - Private, short-term (
<pack>/.memory/, gitignored): the owner's directions log (directions.md, checked for drift at each push so long-standing ones reachinstructions.md), suggestions for the framework and plugins (improvements.md), hosts, secrets, session context, logs (one file per machine). Drop this layer to share the project.
Every project also carries its own semver in a root .version file (new projects start at 0.1.0;
imports adopt an existing v* tag or 1.0.0 for already-shipped work): the engineer
proposes a bump when a milestone lands - never bumps silently - and each approved bump is committed
and tagged v<X.Y.Z>. This is independent of the pack-sync metadata (revisions, framework_version).
The pack is standalone-first: it works with no Solaris around it, and can be refreshed from
the framework master at any time ("update <project>") to pick up the latest improvements.
Say "work on <project>" and make requests; the engineer plans against <pack>/spec.md,
implements, runs, and remembers what it learns in the pack.
Workspaces. When a project grows parallel tracks (say a data pipeline, a UI, and an evaluation
track), split it into workspaces - self-contained top-level folders. Each has its own setup.md
(a from-scratch bring-up ending in verification), spec.md, dependencies, and scratch; none
references files in a sibling, and shared inputs (e.g. data/) live outside all of them.
source/ is the default workspace; the ai-pack stays single and shared. To add one, ask the
engineer - or create the folder from solaris/templates/workspace/ and register it in the
instructions' workspace table.
Ad-hoc tasks. For work that does not warrant a project - research, system setup, quick
prototyping - say "new task: ...". You get a dated folder under tasks/ whose notes.md (steps,
findings, outcome) is the durable record. If a task turns into something real, it graduates into a
project or plugin.
An ai-pack is built for teamwork through ordinary git hosting - most collaborators never run Solaris at all.
- Onboard a teammate. They clone the repo and say "init" (or "onboard me") in their AI tool:
the pack's
initskill collects their environment into the private layer and brings the project up. After a pull, "refresh" migrates their checkout to any new conventions. - Review pack changes like code. The long-term memories (instructions, specs, conventions) are committed as diff-friendly files - wrapped prose, stable headings, generated TOCs - so they review cleanly in PRs.
- Merge without fear. Solaris sync metadata (
_Rev. N_markers, the manifestrevisionsmap) is take-either-side in a conflict; committed*.jsonllogs union-merge via.gitattributes. - Feed improvements back. Projects never edit framework or plugin files: each writes
suggestions to its private
.memory/improvements.md, and "review project improvements" folds in what you approve, so a refinement made on one project reaches every Solaris-based project on its next update. - Hand off or publish. Say "prepare
<project>for handoff": thepublish-projectskill scrubs identities and internals, adds license/disclaimer, and verifies the detached pack stands alone - ready for a customer or the public.
A plugin packages a domain or employer workflow - always-on rules, trigger-invoked skills, MCP servers, optional project types - so any project can opt into it.
- Attach one: "install plugin
<git url | folder | zip>", then "add plugin<name>to<project>". Itsshared/files are copied into the project's<pack>/plugins/<name>/and its MCP servers merged. While developing a plugin, use link mode ("link plugin<name>to<project>") - a pointer to the live source instead of a copy. - Author one: "make a plugin from
<project>" factors that project's ways of working into a reusable plugin; the same skill folds later owner-approved changes back into the plugin source. - Bundled plugins:
browserctl(CLI browser automation on per-project Chromium profiles - the standard browser layer, replacing the Playwright MCP; defines thebrowserctl.<site>extension-skill format for site-specific browser knowledge),apple-asc(App Store Connect from the developer's perspective: ASC REST API skill, browser skill for the flows the API cannot reach, build archive + upload skill, always-on rule),gmail(Gmail throughgws, the Google Workspace CLI: install + sign-in skill for macOS/Linux, read + send skill, always-on send-confirmation rule),kaggle(Kaggle through the official Kaggle CLI and three read-only SDK reads for what the CLI drops: a gateway that pins the CLI and installs it per project or task, Kaggle's own agent skill vendored at the same version, always-on rule confirming every write; plus a generic competition playbook, a saved leaderboard history for following every team's progress, public notebooks saved with their scores, one Kaggle account's sessions and GPU hours shared between projects (kernel pushes need a sharing lease), an hourly competition-forum watch, a single status page for the owner, a pre-submit check of what is new, a gated submit, a one-call hourly pass, and a fetch of named files from huge kernel outputs),docker-home(a per-project Linux container that runs the coding harness itself with only the project folder and the container's home mounted, so nothing above the project exists for the agent;dh-*.shshortcut scripts manage it from any terminal, the skill drives them strictly on request; meant for long-lived sessions on Linux hosts holding a synced Solaris tree),nvidia-isaac-lab(NVBugs + Isaac workflow),visual-qa(VLM-based visual E2E testing),aisee(AISee eyes and ears: visual QA and transcription; rule + skill + MCP servers),nvidia-brev(autonomous Brev cloud-GPU run lifecycle),reporting(findings-report authoring + zero-npm-dep PDF rendering via installed Chrome and Node 22+, also on Linux hosts that block Chrome's sandbox, with a layout check after every render - the only check for living documents rebuilt again and again; per-project theme: fonts, accent color, page furniture),resource-sharing(hosts shared by agents and projects: per-host claim files with pinned, watched jobs and yields; sharing links with one owner per host and guest requests; fit against new paid instances; an owner audit so no machine is abandoned; guests told of new, gone and changed shared hosts; shared pools for account-level limits; a GPU host health check whose--fixapplies safe performance settings; a live dashboard of each host's jobs and load).
Say "update <project>" whenever you want a pack to catch up with the framework. Two mechanisms
work together:
- Per-file revisions (
_Rev. N_markers + a ledger) sync materialized pack files with their masters: files you never touched fast-forward, files you improved merge up into the master, true conflicts ask you. Markers appear only on files that materialize into packs; everything else is versioned by git + semver. - Migrations (
solaris/migrations/<version>.md) carry a pack across framework releases without touching your code; plugins carry their own.
Memory stays scoped while all this happens: the framework's .memory/ (operating lessons,
inventory, logs) and each project's <pack>/.memory/ are the only stores, and packs never read the
framework's. Run "health-check" any time for a one-screen status of projects, revisions,
versions, and tasks.
| Say | Skill | What happens |
|---|---|---|
| "create / new project" | create-project |
Scaffold a project + ai-pack (type / mode / plugins / workspaces). |
"import / adopt <path>" |
import-project |
Adopt an existing codebase; derive its ai-pack. |
"work on / develop <project>" |
develop-project |
Hand off to the project's engineer to plan/implement. |
"update / migrate <project>" |
update-project |
Sync an ai-pack + plugins to the current framework version. |
"publish / share <project>" |
publish-project |
Scrub identities/internals, license, verify the pack stands alone. |
| "create / install / repair a plugin" | import-plugin, install-plugin |
Author, acquire, validate, attach plugins. |
| "do a release" | release |
Bump version, author migration, update docs, tag + publish. |
| "self-reflect", "review project improvements" | self-reflect |
Review interaction logs and project suggestions; propose framework improvements. |
| "new task / research X" | ad-hoc-task |
Start/resume dated ad-hoc work under tasks/. |
| "health-check" / "status" | health-check |
Command-center overview; --deep for full checks. |
"compact yourself", or a DUE line |
opencode2-selfcompact |
An OpenCode 2 session compacts itself past a set context size, after saving a checkpoint. |
Stdlib-only tools back the skills and run as modules (uv run -m solaris.tools.<name>): version,
revs, mcp_sync, agents, toc, ai_spend (estimated AI spend per project and day),
session_clock (a wake clock for scheduled agent work), session_compact (an OpenCode 2 session's
self-compaction, which interactions add checks on every logged turn), housekeeping (a project's folder sizes against its
data budget, tidying of its private folder, pruning by rule and of re-creatable data), plugins (plugin dependencies and the project
types plugins provide, such as kaggle:competition), plus uv run pytest for the test suite. read_first, skill_loader,
log_interaction and session_guard are hooks - never run by hand.
Full conventions, plugin contract, migration engine, project modes, and safety/commit policies:
solaris/spec/spec-v0.46.0.md. Apache 2.0; Copyright 2026
Mikhail Yurasov me@yurasov.me.