# Workspace setup

> Run loopany init, verify bundled kinds copied, complete ONBOARDING.md once, register cadence (cron vs session-boundary), and confirm doctor passes.

- Repository: superdesigndev/loopany
- GitHub: https://github.com/superdesigndev/loopany
- Human docs: https://grok-wiki.com/public/docs/superdesigndev-loopany-97bd9ab97ae8
- Complete Markdown: https://grok-wiki.com/public/docs/superdesigndev-loopany-97bd9ab97ae8/llms-full.txt

## Source Files

- `src/commands/init.ts`
- `ONBOARDING.md`
- `INSTALL_FOR_AGENTS.md`
- `src/commands/doctor.ts`
- `skills/loopany-core/kinds/mission.md`
- `skills/loopany-core/kinds/person.md`
- `skills/loopany-resolver/SKILL.md`

---

---
title: "Workspace setup"
description: "Run loopany init, verify bundled kinds copied, complete ONBOARDING.md once, register cadence (cron vs session-boundary), and confirm doctor passes."
---

`loopany init` scaffolds the per-user brain at `$LOOPANY_HOME` (default `~/loopany`): directories, `config.yaml` with the current `schemaVersion`, and a one-time copy of bundled kind definitions from `skills/loopany-core/kinds/`. A healthy workspace still needs a single onboarding pass (`ONBOARDING.md`), an agent-chosen cadence for review/reflect skills, and `loopany doctor` exit `0` before routine capture and graph work.

## Prerequisites

| Requirement | Notes |
|-------------|--------|
| Bun | Runtime for the CLI (`bun install && bun link` from the repo checkout) |
| `loopany` on `PATH` | Typically `~/.bun/bin` after `bun link` |
| Writable brain directory | Default `~/loopany`; override with `LOOPANY_HOME` |

<Note>
`LOOPANY_HOME` is read on every command via `getWorkspaceRoot()` — the workspace is per user, not per shell cwd.
</Note>

## Workspace layout after init

`runInit()` creates the root, `kinds/`, and `artifacts/`, writes `config.yaml` if missing, and copies any bundled `*.md` kind files not already present. It does **not** create `references.jsonl` or seed artifacts; those appear on first `refs add` / `artifact create`.

```text
$LOOPANY_HOME/                    # default ~/loopany
├── config.yaml                   # schemaVersion: <SCHEMA_VERSION> (currently 0.2.0)
├── kinds/                        # copied from repo skills/loopany-core/kinds/
│   ├── brief.md, journal.md, learning.md, mission.md, note.md
│   ├── person.md, signal.md, skill-proposal.md, task.md
├── artifacts/                    # empty until onboarding / capture
├── audit.jsonl                   # first line written on first CLI op (e.g. init)
└── references.jsonl              # created when first edge is added
```

## Initialize the workspace

<Steps>
<Step title="Run init">

```bash
loopany init
```

With a custom root:

```bash
LOOPANY_HOME=/path/to/brain loopany init
```

</Step>

<Step title="Confirm CLI output">

| Outcome | stdout signal |
|---------|----------------|
| First run | `Initialized loopany workspace at …` and `Created N file(s).` |
| Idempotent re-run | `Workspace already initialized — nothing to do.` |
| Needs onboarding | Blank line, then `NEXT — read ONBOARDING.md…` |

Init is idempotent: existing files (including kind copies) are left untouched; only missing pieces are added.

</Step>

<Step title="Verify bundled kinds">

```bash
ls "$LOOPANY_HOME/kinds"
loopany kind list
```

E2E expects exactly nine files under `kinds/`:

`brief.md`, `journal.md`, `learning.md`, `mission.md`, `note.md`, `person.md`, `signal.md`, `skill-proposal.md`, `task.md`.

`loopany kind list` prints JSON with one entry per loaded kind — use it when you need parsed schemas, not just filenames.

</Step>
</Steps>

### Init implementation constraints

- **Source of kind defs:** `skills/loopany-core/kinds/` in the repo checkout (not TypeScript enums).
- **Mission probe:** `needsOnboarding` is true when `artifacts/missions/` has no `*.md` files (any mission file suppresses the nag, not only `active`).
- **Audit:** `init` writes an `audit.jsonl` entry (`op: init`, ISO `ts`).

## Onboarding (run once)

