AI First OS

Name: ai-first-os
Author: pedroromeroluna

Latest version and what changed in it: Releases · CHANGELOG.md.

A product operating system for working with agents. One primitive —the node— repeated at every
level: every session opens with a scan of your work, you capture whatever comes up on the fly, you
close the session with a verdict of what got done and what is missing, you mount a repo onto an
initiative, you get interviewed to write specs ready to delegate. The craft on top —discovery, the
metric brief, the interview that writes a product's strategic layer— travels in packs, each one
published as its own set of skills: see The AI First Product Skills pack below.

The skills are written in English. The deliverables come out in the language you work in.

This document is written for your agent to execute, not for you to follow step by step.

Requirements

Installing the system takes one thing: git. Python 3 is recommended. They are checked before
anything runs — an agent that installs first and reads the error afterwards leaves you with
command not found instead of an answer.

What	When it is needed	How the agent checks it	Where it comes from if it is missing
git	To install the system	`git --version`	macOS: `xcode-select --install` · Windows: git-scm.com
python3	Recommended, not required — without it the install goes on and warns that two features are missing: connecting a code repository (`mount-repo`) and Living Memory search (`recall`). It is found as `python3`, `python` or `py -3`	`python3 --version` (or `python --version`, or `py -3 --version`)	macOS: `xcode-select --install` (same command as git) · Windows: python.org · Linux: your distro's package manager
Node.js	Only for the `npx` install path and for the pack of skills offered at the end of the install — installing the system by git clone never needs it	`node --version`	The LTS installer at nodejs.org

The agent guides; you install. System software is never installed by the agent on its own: it
points at the official channel, waits for you to run it, and checks again.

git has no path around it. Every brain is versioned from the moment it exists — that is what gives
you an auditable history and updates you can undo — so nothing gets written until git is there.
Install it and say "run bootstrap" again; nothing you already answered is lost.

Python 3 does not stop the install. Without it the system installs completely and warns, once,
that two features will not be available: connecting a code repository (mount-repo) and Living Memory
search (recall; the AI searches files as plain text instead). Install Python from python.org later
and they start working; nothing needs to be reinstalled.

Node is not a requirement of the git-clone path below, and that path never runs npx. Node
belongs to two optional things: installing with npx ai-first-os instead of cloning, and the pack of
skills offered at the end of either path, which travels through the skills.sh CLI —npx, which is
part of Node—. Without Node, use the git-clone path; the system installs completely either way, and
the pack stays as a task in your backlog with the exact command in it until you have Node.

Install

Claude Code

With Node.js, npx is the short path. Paste this to your agent, once:

Run npx ai-first-os, then read and follow the exact path it prints — that is the skill that
conducts the interview.

npx ai-first-os checks the two requirements from the table above the same way the rest of this page describes, then leaves
the system at ~/.ai-first-os — replacing whatever was there before, never merging with it — and
prints the path of the skill to read next. It never installs system software, never asks a question,
and never runs anything from what it just copied. Do not replicate what it does by hand: a
hand-copied install skips the symlinks the system needs and leaves it broken; the script is the
deliverable, and running it again is always the fix.

Without Node.js, clone the repository instead. Save this message and paste it to your agent,
once:

Install AI First OS from github.com/pedroromeroluna/ai-first-os. Bring the repository down to a
fixed local folder on this machine —you will need it to update later—, run its bootstrap to build
my brain with a short interview about who I am and which workspaces I work in, if any, and then
run its installer to hook it into that brain. Ask me whatever the interview needs before writing
anything.

You do not have to do anything else, either way. The agent brings the system down, interviews you and
hooks up the tools; you only answer the interview.

That is the full install: the session contract, the two resolvers, the three delegation subagents
and the eleven skills of the system, hooked in by symlink. Nothing is downloaded from a registry and
nothing asks you to confirm an install in the middle, beyond npx's own one-time download prompt on
the first path.

The pack comes at the end. With the brain already built, the agent offers the AI First Product
Skills pack —the craft on top. With Node present it is one question, and the download asks you to
confirm once. Without Node, the exact command stays as a task in your backlog, and any session runs
it the day you have Node. Either way the system is already yours.

The eleven of the system are not published one at a time, and that is on purpose: each of them writes
into a brain, so on its own —without the session contract, the resolver and the tree of paths— it
has nowhere to write. What you can try one at a time is a pack.

Update

Paste this to your agent:

Update the system.

