# Claude Code workspace starter

Give this document or the browser guide below to your agent in its desktop app and ask it to set up a shared workspace and the first project. You do not need to type commands. Have the agent inspect existing files, then report its changes and verification.

[Browser guide](https://zov.la/setup)

The shared root contains README.md and AGENTS.md with sibling projects/, memory/, documents/, and skills/ folders. projects/my-project/ has its own AGENTS.md and STATUS.md. The Claude Code edition adds CLAUDE.md at the shared root and in the project. The indexes explain how to record knowledge; actual memory and documents start empty.

## Agent execution steps

### Before changes

Before changes, read any existing setup record and compare its scope with current files. Back up only existing instruction files you will modify to a local location outside public sharing, Git tracking, and cloud sync. Record original paths and content hashes. Do not collect credentials or entire app configurations. If a backup cannot be saved, leave that existing file unchanged. Mark new files as new and never overwrite earlier backups.

If no purpose is given, clarify it at the start. If the request already includes a purpose, use it without asking again and identify the capabilities it needs.

1. Review [setup.mjs](./setup.mjs), [files.json](./files.json), and [manifest.json](./manifest.json). The public manifest's SHA-256 values can verify the downloads. Inspect the real destination and existing files.
2. For a new shared workspace, if Node.js 20 or later is available, run the downloaded setup.mjs from its directory. Pass the absolute path of the selected destination to `--dest` and use the same path for `--check`. These are agent-facing OS examples; replace them with the actual path:

Windows example:

```sh
node ./setup.mjs --dest "C:/Users/you/ai-workspace"
node ./setup.mjs --check --dest "C:/Users/you/ai-workspace"
```

macOS example:

```sh
node ./setup.mjs --dest "/Users/you/ai-workspace"
node ./setup.mjs --check --dest "/Users/you/ai-workspace"
```

Linux example:

```sh
node ./setup.mjs --dest "/home/you/ai-workspace"
node ./setup.mjs --check --dest "/home/you/ai-workspace"
```

3. Without Node.js, create each `files[].path` with its exact `files[].content` from [files.json](./files.json) in a new destination. Compare each `sha256` value if a checksum tool is available.
4. For an existing folder, do not run the installer. Do not move an existing repository just to match the layout; link its entry point to the real shared-root path. Read its AGENTS.md, README, progress records, and knowledge base; integrate useful content by role. If NOTES.md or a tracker already holds the current state, do not duplicate it in STATUS.md. Reuse existing memory and reference sources too. Update entry points and indexes to match the actual locations. Preserve existing content and compare old records with the real files. For Claude Code, inspect any existing `CLAUDE.md` and add `@AGENTS.md` only if needed.
5. Rename the empty projects/my-project/ scaffold for actual work, or leave it until a first project is chosen. Start by opening the shared root and naming the project. In a fresh conversation, including when opening the project alone, verify access to shared instructions, STATUS.md, and relevant memory. If the parent is inaccessible, open the shared root or configure the necessary app read access. A new workspace must contain no invented progress or memories. For an existing project, confirm its existing records were preserved and checked against the real files. If actual model behavior is untested, say so in the report.

6. Only if the user requested personal setup, read [PERSONALIZATION.md](./PERSONALIZATION.md). Target only the selected app’s user-level instructions and inspect its actual location and existing content: usually ~/.codex/AGENTS.md for Codex (or the configured CODEX_HOME), ~/.claude/CLAUDE.md for Claude Code, and ~/.config/opencode/AGENTS.md for OpenCode. Check Codex AGENTS.override.md, which takes precedence, and inspect any OpenCode instructions inherited through the Claude fallback before creating its own file. Do not copy another app’s complete instruction file into a second managed copy. If the existing scope cannot be preserved, leave settings unchanged and report the concrete conflict and options. Distinguish temporary Codex overrides from lasting preferences without changing precedence silently. Do not replace the entire file or duplicate equivalent instructions. Integrate new content under a bounded ZOVLA personal preferences heading; on later runs update only that section by diff. Ask about conflicting preferences. Compare changes and verify active instructions in a fresh conversation. The user does not need to paste into settings again. Follow app guidance if write access is unavailable; do not bypass restrictions.

The installer accepts only a new destination with an existing parent. It rejects an existing empty directory, a path through a symbolic link, or a missing parent. On failure it leaves the incomplete destination and reports the error; it never deletes or overwrites it. `--check` verifies files without changing them. It makes no network requests, runs no external commands, changes no global configuration, and does not initialize Git or register plugins, hooks, or schedules.

## Skill selection and installation

If the purpose is unknown, ask what the user wants to create, research, or organize, then clarify only relevant output formats and recurring tasks. Check the selected app's built-in features and installed skills first. For missing capabilities, search official publishers or the app's catalog. Inspect candidate instructions, supporting code, publisher, terms, dependencies, and permissions. Explain a small set of candidates, the task each serves, why it is needed, its installation location, and scope. Once the user selects candidates, verify the app's supported format and actual discovery locations against official documentation and the environment, then install the selected items. If a plugin bundles skills with connectors or hooks, explain those additional effects separately and guide required approvals or sign-in through the app. This request does not authorize permission changes or charges. Avoid duplicate names or equivalent skills, and back up existing files before changes. Test discovery and a representative output on disposable examples. Record purpose, source and version, actual installation location, update and disable steps, and verification in skills/INDEX.md. Copying a skill into the shared skills/ library does not establish registration. If nothing is needed, record why. If no candidate is available or verification is blocked, record the gap and next step instead of inventing a skill or a successful result.

## Setup results and recovery

Save the post-setup contents of created or changed instructions and skills in the same private backup location, so before, after, and current states can be compared. Write the setup outcome to SETUP.md at the shared root. If an existing file with that name serves another purpose, choose a different name and link it from README. Record the purpose, selected app and OS, execution date, created/changed/deferred items, reasons, actual paths, backup locations, before/after snapshot paths and hashes (not a hash of the setup record itself), skill selection results, verified and unverified checks, and the folder to open next. Do not copy full settings or secrets into the record. Preserve earlier history on later runs and never mark unperformed work as complete. Include reversal instructions for each change. When reverting, compare current content with the post-setup state and preserve later work and settings. Do not replace a changed file wholesale with its backup; reverse only the setup changes by diff. Never remove the whole new workspace. Identify the app's supported disable or uninstall method for skills. Tell the user where the record and backups are and link the record from README.

SETUP.md starts as an empty record template. Its creation by the installer does not establish completion of agent-mediated setup. --check compares files with the distributed templates. Run it before renaming folders or updating records; check later differences against the actual setup record. Do not reset legitimate changes to make them match the starter.

Claude Code does not read `AGENTS.md` directly, so this edition includes a `CLAUDE.md` that imports `@AGENTS.md`.

## Official documentation

- [Claude Code instruction-file documentation](https://code.claude.com/docs/en/memory)

- [Claude Code skill documentation](https://code.claude.com/docs/en/skills)

## Permission

These original starter documents may be copied, modified, and shared for any purpose. No warranty is provided.