---
id: SPEC
title: "@cleepi/base"
status: shipped
created: 2026-05-24
owner: Honza
related:
  - ../../docs/specs/0001-development-process.md
---

# Spec: `@cleepi/base`

## Problem

Every Cleevian using pi should get a recognizably *Cleevio* agent on day one:
a consistent voice and a consistent visual identity. Without a shared base,
each developer's pi looks and behaves differently, and the "Cleevio-native
agent" thesis of cleepi is just words.

## Goals

- A single package every Cleevian installs first.
- Ships a system-prompt append that establishes the Cleevio voice for all
  sessions where the package is loaded.
- Ships a Cleevio-flavored theme.
- Stays small and opinionated — it is the *base*, not the kitchen sink.

## Non-goals (v0.1.0)

- Tool extensions for Slack, Linear, GitLab, Confluence, Notion, or any
  internal Cleevio service. Each is its own design problem; each gets its
  own package later.
- Shared prompt templates (`/standup`, `/pr`, etc.). These deserve their own
  design pass and likely their own package(s).
- Shared skills beyond what `@cleepi/sdd` already provides.
- Code style or project conventions — that's `@cleepi/coding` when we get
  there.
- Project-specific knowledge — that's `@cleepi/packeta*` or
  `@cleepi/knowledge`.

## Proposed design

### Layout

```
packages/base/
  package.json
  README.md
  SPEC.md
  CHANGELOG.md
  extensions/
    personality.ts              ← hooks before_agent_start, appends voice
  themes/
    cleevio-dark.json           ← Cleevio-flavored dark theme
```

### Personality extension

A pi extension that subscribes to `before_agent_start` and appends a fixed
"Cleevio voice" block to the system prompt. Idempotent (won't double-append
on repeated calls).

**Voice principles** (the actual prompt text lives in `extensions/personality.ts`):

- Concise. Shortest useful response.
- Honest about uncertainty. No fabrication. "I don't know" is a complete
  answer.
- Willing to push back. Partner-in-crime, not order-taker.
- Low ceremony. No filler greetings, no closing pleasantries.
- Czech/English bilingual fluency, defaulting to whichever the user uses.

The voice text is intentionally short and stable. Rewriting it is a
**minor** version bump (pre-`1.0.0` semantics) because it changes observable
agent behavior.

### Theme

A single dark theme called `cleevio-dark`. All 51 required tokens defined.
Palette built around a Cleevio brand color as `primary`, with neutral grays
for chrome.

Brand colors are currently **placeholder** values pending input from Honza
— this is flagged in the theme file with a `_placeholder` comment.

A light variant is **deferred** — most Cleevians use dark terminals; add
`cleevio-light` when the first person actually asks.

## Alternatives considered

- **Voice via a skill** instead of a system-prompt append. Skills are
  on-demand and not loaded into every turn's system prompt by default. Voice
  needs to be on every turn. Extension wins.
- **Voice via `AGENTS.md` shipped in the package.** Pi loads `AGENTS.md` from
  the user's filesystem (cwd, ancestors, `~/.pi/agent/`), not from packages.
  Not a delivery mechanism.
- **Multiple themes** (`cleevio-light`, `cleevio-high-contrast`). Deferred —
  ship what gets used, add variants on real demand.
- **Bundle SDD workflow** into base. Rejected in
  [ADR 0004](../../docs/adr/0004-extract-sdd-as-package.md) — coupling voice
  to a process opinion is wrong.

## Open questions

- [ ] Real Cleevio brand color palette. Placeholder `#7FB342` (a cucumber
      green, picked because of the 🥒 emoji in the repo's main README) is in
      the theme file until Honza provides the real values.
- [ ] Final voice text. The draft in `extensions/personality.ts` is a
      starting point; Honza to review and rewrite to taste before tagging
      `0.1.0`.

## Acceptance criteria

- [x] Package installable via `pi install`.
- [x] Theme `cleevio-dark` selectable via `/settings`.
- [x] Personality extension loads and appends voice text to system prompt.
- [x] README, SPEC.md, CHANGELOG.md present and following SDD conventions.
- [ ] Real Cleevio brand colors substituted for placeholders (blocks
      first real `0.1.0` tag — pre-tag the placeholders are acceptable for
      iterating).
- [ ] Voice text reviewed and approved by Honza.