Skip to content
EidosDocsRegistry

Quick Start

The CLI does the mechanical parts: scaffolding, frontmatter, validation, the index. You do the part only you can: decide what the product is.

  1. Install the CLI

    Section titled “Install the CLI”
    Terminal window
    npm install -g eidosmd
    eidos --version

    Node 20 or newer. Every command works on Node 20; the browser page’s search is SQLite full text on Node 22.16 or newer (or Node 24) and a simpler in-memory scan on an older Node. npx eidosmd works without installing.

  2. Create a root

    Section titled “Create a root”
    Terminal window
    eidos install @BuildableWorks/software --group identity --product "My Product"

    A root is the folder your blueprints live in. install copies a starting framework (a seed) into Blueprints/, shows its plan, and asks before writing. Pick the nearest seed; everything it gives you is reshapeable later.

    Seed For
    @BuildableWorks/software A product, service, or system being built
    @BuildableWorks/book A book, long-form argument, or course
    @BuildableWorks/research A question, a study, a programme of inquiry

    Settle two things now, because both are awkward to change later: the root folder’s name (Blueprints/ by default; any name works) and the naming convention (--naming kebab-case, the default, TitleCase, or "Title Case"). Naming →

    • DirectoryBlueprints/
      • README.md the front door
      • Directory.eidos/ the framework
        • Framework.yaml folders, properties, vocabulary, the index
        • Directorytemplates/ one body template per variant
          • …
        • Directoryroles/ how an agent talks to each kind of person
          • …
        • me.md who you are (local, gitignored)
      • Directoryassets/ images and documents the blueprints link to
        • …
      • Directoryframes/ what the whole product is: one blank frame per kind
        • …
      • Directoryspecs/ the units, grouped one level deep
        • Directoryidentity/
          • …

    install writes no prose. The README’s one-liner, each group’s description, and every frame are yours.

  3. Say who you are

    Section titled “Say who you are”
    Terminal window
    eidos roles
    eidos whoami --role developer --ownership "the whole product" --experience deep --capacity fluent

    This writes .eidos/me.md. An agent reads it before acting to decide how to respond. Blank is fine. Roles →

  4. Fill the frames

    Section titled “Fill the frames”

    The frames describe the whole product: for software, its architecture, audience, criteria, and market. Every other blueprint is judged against them. Fill what’s known; leave the rest. Frames →

  5. Scaffold a blueprint

    Section titled “Scaffold a blueprint”
    Terminal window
    eidos new specs "Resume Playback" --group identity --variant micro --summary "Returns a viewer to the exact second they stopped."

    The file is born conforming: frontmatter from the properties that apply to specs, body from the micro template, filename in your convention, a permanent id inside. Start on the light variant; grow into full when the fuller sections earn their place.

  6. Write it

    Section titled “Write it”

    Open the file and work through the sections. Two things decide whether it is any good:

    • Lead with ## Intent: why this exists, and who has the problem. If the intent changes substantially, you have a different blueprint.
    • Write ## Out of Scope second, not last. It is where scope is held. Why →

    No tool will do this part. new scaffolds, check reports, an agent asks and formats. None of them decides what the product is. Working with agents →

  7. Check, index, browse, commit

    Section titled “Check, index, browse, commit”
    Terminal window
    eidos check
    eidos index
    git add Blueprints && git commit -m "add product blueprints"

    check reports what is missing or malformed: a review to act on, not a gate. index rebuilds the index inside Framework.yaml. To browse the root, open its folder in Eidos MD. Commit all of it; the seeded .gitignore keeps me.md out.

With an agent

Section titled “With an agent”
Terminal window
eidos agents --write

This puts a short note in AGENTS.md so any coding agent with a shell reads eidos instructions before touching a blueprint. Agents →

From here

Section titled “From here”