Skip to content

concepts.md

Latest commit

 

History

History
234 lines (171 loc) · 7.89 KB

concepts.md

File metadata and controls

234 lines (171 loc) · 7.89 KB
Raw

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

🏠

House metaphor: don’t ask the intern to also be the architect, QA, and filing cabinet. Give them a desk, a ticket, and a checklist. Then maybe a snack.

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

!!! quote "🎤 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]
Loading

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:

Kind What it defines
pipeline Phase graph, loop agents, slots
agent Custom specialist or builtin override
quality Format/lint/test/build commands
pack Composes pipeline + quality + agents into a language pack

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

!!! tip "📜 Disk beats vibes" Always. If the file says hello and the model says goodbye — trust the file.

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:

Verdict Meaning
PASSED a command ran here and exited 0. Settled.
FAILED it ran and did not. A failed must fails the task.
UNVERIFIED nothing ran. The reviewer judges this one.

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

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 (interactive) or slmcode reject 👀

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

☀️ Made with ♥ by UnicoLab