🧠 Concepts¶

The ideas behind SLMCode — so the rest of the docs feel inevitable instead of magical. Also: fewer “why is it like this?” Slack threads. 😅

01 Harness ≠ model 🧰¶

A model predicts tokens. A harness decides what the model sees, when it acts, how failures recover, and where knowledge sticks.

Frontier tools often hide the harness behind a chat box. SLMCode makes the harness explicit — like leaving the kitchen lights on.

02 Scoped packs (the turkey rule) 🦃¶

Stuffing the whole repo into context is how small models fall asleep mid-sentence.

Each specialist receives a TaskPack:

• slices of PROJECT / CONTEXT / MEMORY / skills
• a few focus files
• one atomic task
• tool allowlists that match the role

flowchart TD
  Repo[Whole repo 🏢] -.->|never wholesale| Model[Model 😴]
  Pack[TaskPack 📦] --> Model2[Model 😎]
  Pack --> MD[.slmcode markdown]
  Pack --> Files[Focus files]
  Pack --> Skill[Matched skills]
  Pack --> Task[Atomic task]

Bigger models still benefit: less noise, clearer acceptance criteria, cheaper runs. (Your CFO’s favorite sentence.)

03 Plan → split → coordinate 📋¶

query
  → instructions (AGENTS.md / PROJECT.md)
  → skills match
  → context agent
  → explore OR reuse memory
  → clarify (interview: ask|auto recommended → Locked PRD)
  → scope judge (every task gets concrete acceptance / PRD)
  → planner (multipass) → splitter → sanitize (+ auto tester task)
  → coordinator advice
  → parallel execute (worker smoke + acceptance smoke + static/claims)
  → review ↔ correct (≤ max_retries)
  → escalate HITL if stuck (timeout → @escalate SLM decides)
  → placeholder polish → completeness bar
  → finalize tester (real commands required)
  → QA gate (install deps + pytest preferred — not compileall alone)
  → continue-ask if work remains
  → learn → evolve skills → session snapshot

The coordinator doesn't write code. It steers the kanban: promote, reassign, add tasks, note risks. Think air-traffic control, not pilot. ✈️

04 Explore reuse ♻️¶

Deep exploration is expensive (especially on slow local inference).

If CONTEXT is rich, MEMORY/PROJECT exist, and discovery finds relevant paths, SLMCode skips the deep dive and reuses knowledge. Your fans thank you. Your GPU fans thank you louder.

# When memory feels stale or wrong:
SLMCODE_FORCE_EXPLORE=1 slmcode run -v "…"

05 Building blocks 🧱¶

SLMCode pipelines, agents, quality checks, and language packs are all YAML-configurable building blocks — versioned, shareable, and marketplace-ready.

# .slmcode/blocks/pipelines/my-lang.yaml
api_version: blocks/v1
kind: pipeline
id: my-lang
name: My Pipeline
spec:
  phases:
    test: { agent: my-tester, when: always }
  execute:
    default_role: my-worker

Discovery order: project (.slmcode/blocks/) → user (~/.slmcode/blocks/) → env → builtin. Project blocks always win, so you can override any builtin for a specific project.

Four block kinds:

Thirteen packs ship built-in — go 🐹, python 🐍, react ⚛️, typescript 🟦, web 🌐, rust 🦀, java ☕, kotlin 🟪, dotnet 🟣, ruby 💎, php 🐘, swift 🕊️, cpp ⚙️. slmcode init picks one by scoring each pack's detect stanza (marker files, detect.contains proof of a file's content, source extensions, author priority), skipping nested sub-projects. Switch with slmcode blocks apply <id> or use the Studio's PackSelector.

→ 🧱 Full blocks reference

05 Self-critic with evidence 🔍¶

worker/deep → reviewer → (reject) → corrector → reviewer …

Reviewers can be flaky on SLMs. Heuristics prefer:

• clear status: done
• files_changed that match disk
• rename satisfaction when paths already moved

Acceptance criteria: a contract, not a paragraph¶

Asking a 7B model "is this implementation correct?" is asking it to do the thing it is worst at. So a task's acceptance is split into individually checkable conditions, each with the exact command that proves it:

{
  "criteria": [
    {"text": "Sum returns a+b for the table cases", "priority": "must", "verify": "go test ./..."},
    {"text": "exported Sum has a doc comment", "priority": "should", "verify": ""}
  ]
}

The harness runs each verify — through the same whitelist every auto-run command passes, so a criterion can never widen shell scope — and hands the reviewer a table with three verdicts, never two:

That third state is the point. A prose acceptance blob is scanned by regex for runnable commands, and a condition it finds none for is simply invisible — so "the harness did not check" silently becomes "the harness says it is fine". An UNVERIFIED row says so out loud, and it denies the reviewer fast path: disk evidence proves the worker changed something, never that the condition it was given is now true.

06 Knowledge flywheel 🦋¶

After a run:

1. MEMORY.md — lessons / pitfalls
2. CONTEXT.md — what we touched
3. SKILLS.md + skills/learned/ — conventions that stuck
4. sessions/ — resumable snapshots

Tomorrow's run starts smarter than today's. That's the product. (Also: please don’t rm -rf .slmcode for sport.)

07 Permissions are a feature 🛡️¶

Shell is separate: shell_permission: allow | ask | deny. Files and shells have different blast radii. Treat them that way.

08 Any LLM, same loop 🔌¶

Providers are adapters. The harness stays constant.

• 🏠 Local SLM → more think_passes, a correct model_profiles.<family>.context_limit, patience
• ☁️ Frontier → raise parallel, enjoy speed, keep inspectability

See Providers and Config.

Next 🗺️¶

• ⏱️ Quick start — feel it
• 🧭 User guide — drive it daily
• 🏗️ Architecture — package map for contributors

☀️ Made with ♥ by UnicoLab