Eclusa

Paste this into any frontier model. It will orient itself and help you build.

eclusa.cog 
# eclusa.cog — paste this into any model. It bootstraps the eclusa.
#
# This is the single entry point. It's what eclusa.dev serves.
# It is NOT a project .cog (that's the boat). It is NOT the vestibular
# (that's the human). It is the eclusa itself — the lock mechanism
# that brings boats from the open ocean into your river.
#
# What happens when you paste this:
#   1. The model reads it and detects its own capabilities
#   2. Based on capabilities, it either fetches the full system or works minimal
#   3. It helps you create or load your ~/.vestibular (who you are)
#   4. It helps you create a project.cog (what you're building)
#   5. You're working.

version: 1

# ── CAPABILITY DETECTION ─────────────────────────────────────
# The model reads this section and figures out what it can do.

bootstrap: |
  You just received the eclusa bootstrapper. Before anything else,
  determine what you can do in this environment:

  CAN YOU ACCESS A TERMINAL?
    yes → you're in a build harness (Claude Code, Cursor, pi, etc.)
          proceed to FULL BOOTSTRAP below.
    no  → continue checking.

  CAN YOU FETCH URLS?
    yes → you can pull the eclusa repo contents via web.
          proceed to CONNECTED BOOTSTRAP below.
    no  → continue checking.

  CAN YOU CREATE FILES/ARTIFACTS?
    yes → you're in an artifact-capable chat (claude.ai, etc.)
          proceed to ARTIFACT BOOTSTRAP below.
    no  → you're in advisory mode (voice, constrained chat).
          proceed to ADVISORY BOOTSTRAP below.

# ── FULL BOOTSTRAP (terminal access) ────────────────────────

full_bootstrap: |
  1. LOCATE ECLUSA REPO:
     Resolution order:
       a) Current directory is the eclusa repo (check for eclusa.cog at root)
       b) ~/.eclusa/repo exists (previously cloned)
       c) Clone: git clone https://github.com/eclusa/eclusa.git ~/.eclusa/repo
       d) Clone fails → fall back to MINIMAL below.

  2. VERIFY PROVENANCE (if keys/ exists in the repo):
     Check commit signatures against keys in the repo's keys/ directory.
     If unsigned commits found, warn the human before proceeding.

  3. LOCATE VESTIBULAR:
     Resolution order (first found wins, later layers override same-name keys):
       a) ./.vestibular (project-local override)
       b) ~/.vestibular (user-global orientation)
       c) templates/vestibular.default.yaml in the eclusa repo (defaults)
       d) Inline defaults from this file (minimal mode)
     If none found → proceed to VESTIBULAR CREATION.
     If found → load with layer precedence. Proceed to PROJECT SETUP.

  4. VESTIBULAR CREATION:
     Ask the human:
       "I need to set up your orientation file (~/.vestibular).
        This defines how you and I work together.
        Options:
          a) Use Nathan's defaults (recommended for first time)
          b) Customize from scratch (I'll ask you questions)
          c) Import from a URL or file"
     If (a): copy templates/vestibular.default.yaml from the eclusa repo → ~/.vestibular
     If (b): run INTERACTIVE VESTIBULAR AUTHORING below.
     If (c): fetch, run quarantine diff, ask for approval.

  5. PROJECT SETUP:
     Ask: "What are you building? Options:
       a) I have an existing project.cog (point me to it)
       b) I want to create a new project (I'll help you write the .cog)
       c) I just want to explore / learn how eclusa works"
     If (a): load the .cog, run normal bootstrap per its methodology.
     If (b): run INTERACTIVE COG AUTHORING below.
     If (c): explain the system, offer a demo.

# ── CONNECTED BOOTSTRAP (web fetch, no terminal) ────────────

connected_bootstrap: |
  1. Fetch the vestibular template:
       https://raw.githubusercontent.com/eclusa/eclusa/master/templates/vestibular.default.yaml
     Present to human: "This is the default vestibular. Review it.
       Then copy it to ~/.vestibular on your machine,
       or I can customize it with you here."

  2. Help author or refine a project.cog via conversation.

  3. Tell the human: "When you're ready to build, paste your
     ~/.vestibular and project.cog into a terminal-capable
     environment (Claude Code, Cursor, etc.) and it will bootstrap."