That sentence is enough, and this is the only place that says what it does — the manual in your
brain and the bootstrap skill point here instead of telling the story again. The update has three
parts, and each one runs only when it applies:

The system. The agent goes to the local folder where the repository ended up, brings down the
newest version and runs core/install.sh from that folder.
The pack, if you installed it. The agent runs
npx --yes skills add pedroromeroluna/ai-first-product-skills --agent claude-code --yes again, which replaces the skills in
.claude/skills/ with the published version. With no pack installed there is nothing to refresh, and this half is skipped.
The Obsidian look. The agent runs .os/core/lib/obsidian-look.sh --brain . from your brain. A brain that
already has the look gets the new version of its style files, without being asked. A brain that never
answered is asked once. A brain that said no is left alone.

Your brain —your workspaces, your decisions, your content— is not touched: the update only
refreshes the tools and, if you took it, the style files of the Obsidian look. And if the installer were run by mistake through the hook that is already
installed, it stops on its own with a message before writing anything.

Layout

This is what the install leaves you with once the interview is answered: a folder —your brain—
versioned with git, that every session opens by scanning. Everything in it is a plain text file
you can read in any editor. The tools are not copied in: they are symlinks to the repository you
brought down, so an update refreshes every brain that points at it.

my-brain/
├── AGENTS.md                    # Symlink to the session contract: what the agent does at every start. Read-only on an installed copy
├── HOW-IT-WORKS.md              # The user manual, symlinked in your language (it is the Spanish manual in a Spanish brain)
├── account/
│   ├── operator.md              # Who you are and how you want to be answered — written by the interview. Your own rules go here
│   └── voice/voice.md           # How you write, so what the agent drafts in your name sounds like you
├── .system/
│   ├── resolver.md              # Your root resolver: capability → tool; its rows win over the product's
│   ├── tree.md                  # Which paths a scan walks — a level of the system is a line here
│   └── mounts.md                # Which repos are mounted onto which initiatives (born on first mount-repo)
├── workspaces/                  # One folder per workspace — the isolation boundary. `personal` is your
│   │                            # own work, born with the brain; a company or a client is another one
│   └── <workspace>/
│       ├── README.md            # Its identity, and the `role:` it activates (cpo, cto)
│       ├── resolver.md          # Where whatever gets written in this workspace goes
│       ├── decisions.md         # Index of its decisions: one line each, linking to its own file
│       ├── decisions/<date>-<slug>.md  # One decision per file: what, why, and what would invalidate it
│       ├── learnings.md         # Index of its learnings: one line each, linking to its own file
│       ├── learnings/<slug>.md  # One learning per file, no date in the name — it updates in place
│       ├── initiatives/<slug>/README.md  # Its initiatives, one folder each, status/horizon/owner up top
│       ├── initiatives/<slug>/backlog.md # That initiative's tasks, one line each (born on its first capture)
│       └── <type>/<slug>/       # A memory node of any declared type — products/ is the one this system ships with its own tool
│           └── README.md        # Born with `new-memory --type <type>` (`new-product` is its `products` shortcut); `context/` and `research/` are filled by whatever tool the type has, or by hand
├── .os/
│   ├── core -> …/ai-first-os/core        # The chassis by symlink: the eleven system skills in core/skills/, the shell in core/lib/
│   └── packs/<pack> -> …                 # Each installed pack, by symlink
└── .claude/
    ├── CLAUDE.md                # The same symlink as AGENTS.md: Claude Code reads the contract from here
    ├── agents/                  # complete-spec, ambiguous-spec, scout — one symlink each
    └── skills/                  # The pack's skills, one folder each, left here by `npx skills add` (born with the first skill)

The interview writes account/operator.md, account/voice/voice.md, .system/resolver.md, .system/tree.md and workspaces/personal/ —
your own work, the one every brain is born with — plus one more workspaces/<slug>/ per workspace
you named. The rest is born the first time it is needed: an initiative's backlog.md on
its first capture, .system/mounts.md on the first mounted repo, decisions.md/decisions/ and
learnings.md/learnings/ when there is something to record — one file per decision and per
learning, with the .md index left as the table of contents so a session opens only the one it
needs instead of the whole register.

