Cluide — Shared Project Instructions

About This Project

Cluide covers Claude and ChatGPT, including Codex for repository work, and Google Gemini (Antigravity, Jules and the Gemini app), whose routes are documented but not yet tested. This folder contains an operational framework for building, running, and improving a persistent AI assistant. It includes architecture guides, runnable setup and audit tasks, installable skills, and copy-paste templates — covering the full lifecycle from initial setup to scheduled automation, self-improvement, and security. The guides are human-readable and can be supplied to any of these assistants. Keep native mechanisms labelled and report which surfaces were actually tested; documentation coverage is not evidence of a live runtime check.

When working in this project, apply the guides to your own behavior. You have access to all of them as context. Use them:

• When asked to help set up or improve an assistant, follow the patterns described in the relevant guide
• When writing or editing project instruction files, skills, tasks, or memory files for the user, apply the structure and principles from the guides
• Apply the relevant guide's principles, but verify platform-specific commands, paths, tools, permissions, and feature availability against the actual runtime and current official documentation. Do not execute Claude-only instructions as if they were OpenAI instructions.

Guide map (read 00_INDEX.md for full descriptions):

When the user asks a question or makes a request that a guide covers, read the relevant guide before responding.

File Hygiene

Everything that is not part of the distribution goes in development/. The repo root holds only what a reader of the published guide would open: the numbered guides, 00_INDEX.md, README.md, CHEATSHEET.md, CHANGELOG.md, AGENTS.md, CLAUDE.md, PLATFORM_SETUP.md, LICENSE, and the skills/, tasks/, templates/ and .github/ folders. Review feedback, dated review passes, planning notes, scratch output, editor and tool configs, and the _to_delete/ staging area all live under development/, which is gitignored as a whole — so a new working file needs no new ignore rule, it just needs the right home. Before creating a file at the root, ask whether it ships; if not, create it in development/ instead. See development/README.md.

Optional paragraph — delete it if you are not developing Cluide itself. development/ is gitignored as a whole, so a fresh clone does not contain it and the development/README.md reference above will not resolve. Create the folder when you start making changes to Cluide, or remove the paragraph if you cloned this to use the guides rather than to change them. Nothing else in this file depends on it.

When creating new files, check whether they belong in .gitignore or .claudeignore:

• Add to .gitignore: run logs, output files, auto-generated bundles, any file containing personal data (paths, names, company names)
• Add to .claudeignore: large generated files that don't need to be loaded as context (compiled skill bundles, output archives, etc.)

If a newly created file should be ignored but is already tracked by git, run git rm --cached <file> to untrack it.

Platform and Dispatch Boundaries

• This file is the canonical repository policy. CLAUDE.md imports it for Claude Code. See PLATFORM_SETUP.md for ChatGPT, Gemini and other surfaces.
• Repository examples under templates/ and skills/ are distribution content, not instructions to install or run a personal assistant while maintaining this repository.
• Use only tools, models, skills, and permissions actually available in the current session. Never translate a model name from one vendor into a guessed equivalent from another.
• For delegation, consult skills/dispatch/SKILL.md and use the model configured for the current session. Claude-specific routing lives in CLAUDE.md; OpenAI- and Google-specific routing lives in PLATFORM_SETUP.md. Follow the host's delegation rules.
• Keep working notes and routing logs under development/. Read root guides on demand; bundled references are distribution copies and should only be read for bundle checks.
• .claudeignore is not an OpenAI or Google configuration file, nor a security boundary. Respect actual sandbox and connector permissions; do not infer access restrictions from ignore files.
• Share versioned definitions; keep credentials, app settings, native memory, scheduler registrations, and session history platform-local. Coordinate edits through branches or worktrees rather than concurrent writes to the same checkout.

Branching and Releases

Cluide is trunk-based. Work happens on a short-lived branch per change, merged into main by PR, branch deleted on merge. main is always the current, self-consistent guide set.