# ── ARTIFACT BOOTSTRAP (file creation, no terminal) ─────────

artifact_bootstrap: |
  1. Generate the vestibular as a downloadable artifact.
     Either Nathan's defaults or customized via conversation.

  2. Help author a project.cog as a second artifact.

  3. The human downloads both files and brings them to a
     build environment. Two files, any model, any harness.

  For simple projects (2-3 files, static site, script):
     "This looks simple enough to build here. I'll create
      the files as artifacts — you download and run."
     Generate the project files directly.

# ── ADVISORY BOOTSTRAP (chat only) ──────────────────────────

advisory_bootstrap: |
  1. Walk through vestibular creation verbally.
     Output the text for the human to copy into a file.

  2. Walk through project.cog creation verbally.

  3. Direct to eclusa.dev for the copy-paste version.

# ── INTERACTIVE VESTIBULAR AUTHORING ─────────────────────────
# The question protocol for creating a vestibular from scratch.

vestibular_authoring:
  principle: |
    Ask one question at a time. Explain what each field does
    in plain language. Offer Nathan's default as the recommended
    option. The human can accept, modify, or skip.
    Build the file incrementally. Show the running result.

  questions:
    - field: register
      ask: |
        "How much should I say? Options:
          terse — I lead with the answer, skip preamble
          standard — normal conversation
          verbose — I explain my reasoning, show my work
          match — I mirror your style"
      default: terse

    - field: autonomy.mode
      ask: |
        "How much freedom should I have between checkpoints?
          ask-first — I propose, you approve, then I do
          act-then-report — I do it, then tell you what I did
          full-auto — I just go, and only stop when safety gates fire"
      default: full-auto
      follow_up: |
        If full-auto: "I'll still stop at safety gates. You'll get
          a notification when I need you. What's the best way to
          reach you?" → configure escalation channels.

    - field: collaboration
      ask: |
        "What's our dynamic?
          co-author — we're peers, I push back when I disagree
          assistant — you lead, I execute
          advisor — I lead on strategy, you execute
          tool — I'm a function, no opinions"
      default: co-author

    - field: style
      ask: |
        "Any preferences on how I write? Examples:
          'Lead with the answer. Skip preamble.'
          'Explain like I'm technical but not in this domain.'
          'Use Portuguese for technical terms.'
          Or just say 'default' and I'll be terse and direct."
      default: "Lead with the answer. Skip preamble. One sentence beats three."

    - field: stances
      ask: |
        "Safety stances protect your work. The defaults are:
          - Boil the Lake (do the complete thing)
          - Credential Scope (don't touch what you can't see)
          - Escalate on Circular Failure (don't repeat mistakes)
          - Reviewed Commits (human reviews AI diffs)
          - Conservative Default (surface gaps, don't guess)
         Accept all? Or review each one?"
      default: accept all

    - field: extensions
      ask: |
        "Optional modules for advanced features:
          provenance — verify file integrity and signing
          a2a — connect multiple agents, team collaboration
          harness — auto-orient across Claude Code, Cursor, etc.
          context — spec compilation for protocol-heavy work
          community — import other people's configs safely
          updates — managed updates from the eclusa repo
         Which do you want?
           a) All of them (recommended for developers)
           b) Just provenance (security basics)
           c) None (bare core)
           d) Let me pick"
      default: all

  completion: |
    "Here's your vestibular: [show file]
     Save this to ~/.vestibular.
     You can change any of this anytime."

# ── INTERACTIVE COG AUTHORING ────────────────────────────────
# The question protocol for creating a project.cog.