`ONBOARDING.md` is the agent script for the first conversation. Rules that affect workspace health:

| Rule | Behavior |
|------|----------|
| Run at most once | If a `mission` with `status: active` already exists, exit immediately |
| Pre-read | `loopany --help` + skim `$LOOPANY_HOME/kinds/*.md` before speaking |
| Phase 3 artifacts | Person for the user + one or more `mission` artifacts with `status: active` and `hypothesis` set |
| Backfill | Optional silent capture with `[backfill]` prefix per `skills/loopany-capture/SKILL.md` |

### Artifacts doctor expects

`loopany doctor` onboarding check requires:

1. **Person id `self`** — `idx.byId('self')` must exist (v0.2 slug-as-id). Create with:

   ```bash
   loopany artifact create --kind person --slug self --name "Your Name"
   ```

   <Warning>
   `ONBOARDING.md` Phase 3 still says `prs-self`; that was the v0.1 id. On v0.2 workspaces, use `--slug self` or doctor fails with `self person artifact missing`.
   </Warning>

2. **≥1 active mission** — e.g.:

   ```bash
   loopany artifact create --kind mission --slug ship-v1 \
     --title "Ship loopany v1" --status active
   ```

After onboarding, `loopany init` no longer prints the `ONBOARDING` hint (any mission file under `artifacts/missions/` is enough).

### Resolver gate

`skills/loopany-resolver/SKILL.md` blocks all other skills until bootstrap passes:

```bash
loopany artifact list --kind mission --status active
```

No active mission → read `ONBOARDING.md` and stop.

## Cadence: cron vs session-boundary

Recurring work is defined in skills, not in `loopany init`. `INSTALL_FOR_AGENTS.md` Step 4 assigns **how** those skills fire — without asking the user to choose cron mechanics.

| Cadence | Skill | Role |
|---------|-------|------|
| Daily | `skills/loopany-review/SKILL.md` | `loopany followups --due today`; close items with state transitions |
| Weekly | `skills/loopany-review/SKILL.md` | Overdue sweep + `loopany doctor` + parking-lot queries |
| Weekly | `skills/loopany-reflect/SKILL.md` | Learnings + skill-proposals from recent outcomes |
| Monthly | `skills/loopany-review/SKILL.md` | Mission-drift and structural-drift detection |

```mermaid
flowchart LR
  subgraph durable ["§A Durable cron hosts"]
    CRON[Platform cron]
    CRON --> REV[loopany-review]
    CRON --> REF[loopany-reflect]
  end
  subgraph session ["§B Coding CLIs default"]
    START[Session start]
    START --> FU["followups --due today"]
    END[Week / month boundary]
    END --> SWEEP[Weekly review + reflect suggest]
  end
```

<Tabs>
<Tab title="§A — Durable cron (Hermes, OpenClaw, …)">

Register each skill on its schedule using the host’s cron mechanism. Run inside an agent session (judgment-heavy), not as bare shell-only cron unless you build a wrapper task.

Record job IDs / config paths for re-install audits. Do not describe registration to the user — only the plain-English cadence line below.

</Tab>
<Tab title="§B — Coding CLIs (default)">

Do **not** register platform cron on Claude Code–class hosts: recurring tasks expire (~7 days on Claude Code), so jobs die silently.

**Default:** prompt at session boundaries — start of day → `loopany followups --due today`; end of week → propose weekly review + reflect; month-end → mission review.

System-level `launchd` / crontab is optional future work captured as a `task` artifact if the user asks; not an onboarding question.

</Tab>
</Tabs>

### User-facing cadence line

End onboarding with one sentence (from `INSTALL_FOR_AGENTS.md`):

> I'll check in at the start of each day on what's due, propose a sweep + reflect at week's end, and surface mission-drift around month's end. You can run `loopany factory` anytime for a visual map of what's in here.

No registration menus or host-quality discussion during setup.

## Resolver injection (agent hosts)

Workspace files alone do not load skills. Append `injections/resolver-memory.md` into the host memory file so every task ends with a read of `skills/loopany-resolver/SKILL.md`:

```bash
grep -q "loopany skill resolver" ~/.claude/CLAUDE.md 2>/dev/null || \
  cat ~/loopany-src/injections/resolver-memory.md >> ~/.claude/CLAUDE.md
```