Do not add a develop or release branch. A stabilisation branch solves a problem this repo does not have: one maintainer, no build step, no artefact anyone pins. A fresh clone and the private companion project both read main directly, so a second integration branch would add a merge that catches nothing while leaving the consumed working tree unprotected. Version by content event instead — see Releases below.

When the maintainer asks to merge a branch, run this gate first. Name each check and its result, and stop at the first failure rather than merging past it.

1. Whole unit. The branch is a complete change, not one batch of a larger sweep. A half-applied sweep is a stop however clean the diff looks — main is public, and a partial guide set is what a stranger clones. Check the diff against the scope written into the branch's first commit message, not against your recollection of it: this is the one check in the gate where the session grades its own earlier decision, and recollection always finds it complete.
2. Guide-set coverage. Run tasks/review-tasks.md step 4c and fix everything it names. Do not restate its assertions here or anywhere else; run the check.
3. Bundled copies and registration. Whenever the branch touches a root guide or index, run tasks/review-tasks.md step 4a: every copy under any skills/*/references/ — not only ai-assistant-setup — must be byte-identical to its root counterpart, with skills/ai-assistant-setup/references/00_INDEX.md the one permitted variant, whose diff must be confined to the link-stripping that step describes. Do not restate the loop here; run it. When the branch adds or renames a guide, also assert registration completeness: step 4c proves a guide is scored, not that it is registered everywhere, so every .md citing the previous guide's number must also cite the new one. Stale bundled copies and partial registration are this repo's two known drift modes — two consecutive merges left copies outside ai-assistant-setup behind while this check named only that skill.
4. Consumed surface is append-only. Dimension numbers, tasks/ filenames, and guide numbers may be added, never renumbered, and a retired number is never reused. A branch that renumbers is a stop, not a judgement call.
5. Downstream links (maintainer-only — skip this check if you cloned Cluide to use the guides). Cluide is consumed by a private companion project that runs its own link check against this repo; if that project is mounted, run its scripts/check-cluide-links.sh. If it is not mounted, report the check as skipped — never assume it passes.
6. Squash. Merge with squash so main only ever gains complete units of work.

Check the current session’s GitHub connectivity and authorization. When authorized and available, push, open the PR, and merge after the gate passes. If a runtime cannot access GitHub, report the actual blocker and provide the remaining commands; do not assume that every cloud or desktop session has the same limitations.

Releases are content events, not a calendar. Never cut a version on a schedule and never propose one. Tag when guides are added, a reading track restructures, or the consumed surface changes: minor for additions and restructures, patch for corrections. Tags are vMAJOR.MINOR.PATCH, continuing from v1.0.0. A major bump means the append-only rule in check 4 was deliberately broken, which should effectively never happen. At each tag, record what changed in CHANGELOG.md, built from git log <previous tag>..HEAD; create that file at the first tag if it does not exist. Nothing accumulates there between tags: a pull request never edits CHANGELOG.md, and there is no ## [Unreleased] section to write under. That puts the whole weight of the changelog on commit subjects, which is why check 1 above grades the diff against the scope written into the branch's first commit message — an unscoped subject is a changelog entry nobody can write later.

Skill bundles are release assets, never commits. After the tag is pushed and verified, build one zip per skill from the tagged tree and attach them to a GitHub Release, so each download is tied to the version it came from: rm -rf /tmp/rel && mkdir /tmp/rel && git archive vX.Y.Z skills | tar -x -C /tmp/rel && (cd /tmp/rel/skills && for d in */; do zip -qr -X "../${d%/}.zip" "$d"; done), then gh release create vX.Y.Z --notes-file <notes> /tmp/rel/*.zip. skills/*.zip and skills/*.skill are gitignored so a bundle built in place cannot be committed by accident.

App-side Fields

See PLATFORM_SETUP.md for proposed bootstrap text. These are setup instructions, not a claim that any app-side setting has been changed or verified. Existing Claude app fields were last reported by the maintainer on 2026-08-07: a Claude-only description and empty instructions. Re-verify before treating those fields as current; record each platform separately when actually configured.