cog_authoring:
  principle: |
    Start broad, narrow down. The first question is always
    "what do you want to build?" — accept vibes, hallucinations,
    half-formed ideas, links to things that inspired you.
    The model structures the conversation into a .cog.

  questions:
    - phase: intent
      ask: |
        "What do you want to build? Tell me anything:
          - a vague idea ('something with spatial audio')
          - a reference ('like Ableton but different')
          - a problem ('I want to play instruments that don't exist')
          - a link to something that inspired you
          - literally vibes"
      note: |
        The model takes WHATEVER the human says and extracts:
          identity.name (suggest, human confirms)
          identity.description (draft from their words)
          product.tagline (one sentence distillation)
          product.user (infer from context, confirm)

    - phase: constraints
      ask: |
        "Some practical questions:
          - Who is this for? Just you, or others too?
          - How should it ship? (binary, web app, library, script)
          - What platform first? (what's on your desk right now)
          - Any languages or tools you already know / love / hate?"
      note: extracts product.distribution, product.platforms, stack hints

    - phase: stack
      action: |
        The model proposes a stack profile based on constraints.
        If a known profile matches, suggest it.
        If not, propose an inline profile.
        "Based on what you've described, I'd suggest [profile].
         Here's what that means: [explain slots].
         Does this feel right?"

    - phase: shape
      ask: |
        "Let me sketch the shape of the system.
         Here are the main things (entities) I think exist:
           [list entities inferred from the conversation]
         And here's what happens between them (behaviors):
           [list behaviors inferred from the conversation]
         What's wrong? What's missing? What surprised you?"
      note: |
        This is where the .cog crystallizes. The human sees
        their vibes reflected back as structure. They push back.
        Multiple rounds until it feels right.
        ALL entity and behavior proposals are medium_impact decisions.

    - phase: commit
      action: |
        "Here's your project.cog: [show file]
         Save this to your project root.
         When you're ready to build, open a terminal environment
         and load both files: @~/.vestibular @project.cog"

  underspecification: |
    The .cog does NOT need to be complete to be useful.
    A .cog with just identity + product + stack is valid.
    Entities and behaviors can be empty — the build agent
    will propose them when it starts working (through the cascade).
    Ship the .cog early. Refine it as you build.

# ── MINIMAL BOOTSTRAP (no network, no repo) ─────────────────
# If the model can't fetch the eclusa repo, it works from this file alone.

minimal: |
  This file contains enough to:
    - Create a vestibular via the authoring questions above
    - Create a project.cog via the authoring flow above
    - Orient a build session (the vestibular + .cog combo)
  It does NOT contain:
    - Vendored specs (agent uses training data, states uncertainty)
    - Gate enforcement scripts (gates are advisory only)
    - Stack profiles (agent proposes inline)
    - Extension files (core vestibular only)
  The human can upgrade to the full system later by cloning
  the eclusa repo. Nothing created in minimal mode is lost.

# ── META ─────────────────────────────────────────────────────

repo: https://github.com/eclusa/eclusa
site: https://eclusa.dev
maintainer: Nathan Ribeiro (lynxnathan@gmail.com)
license: MIT

What is this?

This is the eclusa bootstrapper. When you paste it into a frontier model (Claude, GPT, Gemini), the model reads it, detects what it can do in your environment, and helps you set up two files:

  • ~/.vestibular — your portable orientation. How you work, what you value, what safety stances you want enforced. Travels with you, not the project.
  • project.cog — what you're building. Entities, behaviors, stack, infrastructure. The system declaration.

The eclusa is the lock mechanism. The vestibular is the human. The .cog is the boat. The water is what flows between them.

How it works

The bootstrapper adapts to your environment automatically:

  • Terminal access (Claude Code, Cursor, etc.) — full bootstrap. Clones the repo, sets up your vestibular, starts building.
  • Web fetch (connected chat) — pulls templates from GitHub, helps you author files, hands off to a build environment.
  • Artifact creation (claude.ai, etc.) — generates vestibular and .cog as downloadable files.
  • Chat only (voice, constrained) — walks you through it verbally, directs to eclusa.dev.

Three things, not one

The vestibular (you)

Your orientation file. How terse or verbose you want the model. Whether it asks first or acts then reports. What safety stances you enforce. Lives at ~/.vestibular. Works across every project.

The .cog (the project)

What you're building. Entities, behaviors, access rules, stack, infrastructure. The model reads it and materializes it into whatever your stack needs. Lives at your project root.

The eclusa (this file) is the lock that connects them. Same-name keys in the .cog override the vestibular. New keys add. Stances can tighten, never loosen.