🧠 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.

Layer	Owner	Job
🧭 Routing / board	Go	Plan, schedule, stop/resume
🧩 Specialists	Prompts + tools	One role, one pack
🔍 Critic	Reviewer + disk evidence	Catch fiction
💾 Memory	`.slmcode/*.md`	Compound lessons

🎤 UnicoLab watercooler

Models are the talent. Harnesses are the stage managers. Never let the talent rearrange the set mid-show.

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 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

📜 Disk beats vibes

Always. If the file says hello and the model says goodbye — trust the file.

06 Knowledge flywheel 🦋¶

After a run:

MEMORY.md — lessons / pitfalls
CONTEXT.md — what we touched
SKILLS.md + skills/learned/ — conventions that stuck
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 🛡️¶

Mode	Use when
`auto`	You trust the loop (or it's a playground) 🛝
`dry-run`	Demos, CI dry checks, “what would you do?” 🎭
`review`	Real repos — stage patches, then `slmcode apply` 👀

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, smaller max_context_kb, 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