<Info>
`loopany doctor` does not yet verify resolver registration (noted as roadmap in `INSTALL_FOR_AGENTS.md`). Verify with `grep -l "loopany skill resolver"` on the target memory file.
</Info>

## Verify with doctor

```bash
loopany doctor
# machine-readable:
loopany doctor --format json
```

| Exit code | Meaning |
|-----------|---------|
| `0` | No check with `status: fail` |
| `1` | At least one failed check (stdout still prints the report) |

Doctor runs `bootstrap({ skipVersionCheck: true })` so it can **report** schema mismatch instead of throwing `SchemaVersionMismatchError`.

### Check inventory

| Check | Fail? | What it validates |
|-------|-------|-------------------|
| `workspace` | — | Always ok if doctor ran (path echoed) |
| `schema version` | fail | `config.yaml` `schemaVersion` vs binary `SCHEMA_VERSION` |
| `kinds` | fail | Every kind file parses; lists loaded kinds |
| `artifacts` | fail | All indexed frontmatter passes per-kind Zod |
| `references` | fail | No dangling `from` / `to` in `references.jsonl` |
| `onboarding` | fail | `self` person + ≥1 `mission` with `status: active` |
| `mission coverage` | warn | Tasks without a mission in `mentions` |
| `domain coverage` | warn | Artifact `domain` not in `enabled_domains` |

Fresh init → doctor fails onboarding (`self` / active mission missing). Minimal green path (matches e2e):

```bash
loopany artifact create --kind person --slug self --name "Test User"
loopany artifact create --kind mission --slug g1 --title "Test mission" --status active
loopany doctor
```

### Schema mismatch before doctor is green

If `schema version` fails, run the migration named in `problems`, e.g. `loopany migrate v0.1.0-to-v0.2.0`, following `skills/migrations/v0.1.0-to-v0.2.0/SKILL.md`. Do not hand-edit `schemaVersion` alone.

## Setup flow (end-to-end)

```text
install CLI (bun link)
    → loopany init
    → verify kinds/ + kind list
    → ONBOARDING.md (once) → self + active mission(s)
    → pick cadence §A or §B silently
    → optional resolver-memory injection
    → loopany doctor (exit 0)
    → resolver bootstrap OK → routine capture / review
```

## Troubleshooting

| Symptom | Likely cause | Fix |
|---------|--------------|-----|
| `No loopany workspace at … Run loopany init` | Missing `kinds/` under `$LOOPANY_HOME` | `loopany init` |
| Init keeps printing `ONBOARDING` | No `artifacts/missions/*.md` | Complete onboarding |
| Doctor: `self person artifact missing` | No person id `self` | `artifact create --kind person --slug self …` |
| Doctor: `no active mission` | Missions missing or none `active` | Create mission with `--status active` |
| Kind list empty / errors | Broken files in `kinds/` | Compare to bundled set; fix YAML in kind frontmatter |
| Doctor schema fail | Workspace older than binary | `loopany migrate …` per doctor `problems` |
| Cron “stopped working” on coding CLI | Session-scoped cron expiry | Switch to session-boundary prompts (§B) |

<Warning>
Warnings (`mission coverage`, `domain coverage`) do not change the exit code. Treat fails (`onboarding`, `references`, `schema version`, etc.) as blocking.
</Warning>

## Related pages

<CardGroup>
<Card title="Installation" href="/installation">
Clone, Bun, `bun link`, `PATH`, and resolver injection into Claude Code / Codex / other hosts.
</Card>
<Card title="Quickstart" href="/quickstart">
First session after setup: mission, task, reference edge, optional factory.
</Card>
<Card title="Artifacts and workspace" href="/artifacts-and-workspace">
On-disk layout, slug-as-id rules, and `config.yaml` fields.
</Card>
<Card title="Doctor and troubleshooting" href="/doctor-and-troubleshooting">
Per-check failures, dangling refs, and recovery commands.
</Card>
<Card title="Periodic review" href="/periodic-review">
Daily followups, weekly doctor sweep, monthly mission drift.
</Card>
<Card title="Configuration reference" href="/configuration-reference">
`LOOPANY_HOME`, `LOOPANY_SKIP_VERSION_CHECK`, `schemaVersion`, `enabled_domains`.
</Card>
</CardGroup>