--- id: SPEC title: "@cleepi/coding" status: shipped created: 2026-05-24 owner: Honza related: - ../../docs/specs/0001-development-process.md - ../../docs/adr/0004-extract-sdd-as-package.md - ../sdd/SPEC.md - ../base/SPEC.md --- # Spec: `@cleepi/coding` ## Problem `@cleepi/base` establishes the Cleevio voice across *every* session. But when a Cleevian is actually writing code, additional opinions apply: code review mindset, naming, comments, when to refactor, when to test. Those don't belong in base (they'd burn context on non-code sessions) and they don't belong in sdd (which is process, not craft). Separately: when SDD is the agreed process, the agent should be *reminded* of it in code sessions — without coupling the coding package to sdd by hard dependency (ADR-0004 explicitly keeps them as peers). ## Goals (v0.1.0) - A pi package that, when installed, makes the agent a better coding partner *specifically*, on top of what base provides. - Codify Cleevio coding opinions in one on-demand skill that the agent loads when the task is code-shaped. - Make SDD discoverable from code work: if `@cleepi/sdd` is also installed, surface it explicitly so the agent reaches for `/spec`, `/adr`, etc. before cutting code. If sdd is not installed, suggest it. - Ship a small, opinionated set of code-focused slash prompts — the ones Cleevians will use across every project regardless of language. ## Non-goals (v0.1.0) Explicitly out of scope for this version. Each may become its own package or its own future spec inside `coding`: - **Sub-agents** (`implementer`, `reviewer`, `spec-writer` definitions). To be designed in a future repo-level spec (see [root README roadmap](../../README.md)); built on top of the abstractions in sdd + base + coding once stable. - **Language-specific tooling** (eslint configs, prettier configs, tsconfig templates, Python style configs). Belongs in language- or project-specific packages (`@cleepi/packeta-fe`, etc.). - **PR templates / commit-message conventions**. Real, but project-policy; belongs in project packages. - **Deploy / release workflows**. Out of scope; would belong in a future `@cleepi/release` if demand emerges. - **A `coding` theme**. Theming is base's job. - **Hard SDD enforcement** (blocking writes if no spec exists). See *Alternatives considered*; rejected as annoying. ## Proposed design ### Layout ``` packages/coding/ package.json README.md SPEC.md CHANGELOG.md extensions/ coding.ts ← personality append + SDD awareness skills/ coding/ SKILL.md ← on-demand coding craft principles prompts/ review.md ← /review — review the current diff ``` (Final prompt set is an *Open question* — see below.) ### Personality extension (`extensions/coding.ts`) Hooks `before_agent_start`. Idempotent via a marker comment, same pattern as base's personality extension. Appends two things to the system prompt: 1. **Coding voice** — a short block of code-specific defaults (separate from base's general voice): - Readable > clever. - Comments explain *why*, not *what*. - Delete dead code on sight. - Names should pay rent. - Tests for behavior, not implementation. - Small, reversible steps. 2. **SDD awareness, conditional on what's loaded**: - Inspect `event.systemPromptOptions.skills`. - If a skill named `sdd` is present: append "When the work is non-trivial, follow SDD: write a spec first, accept it, then implement. Use `/spec`, `/adr`, `/changelog`. Load `/skill:sdd` if you need the workflow details." - If `sdd` is not loaded: append a softer "Cleevio's default process is Spec-Driven Development. Install `@cleepi/sdd` for the prompts and skill." No hard dependency on `@cleepi/sdd` in `package.json`. ### Skill (`skills/coding/SKILL.md`) On-demand reference for *code craft*, not process. Loaded when the agent recognizes code work. Contents: - Code review checklist (what to look for, in order). - Refactoring posture (when to refactor in-line vs. propose, how to keep refactors reviewable). - Naming guidance with examples of bad → better. - Comment policy (why-not-what, when to skip). - Testing posture (what's worth testing, what isn't). - Error handling defaults (fail loud at boundaries, recover gracefully inside). - "Skip the dance" boundary — same trivial-work exemption as `AGENTS.md`. Language-agnostic by design. Examples may use TypeScript since that's the common case in Cleevio, but principles apply broadly. ### Slash prompts Minimum viable set: **`/review`** only, scoped to "review the current diff." The full v0.1.0 prompt set is an **Open question**; see below. ### What `coding` does *not* duplicate from base - Voice: base owns the general voice. Coding adds a *code-specific* voice layer on top, not a replacement. - Theme: base owns the theme. Coding has none. - Bilingual default: inherited from base; no need to restate. ## Alternatives considered - **Hard dependency on `@cleepi/sdd`** (installing coding installs sdd). Rejected — violates the spirit of ADR-0004 (peers, not bundled). Some teams will want code opinions without our process opinion. - **Bake SDD content directly into coding's skill** (no separate sdd package). Rejected — would force the same coupling and duplicate the SDD package's content. Soft-awareness (option B in the design discussion) gives us the integration without the coupling. - **Hard SDD enforcement** via `tool_call` hooks that block `Write`/`Edit` when no accepted spec exists. Rejected as a v0.1.0 feature — high false- positive rate, annoying friction. Re-evaluate if soft-awareness proves insufficient. - **Large prompt library shipped on day one** (`/review`, `/explain`, `/refactor`, `/test`, `/pr-description`, `/commit`, ...). Rejected — prompts that don't get used become noise in the autocomplete dropdown. Ship what we'll actually use; add on real demand. - **A coding-specific theme**. Rejected — theming belongs in base. ## Open questions - [ ] **Prompt set for v0.1.0.** My recommendation: `/review` only. Possibly add `/pr-description` (generate a PR description from a diff) since that's a consistent shape across projects. Skip `/explain`, `/refactor`, `/test` — these are well-served by just asking the agent, no template needed. **Honza to confirm before implementation.** - [ ] **Coding voice text — final wording.** Drafted as a list above; actual prose will be written into `extensions/coding.ts` and is open to rewrite by Honza, same flow as base's personality. Pre-tag draft is acceptable. - [ ] **Skill section on AI-pair-programming etiquette?** E.g. "when working with a human reviewer in the chat, surface uncertainty early, don't apologize for clarifications." Could fit base's voice instead. Defer decision until skill is written and we see the shape. - [ ] **Should coding's extension warn (once per session) when sdd is missing**, or stay silent and just embed the suggestion in the system prompt? Quieter is better but less visible. Default: silent / system-prompt only. ## Acceptance criteria - [ ] Package installable via `pi install`. - [ ] Personality extension loads and appends both blocks (coding voice + conditional SDD awareness) to the system prompt. - [ ] Skill `coding` discoverable as `/skill:coding`. - [ ] At least `/review` registers as a slash command. - [ ] README, SPEC.md, CHANGELOG.md present and follow SDD conventions. - [ ] Spec acceptance criteria from open questions resolved (or explicitly deferred with a follow-up ADR or spec).