Where the skills live. The eleven skills of the system are not copied into your brain: they live
in .os/core/skills/, a symlink to the core/ of the repository you brought down, and the agent
reaches them through the resolver. The skills of the pack are what npx skills add installs: one
folder per skill under .claude/skills/<name>/SKILL.md —the place Claude Code reads skills from, which is why they show up as /cpo, /prd and so on— plus
product-builder-resolver, the pack's index. Your own skills, if you write any, go next to them as
plain folders in .claude/skills/.

The catalog

Seventeen skills come with the system itself, in two families. Workflow skills run a process and
leave a deliverable: they are triggered manually, by name — the index is the resolver, never
automatic activation. Knowledge skills carry a method or a standing craft and are loaded as
context.

Workflow skills

Name	What it does
`bootstrap`	Creates the brain from scratch: identity, voice, root resolver, the tree of paths a scan walks, one folder per workspace
`new-workspace`	Adds a workspace — the isolation boundary — with its identity, its resolver and its initiatives
`new-product`	Adds a product to a workspace — memory: what it is, for whom, what is known — with its identity
`new-memory`	Creates a memory-node type the first time it is used —a folder plus its five lines in `tree.md`— and adds a node to it, inside the workspace it belongs to
`sweep`	The three global scans: what is pending, what is blocked and why, how the roadmap is going
`check-resolvable`	Audits the capability-to-tool graph and reports dark tools, broken links and rows pointing nowhere
`capture`	Files what you throw in mid-conversation into the right backlog, without opening a discussion
`close-session`	Closes the session with a four-part verdict: captured, not captured, candidate resolver row, where to resume
`mount-repo`	Gives an initiative a body: the remote in the head, the checkout outside the brain (or the repo born from the scaffold, with `--new`), the row in the environment table
`grill`	The pressure interview: counter-question with a concrete example, capped attempts, escape hatches, evidence hierarchy
`new-spec`	Writes a spec an agent can implement without asking for an opinion — one runnable eval per criterion
`supersede`	Marks a file as replaced by another —`superseded_by:` in the frontmatter of the old one— so a session that opens it knows what to read instead, and audits the marks of the whole brain
`rename-workspaces`	Adopts the current name of the workspaces folder on a brain born before it, run only when the operator asks
`rename-heads`	Adopts the single node shape —a folder with its `README.md` inside— on a brain born before it, run only when the operator asks
`migrate-root`	Moves a brain's own root work —initiatives, a memory-node type, backlog, decisions, learnings— into `workspaces/personal`, run only when the operator asks
`migrate-layout`	Brings a brain with the old layout to the new one, printing the whole plan first and writing nothing until `--apply`; run only when the operator asks
`archive`	Moves a document into the node's `archive/` so the focus lists it by name instead of loading it, rewriting every reference that pointed at it, and lists what the brain already declared replaced and still loads
`recall`	Searches every file the tree reaches for a lateral question, ranked with file, line and date, current work ahead of whatever replaced it, and one jump to a result's neighbours with `--expand`
`orchestrator`	Optional, off until you ask: one session that hands each topic's work to that topic's session and keeps what it needs to remember in a hidden file, with a full mode in the desktop app and a reduced one in the terminal

Knowledge skills

None of them travels with the system: a standing craft belongs to the pack that carries it. Two
exist today, both in the pack below: cpo, the standing craft of a Chief Product Officer, and
cto, the standing craft of a Chief Technology Officer, written for a builder who directs an agent
but cannot read a diff. cto never opines on models, prices or capabilities from memory: it
verifies the state of the art live before answering, so it stays current with the latest in AI
without anyone editing the file.

The AI First Product Skills pack

The craft of building product —discovery from a vague problem to the strategic layer, the metric
brief, the pressure interview, the standing crafts of a CPO and a CTO— is published as its own set
of skills, in the Agent Skills format that any harness reading that standard can install:

npx skills add pedroromeroluna/ai-first-product-skills

11 skills plus the pack's own index. The bootstrap above offers that command at its close,
and leaves it in your backlog if you take it later: this section is here for the other two cases —
trying the pack before installing the system, and adding it to a brain that was born before the pack
existed.

One at a time with --skill <name> — for example
npx skills add pedroromeroluna/ai-first-product-skills --skill product-strategy.

Trying one skill is the way to test the toolkit before trusting it with a system install. They
work on their own, in any project, with nothing else installed: a small skill, a small blast radius,
a real deliverable. Installed that way the deliverable is a file in the current folder; installed
inside the system it lands in the node it belongs to. If what they do earns your trust, the full
install above is the system they came from.

License

MIT. See LICENSE.